MySQL2

https://sidorares.github.io/node-mysql2/docs
Admin
MySQL2 is a Node.js MySQL client with focus on performance, supporting prepared statements,...
Tokens:89,292
Snippets:630
Trust Score:9.7
Update:9 minutes ago
Show doc for...
Tokens:
Raw
### Manually acquire connection with using

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

Gets a connection from the pool and uses using for automatic release.

```typescript
// For pool initialization, see above
pool.getConnection(function (err, _conn) {
  using conn = _conn;

  // Do something with the connection
  conn.query(/* ... */);

  // No need to manually release — .release() is called
  // automatically when leaving the scope
});
```

--------------------------------

### Install MySQL2 (JavaScript)

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

Install the mysql2 package for JavaScript projects. Requires npm.

```bash
npm install --save mysql2
```

--------------------------------

### Manually acquire connection with await using

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

Gets a connection from the pool and uses await using for automatic release.

```typescript
// For pool initialization, see above
{
  await using conn = await pool.getConnection();

  // Do something with the connection
  await conn.query(/* ... */);

  // No need to manually release — .release() is called
  // automatically when leaving the scope
}
```

--------------------------------

### Install MySQL2 with TypeScript types

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

Install mysql2 and the @types/node package for TypeScript development. Requires npm.

```bash
npm install --save mysql2
npm install --save-dev @types/node
```

--------------------------------

### Create promise pool from existing pool

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

Creates a pool, then uses pool.promise() to get a Promise-wrapped instance for querying with promises.

```js
import mysql from 'mysql2';

async function main() {
  // create the pool
  const pool = mysql.createPool({
    host: 'localhost',
    user: 'root',
    database: 'test',
  });

  // now get a Promise wrapped instance of that pool
  const promisePool = pool.promise();

  // query database using promises
  const [rows, fields] = await promisePool.query('SELECT 1');
}
```

--------------------------------

### Manually acquire and release connection with Callback API

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

Gets a connection from the pool, uses it, and releases it with pool.releaseConnection().

```javascript
// For pool initialization, see above
pool.getConnection(function (err, conn) {
  // Do something with the connection
  conn.query(/* ... */);

  // Don't forget to release the connection when finished!
  pool.releaseConnection(conn);
});
```

--------------------------------

### Create pool cluster and query with Promise API

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

Creates a pool cluster, adds a MASTER pool, queries all pools with cluster.of('*'), and ends the cluster. Uses the promise API with async/await.

```js
import mysql from 'mysql2/promise';

const cluster = mysql.createPoolCluster();

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

const [rows] = await cluster.of('*').query('SELECT * FROM users');
console.log(rows);

cluster.end();
```

--------------------------------

### Use custom Promise implementation (bluebird)

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

Creates a connection with a custom Promise implementation (bluebird) by passing the Promise option. Executes a parameterized query.

```js
// get the client
import mysql from 'mysql2/promise';

// get the promise implementation, we will use bluebird
import bluebird from 'bluebird';

// create the connection, specify bluebird as Promise
const connection = await mysql.createConnection({
  host: 'localhost',
  user: 'root',
  database: 'test',
  Promise: bluebird,
});

// query database
const [rows, fields] = await connection.execute(
  'SELECT * FROM `table` WHERE `name` = ? AND `age` > ?',
  ['Morty', 14]
);
```

--------------------------------

### Manually acquire and release connection with Promise API

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

Gets a connection from the pool, uses it, and releases it with pool.releaseConnection().

```javascript
// For pool initialization, see above
const conn = await pool.getConnection();

// Do something with the connection
await conn.query(/* ... */);

// Don't forget to release the connection when finished!
pool.releaseConnection(conn);
```

--------------------------------

### Create pool cluster and query with callback API

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

Creates a pool cluster, adds a MASTER pool, queries all pools with cluster.of('*') using a callback, and ends the cluster. Uses the callback API.

```js
const mysql = require('mysql2');

const cluster = mysql.createPoolCluster();

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

cluster.of('*').query('SELECT * FROM users', function (err, rows) {
  console.log(rows);
});

cluster.end();
```

--------------------------------

### Upgrade connection to promise with .promise()

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

Creates a connection, then uses conn.promise() to upgrade it to a promise-based API for querying. Ends the connection after the query.

```js
const mysql = require('mysql2');

// create the connection
const conn = mysql.createConnection({
  host: 'localhost',
  user: 'root',
  database: 'test',
});

conn
  .promise()
  .query('SELECT 1')
  .then(([rows, fields]) => {
    console.log(rows);
  })
  .catch(console.log)
  .then(() => conn.end());
```

--------------------------------

### First query using Callback API

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

Use the callback-based API from 'mysql2' to create a connection and run SELECT queries. The connection is closed inside the placeholder query callback.

