mysql2 Documentation

MySQL2 is a high-performance MySQL client for Node.js. It is mostly API compatible with the mysql (Node MySQL) package but provides several additional features:

• Performance: Faster and better performance than the original mysql driver.
• Prepared Statements: Native support for prepared statements.
• Protocol Support: Supports MySQL Binary Log Protocol and MySQL Server features.
• Connectivity: Supports SSL, Authentication Switch, and Compression.
• Advanced API: Includes a Promise Wrapper, Custom Streams, and Connection Pooling.
• Encoding: Extended support for various Encodings and Collations.

The official documentation for the mysql2 package is hosted as a static website built with Docusaurus 3. You can find the full documentation, including guides and API references, at the link below.

https://sidorares.github.io/node-mysql2/docs

MySQL2 is designed to be mostly API compatible with the mysql (Node MySQL) package. However, there is a significant difference in how DECIMAL values are handled to prevent precision loss.

In MySQL2, DECIMAL values (including results from SUM() and AVG() functions applied to INTEGER arguments) are returned as strings. In the original mysql package, these are returned as numbers. Use strings if you need to maintain exact precision for financial or high-precision calculations.

Connection pools reuse existing connections to reduce latency. You can create a pool using mysql.createPool(). You can execute queries directly on the pool or manually acquire a connection using pool.getConnection().

import mysql from 'mysql2/promise';

const pool = mysql.createPool({
  host: 'localhost',
  user: 'root',
  database: 'test',
  waitForConnections: true,
  connectionLimit: 10,
  maxIdle: 10,
  idleTimeout: 60000,
  queueLimit: 0,
  enableKeepAlive: true,
  keepAliveInitialDelay: 0,
});

// Direct query (connection is automatically released)
const [rows] = await pool.query('SELECT 1');

// Manual connection acquisition
const conn = await pool.getConnection();
try {
  await conn.query('SELECT 1');
} finally {
  conn.release(); // or pool.releaseConnection(conn)
}

await pool.end();

In addition to the standard errback interface, mysql2 provides a thin wrapper to expose a Promise-based API. You can access this by importing from mysql2/promise or by using helper methods on the standard module.

/* eslint-env es6 */
const mysql = require('mysql2/promise');

// Create a connection
mysql
  .createConnection({
    /* same parameters as for non-promise createConnection */
  })
  .then((conn) => conn.query('select foo from bar'))
  .then(([rows, fields]) => console.log(rows[0].foo));

MariaDB UUID, INET4, and INET6 values are returned as strings. To insert these values, bind them as strings; MariaDB will automatically convert them to its internal compact representation.

// Reading values
const [rows] = await connection.query('SELECT u, i4, i6 FROM t');
// rows[0].u  === '123e4567-e89b-12d3-a456-426614174000'
// rows[0].i4 === '203.0.113.7'
// rows[0].i6 === '2001:db8::1'

// Inserting values
await connection.execute('INSERT INTO t (u, i4, i6) VALUES (?, ?, ?)', [
  '123e4567-e89b-12d3-a456-426614174000',
  '203.0.113.7',
  '2001:db8::1',
]);

To execute multiple SQL statements in a single query call, you must set the multipleStatements option to true within your ConnectionOptions object when creating a connection.

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

const access: ConnectionOptions = {
  host: '',
  user: '',
  password: '',
  database: '',
  multipleStatements: true,
};

const conn = await mysql.createConnection(access);

Install the mysql2 package as a dependency for your Node.js project. It is free from native bindings and works on Linux, Mac OS, and Windows.

If you are using TypeScript, you must also install @types/node as a development dependency.

npm install --save mysql2

# For TypeScript users
npm install --save-dev @types/node

If you are using TypeScript, you can leverage the Explicit Resource Management proposal (using and await using) to ensure that poolCluster.end() and connection.release() are called automatically when the variables go out of scope. This prevents connection leaks and simplifies cleanup logic.

import mysql from 'mysql2/promise';

{
  // .end() is called automatically when leaving the scope
  await using poolCluster = mysql.createPoolCluster();

  poolCluster.add('clusterA', {
    host: 'localhost',
    user: 'root',
    database: 'test',
  });

  // .release() is called automatically when leaving the scope
  await using connection = await poolCluster.getConnection('clusterA');

  // ... some query
}

Install the mysql2 package via npm. For TypeScript projects, you should also install @types/node as a development dependency.

# JavaScript
npm install --save mysql2

# TypeScript
npm install --save mysql2
npm install --save-dev @types/node