README.md

MySQL2 ORM

An ORM built on MySQL2, designed to be intuitive, productive and focused on essential functionality.

• This project uses mysql2/promise, createPool and execute behind the scenes.

---

🎲 Documentation Website

---

Table of Contents

• Why
• Documentation
• Quickstart
  • Installation
  • Import
  • Connect
  • Basic Usage Example
  • Close the Connection
• Curiosity
  • Why a dice?
• Acknowledgements

---

Why

• An user-friendly ORM for INSERT, SELECT, UPDATE, DELETE and WHERE clauses.
• Automatic Prepared Statements (including LIMIT and OFFSET).
• You can also simply use QueryBuilder to mount your queries and use them in your original MySQL2 connection.
• It will smartly detect and release the connection when using commit or rollback in a transaction.
• It exposes the execute and query original methods from MySQL2 Pool class.
• Strictly Typed: No usage of any, as neither satisfies at all.

---

Documentation

See detailed specifications and usage in Documentation section for queries, advanced concepts and much more.

---

Quickstart

Installation

npm i mysql2-orm

If you are using TypeScript, you will need to install @types/node.

npm i -D @types/node

---

Import

import { MySQL } from 'mysql2-orm';

---

Connect

const pool = new MySQL({
  host: '',
  user: '',
  database: '',
  // ...
});

---

Basic Usage Example

The following example is based on TypeScript and ES Modules, but you can also use JavaScript and CommonJS.

const user = await pool.select({
  table: 'users',
  where: OP.eq('id', 16),
  limit: 1,
});

• See all available operators (OP) here.
• Due to limit: 1, it returns a direct object with the row result.
• The result of getUser will be a RowDataPacket or false.

It's equivalent to:

import mysql, { RowDataPacket } from 'mysql2/promise';

const pool = mysql.createPool({
  // ...
});

const [users] = execute<RowDataPacket[]>(
  'SELECT * FROM `users` WHERE `id` = ? LIMIT ?',
  [16, '1']
);

const user = users?.[0] || false;

---

Close the Connection

await pool.end();

---

Curiosity

Why a dice?

While in English dice and data each have their own word, in Brazil, both the dice and "data" are called "dado" even though they refer to different things:

	🇺🇸 English	🇧🇷 Portuguese (BR)
💾	data	dado
🎲	dice	dado

---

Acknowledgements

• MySQL2 is maintained by @sidorares.
• The operator names eq, ne, gt, lt, gte and lte are inspired by Sequelize.
• Contributors.