```js
// Get the client
const mysql = require('mysql2');

// Create the connection to database
const connection = mysql.createConnection({
  host: 'localhost',
  user: 'root',
  database: 'test',
});

// A simple SELECT query
connection.query(
  'SELECT * FROM `table` WHERE `name` = "Page" AND `age` > 45',
  function (err, results, fields) {
    console.log(results); // results contains rows returned by server
    console.log(fields); // fields contains extra meta data about results, if available
  }
);

// Using placeholders
connection.query(
  'SELECT * FROM `table` WHERE `name` = ? AND `age` > ?',
  ['Page', 45],
  function (err, results) {
    console.log(results);

    // Close the connection
    connection.end();
  }
);
```

--------------------------------

### First query using using (Explicit Resource Management)

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

Use 'using' with the callback API to automatically call .end() when the connection goes out of scope. Requires TypeScript support for Explicit Resource Management.

```ts
import mysql from 'mysql2';

{
  // .end() is called automatically when leaving the scope
  using connection = mysql.createConnection({
    host: 'localhost',
    user: 'root',
    database: 'test',
  });

  // A simple SELECT query
  connection.query(
    'SELECT * FROM `table` WHERE `name` = "Page" AND `age` > 45',
    function (err, results, fields) {
      console.log(results); // results contains rows returned by server
      console.log(fields); // fields contains extra meta data about results, if available
    }
  );

  // Using placeholders
  connection.query(
    'SELECT * FROM `table` WHERE `name` = ? AND `age` > ?',
    ['Page', 45],
    function (err, results) {
      console.log(results);
    }
  );
}
```

--------------------------------

### Create and close a connection pool with mysql2

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

Creates a connection pool with default settings and closes it with pool.end(). The pool creates connections on demand up to connectionLimit.

```javascript
const mysql = require('mysql2');

// Create the connection pool. The pool-specific settings are the defaults
const pool = mysql.createPool({
  host: 'localhost',
  user: 'root',
  database: 'test',
  waitForConnections: true,
  connectionLimit: 10,
  maxIdle: 10, // max idle connections, the default value is the same as `connectionLimit`
  idleTimeout: 60000, // idle connections timeout, in milliseconds, the default value 60000
  queueLimit: 0,
  enableKeepAlive: true,
  keepAliveInitialDelay: 0,
});

// ... some query

// Close the pool
pool.end();
```

--------------------------------

### Create pool cluster with await using (TypeScript)

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

Creates a pool cluster using `await using` so cluster.end() is called automatically when leaving the scope. Uses the promise API.

```ts
import mysql from 'mysql2/promise';

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

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

  const [rows] = await cluster.of('*').query('SELECT * FROM users');
  console.log(rows);
}
```

--------------------------------

### Use pool with await using for automatic cleanup

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

Uses Explicit Resource Management to automatically call pool.end() when leaving the scope.

```typescript
import mysql from 'mysql2/promise';

{
  // pool.end() is called automatically when leaving the scope
  await using pool = mysql.createPool({
    host: 'localhost',
    user: 'root',
    database: 'test',
    waitForConnections: true,
    connectionLimit: 10,
    maxIdle: 10, // max idle connections, the default value is the same as `connectionLimit`
    idleTimeout: 60000, // idle connections timeout, in milliseconds, the default value 60000
    queueLimit: 0,
    enableKeepAlive: true,
    keepAliveInitialDelay: 0,
  });

  // ... some query
}
```

--------------------------------

### Use pool with using for automatic cleanup

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

Uses Explicit Resource Management to automatically call pool.end() when leaving the scope.

```typescript
import mysql from 'mysql2';

{
  // pool.end() is called automatically when leaving the scope
  using pool = mysql.createPool({
    host: 'localhost',
    user: 'root',
    database: 'test',
    waitForConnections: true,
    connectionLimit: 10,
    maxIdle: 10, // max idle connections, the default value is the same as `connectionLimit`
    idleTimeout: 60000, // idle connections timeout, in milliseconds, the default value 60000
    queueLimit: 0,
    enableKeepAlive: true,
    keepAliveInitialDelay: 0,
  });

  // ... some query
}
```

--------------------------------

### First query using Promise API

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

Use the promise-based API from 'mysql2/promise' to create a connection, run a SELECT query with and without placeholders, and close the connection. The query uses '?' placeholders for parameterized values.

```js
// Get the client
import mysql from 'mysql2/promise';

// Create the connection to database
const connection = await mysql.createConnection({
  host: 'localhost',
  user: 'root',
  database: 'test',
});

// A simple SELECT query
try {
  const [results, fields] = await connection.query(
    'SELECT * FROM `table` WHERE `name` = "Page" AND `age` > 45'
  );

  console.log(results); // results contains rows returned by server
  console.log(fields); // fields contains extra meta data about results, if available
} catch (err) {
  console.log(err);
}

// Using placeholders
try {
  const [results] = await connection.query(
    'SELECT * FROM `table` WHERE `name` = ? AND `age` > ?',
    ['Page', 45]
  );

  console.log(results);
} catch (err) {
  console.log(err);
}

// Close the connection
await connection.end();
```

--------------------------------

### Create pool cluster with using (TypeScript)

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

Creates a pool cluster using `using` so cluster.end() is called automatically when leaving the scope. Uses the callback API.

```ts
import mysql from 'mysql2';

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

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

  cluster.of('*').query('SELECT * FROM users', function (err, rows) {
    console.log(rows);
  });
}
```

