mysql8

library2.17.3jsnpmunverified

A community fork of the official mysqljs/mysql package (v2.17.3) to ensure compatibility with MySQL 8 authentication and features. This package provides a pure JavaScript, no-compile MySQL driver for Node.js (>=0.6). It offers connection pooling, prepared statements, streaming, and transaction support. It is an active drop-in replacement for the original mysql package, which has been in maintenance mode. Note that the original mysql package is no longer actively maintained; the mysql8 fork addresses issues like caching_sha2_password support. However, for new projects, the mysql2 package is recommended due to better performance, promise support, and ongoing maintenance.

database

npm install mysql8

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · MYSQL8

mysql8

databasejavascriptv2.17.3

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

mysql

✓ import mysql from 'mysql8'

✗ import mysql from 'mysql'

Default import, ESM syntax. Use 'mysql8' as the package name, not 'mysql'.

createConnection

✓ const mysql = require('mysql8'); const connection = mysql.createConnection({...})

✗ const { createConnection } = require('mysql8');

CommonJS require(). createConnection is a method on the default export, not a named export.

createPool

✓ import mysql from 'mysql8'; const pool = mysql.createPool({...});

✗ import { createPool } from 'mysql8';

Same as createConnection: it's a method on the default mysql object.

Connects to MySQL, runs a query, and logs the result. Uses ESM import and environment variable for password.

import mysql from 'mysql8'; const connection = mysql.createConnection({ host: 'localhost', user: 'root', password: process.env.DB_PASSWORD ?? '', database: 'test' }); connection.connect((err) => { if (err) { console.error('Error connecting: ' + err.stack); return; } console.log('Connected as id ' + connection.threadId); }); connection.query('SELECT 1 + 1 AS solution', (error, results, fields) => { if (error) throw error; console.log('The solution is: ', results[0].solution); }); connection.end();

Debug

Known issues

gotchaThe mysql package (and its forks) use callback-based APIs. Promises are not natively supported. Use util.promisify or wrap in a Promise manually.

fix

Use the mysql2 package or wrap callbacks with util.promisify.

affects: >=2.0.0

gotchaThe package name is 'mysql8', but the code and documentation often refer to 'mysql'. Ensure you import from 'mysql8' and not 'mysql'.

fix

Use `import mysql from 'mysql8'` or `const mysql = require('mysql8')`.

affects: >=2.0.0

deprecatedThe underlying `mysql` package (and this fork) have not adopted ES modules properly; the package does not have an 'exports' field. Using `import mysql from 'mysql8'` may require `esModuleInterop` or a default import workaround in TypeScript.

fix

If using TypeScript, set `esModuleInterop: true` in tsconfig.json or use `import * as mysql from 'mysql8'`.

affects: >=2.0.0

gotchaMySQL 8's default authentication plugin is `caching_sha2_password`. This fork may not handle it correctly; you may need to set `defaultAuthenticationPlugin` or `authSwitchHandler`.

fix

Add `authSwitchHandler: function ({pluginName, pluginData}, cb) { ... }` to connection options, or alter MySQL user to use `mysql_native_password`.

affects: >=2.0.0

Errors

Common errors & fixes

Error: ER_NOT_SUPPORTED_AUTH_MODE: Client does not support authentication protocol requested by server; consider upgrading MySQL client

MySQL 8 default authentication plugin caching_sha2_password is not supported by this driver.

fix

Change the user's authentication plugin: ALTER USER 'user'@'host' IDENTIFIED WITH mysql_native_password BY 'password';

TypeError: mysql.createConnection is not a function

Incorrect import: using named import instead of default import.

fix

Use `const mysql = require('mysql8')` or `import mysql from 'mysql8'`.

TypeError: Cannot read properties of undefined (reading 'query')

Connection not established properly; missing call to `.connect()` or error in connection options.

fix

Ensure connection options are correct and call `connection.connect()` before `connection.query()`.

Upgrade

Version history

2.17.3latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

11 hits · last 30 days

node

Resources

githubhttps://github.com/mysqljs/mysql ↗

packagemysql8 ↗

homepagehttps://github.com/mysqljs/mysql#readme ↗