--------------------------------

### First query using await using (Explicit Resource Management)

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

Use 'await using' with the promise API to automatically call .end() when the connection goes out of scope. Requires TypeScript support for Explicit Resource Management.

```ts
import mysql from 'mysql2/promise';

{
  // .end() is called automatically when leaving the scope
  await using connection = await mysql.createConnection({
    host: 'localhost',
    user: 'root',
    database: 'test',
  });

  // A simple SELECT query
  const [results, fields] = await connection.query(
    'SELECT * FROM `table` WHERE `name` = "Page" AND `age` > 45'
  );

  console.log(results); // results contains rows returned by server
  console.log(fields); // fields contains extra meta data about results, if available

  // Using placeholders
  const [results2] = await connection.query(
    'SELECT * FROM `table` WHERE `name` = ? AND `age` > ?',
    ['Page', 45]
  );

  console.log(results2);
}
```

--------------------------------

### package.json - Dependencies for promise-co-await example

Source: https://sidorares.github.io/node-mysql2/docs/examples/promise-wrapper/co-await

Package manifest for the promise-co-await example. Lists babel-cli as a dependency and sets await.js as the main entry point.

```json
{
  "name": "promise-co-await",
  "version": "1.0.0",
  "description": "",
  "main": "await.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "author": "",
  "license": "ISC",
  "dependencies": {
    "babel-cli": "^6.9.0"
  }
}

```

--------------------------------

### Query pool with Promise API

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

Uses pool.query() with async/await. The connection is automatically released when the query resolves.

```javascript
try {
  // For pool initialization, see above
  const [rows, fields] = await pool.query('SELECT `field` FROM `table`');
  // Connection is automatically released when query resolves
} catch (err) {
  console.log(err);
}
```

--------------------------------

### Query pool with Callback API

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

Uses pool.query() with a callback. The connection is automatically released when the query resolves.

```javascript
// For pool initialization, see above
pool.query('SELECT `field` FROM `table`', function (err, rows, fields) {
  // Connection is automatically released when query resolves
});
```

--------------------------------

### Using Prepared Statements with Promise API

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

Use the `execute` helper to prepare and query a statement with the Promise API. The connection is created with `mysql.createConnection` and closed manually with `connection.end()`. Results and fields are returned as an array.

```javascript
import mysql from 'mysql2/promise';

try {
  // create the connection to database
  const connection = await mysql.createConnection({
    host: 'localhost',
    user: 'root',
    database: 'test',
  });

  // execute will internally call prepare and query
  const [results, fields] = await connection.execute(
    'SELECT * FROM `table` WHERE `name` = ? AND `age` > ?',
    ['Rick C-137', 53]
  );

  console.log(results); // results contains rows returned by server
  console.log(fields); // fields contains extra meta data about results, if available
} catch (err) {
  console.log(err);
}

// Close the connection
await connection.end();
```

--------------------------------

### add() with callback.js

Source: https://sidorares.github.io/node-mysql2/docs/examples/connections/createPoolCluster

Uses the callback API to add a cluster, get a connection, release it, and close the pool cluster. Requires releasing the connection with connection.release() when finished.

```javascript
const mysql = require('mysql2');

const poolCluster = mysql.createPoolCluster();

poolCluster.add('clusterA', {
  host: 'localhost',
  user: 'root',
  database: 'test',
  // port: 3306,
  // password: '',
});
// poolCluster.add('clusterB', '...');

poolCluster.getConnection('clusterA', function (err, connection) {
  if (err instanceof Error) {
    console.log(err);
    return;
  }

  // ... some query

  connection.release();

  // Close the pool cluster
  poolCluster.end();
});
```

--------------------------------

### Creating a Connection Pool with Promise API

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

Create a connection pool with `mysql.createPool` using default pool-specific settings. The pool is closed with `pool.end()`. Settings include `waitForConnections`, `connectionLimit`, `maxIdle`, `idleTimeout`, `queueLimit`, `enableKeepAlive`, and `keepAliveInitialDelay`.

```javascript
import mysql from 'mysql2/promise';

// Create the connection pool. The pool-specific settings are the defaults
const pool = mysql.createPool({
  host: 'localhost',
  user: 'root',
  database: 'test',
  waitForConnections: true,
  connectionLimit: 10,
  maxIdle: 10, // max idle connections, the default value is the same as `connectionLimit`
  idleTimeout: 60000, // idle connections timeout, in milliseconds, the default value 60000
  queueLimit: 0,
  enableKeepAlive: true,
  keepAliveInitialDelay: 0,
});

// ... some query

// Close the pool
await pool.end();
```

--------------------------------

### Using Prepared Statements with Callback API

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

Use the `execute` helper with the callback API. The connection is created with `mysql.createConnection` and closed inside the callback with `connection.end()`. Results and fields are passed to the callback function.

```javascript
const mysql = require('mysql2');

// create the connection to database
const connection = mysql.createConnection({
  host: 'localhost',
  user: 'root',
  database: 'test',
});

// execute will internally call prepare and query
connection.execute(
  'SELECT * FROM `table` WHERE `name` = ? AND `age` > ?',
  ['Rick C-137', 53],
  function (err, results, fields) {
    console.log(results); // results contains rows returned by server
    console.log(fields); // fields contains extra meta data about results, if available

    // Close the connection
    connection.end();
  }
);
```

--------------------------------

### add() with promise.js

Source: https://sidorares.github.io/node-mysql2/docs/examples/connections/createPoolCluster

Creates a pool cluster, adds a cluster named 'clusterA', gets a connection, releases it, and closes the cluster. Requires releasing the connection with connection.release() when finished.

```javascript
import mysql from 'mysql2/promise';

try {
  const poolCluster = mysql.createPoolCluster();

  poolCluster.add('clusterA', {
    host: 'localhost',
    user: 'root',
    database: 'test',
    // port: 3306,
    // password: '',
  });
  // poolCluster.add('clusterB', '...');

  const connection = await poolCluster.getConnection('clusterA');
  // ... some query

  connection.release();

  // Close the pool cluster
  await poolCluster.end();
} catch (err) {
  console.log(err);
}
```

--------------------------------

### Directly release connection using connection object

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

Releases the connection directly using the connection object's release() method.

```javascript
conn.release();
```

--------------------------------

### Clone and run website locally

Source: https://sidorares.github.io/node-mysql2/docs/contributing/website

Commands to clone the MySQL2 repository, create a branch, and start the Docusaurus development server from the website workspace.

```bash
git clone https://github.com/sidorares/node-mysql2.git
git checkout -b website # optional
cd /path-to/node-mysql2/website
npm ci
npm start
```

--------------------------------

### Server.listen

Source: https://sidorares.github.io/node-mysql2/docs/documentation/mysql-server

Starts listening on a port or Unix socket. Accepts the same arguments as net.Server.listen.

```APIDOC
## Server.listen

### Description
Starts listening on a port or Unix socket. Accepts the same arguments as net.Server.listen.

### Method
N/A (method call)

### Endpoint
N/A

### Parameters
Same as net.Server.listen (port, host, backlog, callback, etc.)

### Request Example
N/A

### Response
N/A

### Response Example
N/A
```

--------------------------------

### Create and use a MySQL2 connection pool

Source: https://sidorares.github.io/node-mysql2/docs/examples/tests/pool

Creates a connection pool with mysql2 and demonstrates two ways to run queries: using pool.query() which automatically releases the connection, and using pool.getConnection() with manual release via db.release(). The example runs queries every second in intervals.

```javascript
'use strict';

const pool = require('mysql2').createPool({
  host: 'localhost',
  user: 'root',
  database: 'test',
  password: 'root',
});

setInterval(() => {
  for (let i = 0; i < 5; ++i) {
    pool.query((err, rows, fields) => {
      console.log(rows, fields);
      // Connection is automatically released once query resolves
    });
  }
}, 1000);

setInterval(() => {
  for (let i = 0; i < 5; ++i) {
    pool.getConnection((err, db) => {
      db.query('select sleep(0.5) as qqq', (err, rows, fields) => {
        console.log(rows, fields);
        db.release();
      });
    });
  }
}, 1000);
```

--------------------------------

### execute(options)

Source: https://sidorares.github.io/node-mysql2/docs/examples/queries/prepared-statements/select

Executes a prepared statement using a QueryOptions object. Returns rows and fields from the server.

```APIDOC
## execute(options)

### Description
Executes a prepared statement using a QueryOptions object. Returns rows and fields from the server.

### Method
execute

### Parameters
#### options (QueryOptions) - Required - An object containing query options, including `sql` and `values`.

### Returns
- **rows** - contains rows returned by server
- **fields** - contains extra meta data about rows, if available

### Example (promise.js)
```js
try {
  const sql = 'SELECT * FROM `users` WHERE `name` = ? AND `age` > ?';
  const values = ['Page', 45];

  const [rows, fields] = await connection.execute({
    sql,
    values,
    // ... other options
  });

  console.log(rows);
  console.log(fields);
} catch (err) {
  console.log(err);
}
```

### Example (callback.js)
```js
const sql = 'SELECT * FROM `users` WHERE `name` = ? AND `age` > ?';
const values = ['Page', 45];

connection.execute(
  {
    sql,
    values,
    // ... other options
  },
  (err, rows, fields) => {
    if (err instanceof Error) {
      console.log(err);
      return;
    }

    console.log(rows);
    console.log(fields);
  }
);
```

### Notes
The connection used for the query (`execute`) can be obtained through the `createConnection`, `createPool` or `createPoolCluster` methods.
```

--------------------------------

### Using Prepared Statements with using (Explicit Resource Management)

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

Use `using` to automatically call `.end()` when the connection goes out of scope, leveraging Explicit Resource Management. The connection is created with `mysql.createConnection` and the `execute` helper is used for prepared statements.

```typescript
const mysql = require('mysql2');

{
  // create the connection to database
  // .end() is called automatically when leaving the scope
  using connection = mysql.createConnection({
    host: 'localhost',
    user: 'root',
    database: 'test',
  });

  // execute will internally call prepare and query
  connection.execute(
    'SELECT * FROM `table` WHERE `name` = ? AND `age` > ?',
    ['Rick C-137', 53],
    function (err, results, fields) {
      console.log(results); // results contains rows returned by server
      console.log(fields); // fields contains extra meta data about results, if available
    }
  );
}
```

--------------------------------

### Using Prepared Statements with await using (Explicit Resource Management)

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

Use `await using` to automatically call `.end()` when the connection goes out of scope, leveraging Explicit Resource Management. The connection is created with `mysql.createConnection` and the `execute` helper is used for prepared statements.

```typescript
import mysql from 'mysql2/promise';

{
  // create the connection to database
  // .end() is called automatically when leaving the scope
  await using connection = await mysql.createConnection({
    host: 'localhost',
    user: 'root',
    database: 'test',
  });

  // execute will internally call prepare and query
  const [results, fields] = await connection.execute(
    'SELECT * FROM `table` WHERE `name` = ? AND `age` > ?',
    ['Rick C-137', 53]
  );

  console.log(results); // results contains rows returned by server
  console.log(fields); // fields contains extra meta data about results, if available
}
```

--------------------------------

### query(options)

Source: https://sidorares.github.io/node-mysql2/docs/examples/queries/simple-queries/select

Executes a SQL SELECT query using a QueryOptions object. Returns rows and fields metadata.

```APIDOC
## query(options)

### Description
Executes a SQL SELECT query using a QueryOptions object. Returns rows and fields metadata.

### Method
query

### Signature
query(options: QueryOptions)

### Parameters
- **options** (QueryOptions) - Required - An object containing the SQL query and other options.
  - **sql** (string) - Required - The SQL query string to execute.
  - **... other options** - Optional - Additional query options.

### Returns
- **rows** - Contains rows returned by server
- **fields** - Contains extra meta data about rows, if available

### Example (Promise)
```js
try {
  const sql = 'SELECT * FROM `users` WHERE `name` = "Page" AND `age` > 45';

  const [rows, fields] = await connection.query({
    sql,
    // ... other options
  });

  console.log(rows);
  console.log(fields);
} catch (err) {
  console.log(err);
}
```

### Example (Callback)
```js
const sql = 'SELECT * FROM `users` WHERE `name` = "Page" AND `age` > 45';

connection.query(
  {
    sql,
    // ... other options
  },
  (err, rows, fields) => {
    if (err instanceof Error) {
      console.log(err);
      return;
    }

    console.log(rows);
    console.log(fields);
  }
);
```
```

--------------------------------

### Custom query logger using node:diagnostics_channel tracingChannel

Source: https://sidorares.github.io/node-mysql2/docs/documentation/tracing-channels

Complete example that subscribes to mysql2 tracing channels to build a simple query logger with timing. It tracks active spans in a WeakMap keyed by context, logs query or connect events with duration in milliseconds, and reports failures with the error message. Requires the 'node:diagnostics_channel' and 'mysql2' modules. The example subscribes to 'mysql2:query', 'mysql2:execute', 'mysql2:connect', and 'mysql2:pool:connect' channels, then runs a sample query to demonstrate the output.

```javascript
const diagnostics_channel = require('node:diagnostics_channel');
const mysql = require('mysql2');

// Track all active spans
const activeSpans = new WeakMap();

function subscribeChannel(name) {
  const channel = diagnostics_channel.tracingChannel(name);

  channel.subscribe({
    start(ctx) {
      activeSpans.set(ctx, {
        channel: name,
        query: ctx.query || null,
        database: ctx.database,
        server: `${ctx.serverAddress}:${ctx.serverPort}`,
        startTime: process.hrtime.bigint(),
      });
    },
    end() {},
    asyncStart() {},
    asyncEnd(ctx) {
      const span = activeSpans.get(ctx);
      if (span) {
        const duration = Number(process.hrtime.bigint() - span.startTime) / 1e6;
        console.log(
          `[${span.channel}] ${span.query || 'connect'} - ${duration.toFixed(1)}ms`
        );
        activeSpans.delete(ctx);
      }
    },
    error(ctx) {
      const span = activeSpans.get(ctx);
      if (span) {
        const duration = Number(process.hrtime.bigint() - span.startTime) / 1e6;
        console.error(
          `[${span.channel}] FAILED ${span.query || 'connect'} - ${duration.toFixed(1)}ms: ${ctx.error.message}`
        );
        activeSpans.delete(ctx);
      }
    },
  });
}

// Subscribe to all channels
subscribeChannel('mysql2:query');
subscribeChannel('mysql2:execute');
subscribeChannel('mysql2:connect');
subscribeChannel('mysql2:pool:connect');

// All mysql2 operations are now traced
const connection = mysql.createConnection({
  host: 'localhost',
  user: 'root',
  database: 'test',
});

connection.query('SELECT * FROM users WHERE id = ?', [1], (err, rows) => {
  // Logs: [mysql2:query] SELECT * FROM users WHERE id = ? - 3.2ms
});
```

--------------------------------

### execute(options, values)

Source: https://sidorares.github.io/node-mysql2/docs/examples/queries/prepared-statements/select

Executes a prepared statement with a QueryOptions object and a separate values array. Returns rows and fields from the server.

```APIDOC
## execute(options, values)

### Description
Executes a prepared statement with a QueryOptions object and a separate values array. Returns rows and fields from the server.

### Method
execute

### Parameters
#### options (QueryOptions) - Required - An object containing query options, including `sql`.
#### values (any[]) - Required - Array of values to substitute for placeholders

### Returns
- **rows** - contains rows returned by server
- **fields** - contains extra meta data about rows, if available

### Example (promise.js)
```js
try {
  const sql = 'SELECT * FROM `users` WHERE `name` = ? AND `age` > ?';
  const values = ['Page', 45];

  const [rows, fields] = await connection.execute(
    {
      sql,
      // ... other options
    },
    values
  );

  console.log(rows);
  console.log(fields);
} catch (err) {
  console.log(err);
}
```

### Example (callback.js)
```js
const sql = 'SELECT * FROM `users` WHERE `name` = ? AND `age` > ?';
const values = ['Page', 45];

connection.execute(
  {
    sql,
    // ... other options
  },
  values,
  (err, rows, fields) => {
    if (err instanceof Error) {
      console.log(err);
      return;
    }

    console.log(rows);
    console.log(fields);
  }
);
```

### Notes
The connection used for the query (`execute`) can be obtained through the `createConnection`, `createPool` or `createPoolCluster` methods.
```

--------------------------------

### execute(sql, values)

Source: https://sidorares.github.io/node-mysql2/docs/examples/queries/prepared-statements/select

Executes a prepared statement with a SQL string and an array of values. Returns rows and fields from the server.

```APIDOC
## execute(sql, values)

### Description
Executes a prepared statement with a SQL string and an array of values. Returns rows and fields from the server.

### Method
execute

### Parameters
#### sql (string) - Required - The SQL query string with placeholders (?)
#### values (any[]) - Required - Array of values to substitute for placeholders

### Returns
- **rows** - contains rows returned by server
- **fields** - contains extra meta data about rows, if available

### Example (promise.js)
```js
try {
  const sql = 'SELECT * FROM `users` WHERE `name` = ? AND `age` > ?';
  const values = ['Page', 45];

  const [rows, fields] = await connection.execute(sql, values);

  console.log(rows);
  console.log(fields);
} catch (err) {
  console.log(err);
}
```

### Example (callback.js)
```js
const sql = 'SELECT * FROM `users` WHERE `name` = ? AND `age` > ?';
const values = ['Page', 45];

connection.execute(sql, values, (err, rows, fields) => {
  if (err instanceof Error) {
    console.log(err);
    return;
  }

  console.log(rows);
  console.log(fields);
});
```

### Notes
The connection used for the query (`execute`) can be obtained through the `createConnection`, `createPool` or `createPoolCluster` methods.
```

--------------------------------

### query(options)

Source: https://sidorares.github.io/node-mysql2/docs/examples/queries/simple-queries/insert

Executes an INSERT SQL query using a QueryOptions object. Returns a ResultSetHeader object and optional field metadata.

```APIDOC
## query(options)

### Description
Executes an INSERT SQL query using a QueryOptions object. Returns a ResultSetHeader object and optional field metadata.

### Method
query

### Parameters
#### options (QueryOptions) - Required - An object containing the SQL query and other options.

### Request Example
```js
const sql = 'INSERT INTO `users`(`name`, `age`) VALUES ("Josh", 19), ("Page", 45)';
const [result, fields] = await connection.query({ sql });
```

### Response
#### Success Response
- **result** (ResultSetHeader) - Contains details about the operation executed by the server.
- **fields** (array) - Extra metadata about the operation, if available.

#### Response Example
```js
console.log(result);
console.log(fields);
```
```

--------------------------------

### createServer()

Source: https://sidorares.github.io/node-mysql2/docs/documentation/mysql-server

Creates a new MySQL server instance. This is the entry point for setting up a MySQL-compatible server.

```APIDOC
## createServer()

### Description
Creates a new MySQL server instance. This is the entry point for setting up a MySQL-compatible server.

### Method
N/A (function call)

### Endpoint
N/A

### Parameters
None

### Request Example
N/A

### Response
Returns a server instance.

### Response Example
N/A
```

--------------------------------

### Trace Connection Establishment with mysql2:connect

Source: https://sidorares.github.io/node-mysql2/docs/documentation/tracing-channels

Subscribes to the 'mysql2:connect' tracing channel to log connection attempts. The start callback logs the server address, port, and user; asyncEnd logs successful connection; error logs failures.

```javascript
const diagnostics_channel = require('node:diagnostics_channel');

const connectChannel = diagnostics_channel.tracingChannel('mysql2:connect');

connectChannel.subscribe({
  start(ctx) {
    console.log(
      `Connecting to ${ctx.serverAddress}:${ctx.serverPort} as ${ctx.user}`
    );
  },
  end() {},
  asyncStart() {},
  asyncEnd(ctx) {
    console.log(`Connected to ${ctx.serverAddress}:${ctx.serverPort}`);
  },
  error(ctx) {
    console.error(`Connection failed:`, ctx.error.message);
  },
});
```

--------------------------------

### Create a MySQL server with authentication and query handling

Source: https://sidorares.github.io/node-mysql2/docs/examples/tests/server

Sets up a MySQL server using mysql2's createServer, listens on port 3333, and handles connections with a custom authentication callback. The authenticate function verifies a password using doubleSha1 and verifyToken, and returns an error code 1045 for invalid credentials. The 'query' event writes columns and text rows, then closes the connection.

```javascript
'use strict';

const mysql = require('mysql2');
const flags = require('mysql2/lib/constants/client.js');
const auth = require('mysql2/lib/auth_41.js');

function authenticate(params, cb) {
  console.log(params);
  const doubleSha = auth.doubleSha1('pass123');
  const isValid = auth.verifyToken(
    params.authPluginData1,
    params.authPluginData2,
    params.authToken,
    doubleSha
  );
  if (isValid) {
    cb(null);
  } else {
    // for list of codes lib/constants/errors.js
    cb(null, { message: 'wrong password dude', code: 1045 });
  }
}

const server = mysql.createServer();
server.listen(3333);
server.on('connection', (conn) => {
  // we can deny connection here:
  // conn.writeError({ message: 'secret', code: 123 });
  // conn.close();
  conn.serverHandshake({
    protocolVersion: 10,
    serverVersion: '5.6.10', // 'node.js rocks',
    connectionId: 1234,
    statusFlags: 2,
    characterSet: 8,
    // capabilityFlags: 0xffffff,
    // capabilityFlags: -2113931265,
    capabilityFlags: 2181036031,
    authCallback: authenticate,
  });

  conn.on('field_list', (table, fields) => {
    console.log('FIELD LIST:', table, fields);
    conn.writeEof();
  });

  conn.on('query', (query) => {
    conn.writeColumns([
      {
        catalog: 'def',
        schema: 'test',
        table: 'test_table',
        orgTable: 'test_table',
        name: 'beta',
        orgName: 'beta',
        characterSet: 33,
        columnLength: 384,
        columnType: 253,
        flags: 0,
        decimals: 0,
      },
    ]);
    conn.writeTextRow(['test тест テスト փորձարկում পরীক্ষা kiểm tra ']);
    conn.writeTextRow(['ტესტი પરીક્ષણ  מבחן פּרובירן اختبار परीक्षण']);
    conn.writeEof();
    conn.close();
  });
});
```

--------------------------------

### await.js - Using async/await with mysql2/promise

Source: https://sidorares.github.io/node-mysql2/docs/examples/promise-wrapper/co-await

Shows how to use the mysql2 promise wrapper with async/await. Creates a connection, runs queries, catches errors, and demonstrates that commands are queued per connection (parallel sleep calls are not actually parallel). Also creates a pool and runs parallel queries. Requires a MySQL server with user 'testuser' and password 'testpassword' on port 3306.

```javascript
'use strict';

const mysql = require('mysql2/promise');

async function test() {
  const c = await mysql.createConnection({
    port: 3306,
    user: 'testuser',
    namedPlaceholders: true,
    password: 'testpassword',
  });
  console.log('connected!');
  const [rows, fields] = await c.query('show databases');
  console.log(rows);

  try {
    const [rows, fields] = await c.query('some invalid sql here');
  } catch (e) {
    console.log('caught exception!', e);
  }

  console.log(await c.execute('select sleep(0.5)'));
  console.log('after first sleep');
  console.log(await c.execute('select sleep(0.5)'));
  console.log('after second sleep');
  let start = +new Date();
  console.log(
    await Promise.all([
      c.execute('select sleep(2.5)'),
      c.execute('select sleep(2.5)'),
    ])
  );
  console.log(
    'after 2+3 parallel sleep which is in fact not parallel because commands are queued per connection'
  );
  let end = +new Date();
  console.log(end - start);
  await c.end();

  const p = mysql.createPool({
    port: 3306,
    user: 'testuser',
    namedPlaceholders: true,
    password: 'testpassword',
  });
  console.log(await p.execute('select sleep(0.5)'));
  console.log('after first pool sleep');
  start = +new Date();
  console.log(
    await Promise.all([
      p.execute('select sleep(2.5)'),
      p.execute('select sleep(2.5)'),
    ])
  );
  console.log('after 2+3 parallel pool sleep');
  end = +new Date();
  console.log(end - start);
  await p.end();
}

test()
  .then(() => {
    console.log('done');
  })
  .catch((err) => {
    console.log('error!', err);
    throw err;
  });

```

--------------------------------

### Run tests

Source: https://sidorares.github.io/node-mysql2/docs/contributing/website

Runs the test suite for the website.

```bash
npm run test
```

--------------------------------

### Add pool cluster with SSL using callback API

Source: https://sidorares.github.io/node-mysql2/docs/examples/connections/createPoolCluster

Uses the callback style with mysql2. Adds a cluster with SSL config, gets a connection, and releases it. Remember to call connection.release() and poolCluster.end().

```javascript
const mysql = require('mysql2');

const poolCluster = mysql.createPoolCluster();

poolCluster.add('clusterA', {
  // ...
  ssl: {
    // key: fs.readFileSync('./certs/client-key.pem'),
    // cert: fs.readFileSync('./certs/client-cert.pem')
    ca: fs.readFileSync('./certs/ca-cert.pem'),
  },
});
// poolCluster.add('clusterB', '...');

poolCluster.getConnection('clusterA', function (err, connection) {
  if (err instanceof Error) {
    console.log(err);
    return;
  }

  // ... some query

  connection.release();

  // Close the pool cluster
  poolCluster.end();
});
```

--------------------------------

### co.js - Using co with generator functions

Source: https://sidorares.github.io/node-mysql2/docs/examples/promise-wrapper/co-await

Shows how to use the mysql2 promise wrapper with the co library and generator functions. Creates a connection, runs queries, and uses named placeholders. Requires a MySQL server with user 'root' on port 3306.

```javascript
'use strict';

const mysql = require('mysql2/promise');
const co = require('co');

co(function* () {
  const c = yield mysql.createConnection({
    port: 3306,
    user: 'root',
    namedPlaceholders: true,
  });
  const rows = yield c.query('show databases');
  console.log(rows);
  console.log(yield c.execute('select 1+:toAdd as qqq', { toAdd: 10 }));
  yield c.end();
})
  .then(function () {
    console.log('done');
  })
  .catch(function (err) {
    console.log(err);
    throw err;
  });

```

--------------------------------

### Add pool cluster with SSL using promise API

Source: https://sidorares.github.io/node-mysql2/docs/examples/connections/createPoolCluster

Creates a pool cluster, adds a cluster with SSL configuration, gets a connection, and releases it. Remember to call connection.release() and poolCluster.end() to clean up.

```javascript
import mysql from 'mysql2/promise';

try {
  const poolCluster = mysql.createPoolCluster();

  poolCluster.add('clusterA', {
    // ...
    ssl: {
      // key: fs.readFileSync('./certs/client-key.pem'),
      // cert: fs.readFileSync('./certs/client-cert.pem')
      ca: fs.readFileSync('./certs/ca-cert.pem'),
    },
  });
  // poolCluster.add('clusterB', '...');

  const connection = await poolCluster.getConnection('clusterA');
  // ... some query

  connection.release();

  // Close the pool cluster
  await poolCluster.end();
} catch (err) {
  console.log(err);
}
```

--------------------------------

### Enable rowsAsArray at connection level (Callback)

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

Sets rowsAsArray: true on the connection using the callback API. Use when two columns share the same name to prevent clashing. This is a deviation from the Node MySQL library.

```javascript
const conn = mysql.createConnection({
  host: 'localhost',
  database: 'test',
  user: 'root',
  rowsAsArray: true,
});
```

--------------------------------

### add(group, connectionUri) with callback.js

Source: https://sidorares.github.io/node-mysql2/docs/examples/connections/createPoolCluster

Creates a pool cluster, adds a group named 'clusterA', and gets a connection using a callback. Uses the callback API of mysql2. Remember to call connection.release() and poolCluster.end().

```javascript
const mysql = require('mysql2');

const poolCluster = mysql.createPoolCluster();

poolCluster.add('clusterA', 'mysql://root:password@localhost:3306/test');
// poolCluster.add('clusterB', '...');

poolCluster.getConnection('clusterA', function (err, connection) {
  if (err instanceof Error) {
    console.log(err);
    return;
  }

  // ... some query

  connection.release();

  // Close the pool cluster
  poolCluster.end();
});
```

--------------------------------

### Enable rowsAsArray at query level (Callback)

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

Sets rowsAsArray: true on a single query using the callback API. The query selects two columns with the same name (foo). Results will be an array of arrays; fields are unchanged.

```javascript
conn.query(
  {
    sql: 'SELECT 1 AS `foo`, 2 AS `foo`',
    rowsAsArray: true,
  },
  function (err, results, fields) {
    console.log(results); // in this query, results will be an array of arrays rather than an array of objects
    console.log(fields); // fields are unchanged
  }
);
```

--------------------------------

### Clear and build the website

Source: https://sidorares.github.io/node-mysql2/docs/contributing/website

Clears the build cache and builds the website. Included in the GitHub Actions workflow.

```bash
npm run clear
npm run build
```

--------------------------------

### add() with using

Source: https://sidorares.github.io/node-mysql2/docs/examples/connections/createPoolCluster

Uses Explicit Resource Management with using to automatically call .end() and .release() when leaving the scope, so cleanup is never forgotten.

```typescript
const mysql = require('mysql2');

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

  poolCluster.add('clusterA', {
    host: 'localhost',
    user: 'root',
    database: 'test',
    // port: 3306,
    // password: '',
  });
  // poolCluster.add('clusterB', '...');

  poolCluster.getConnection('clusterA', function (err, _connection) {
    if (err instanceof Error) {
      console.log(err);
      return;
    }

    // .release() is called automatically when leaving the scope
    using connection = _connection;

    // ... some query
  });
}
```
Tokens:
Raw