Open-source project
sidorares/node-mysql2 avatar
sidorares/node-mysql2

mysql2 and the Node.js MySQL driver it was written to replace

:zap: fast mysqljs/mysql compatible mysql driver for node.js

4,392 stars683 forksTypeScriptMIT

At a glance

What is it?
mysql2 is a pure JavaScript MySQL driver for Node.js that keeps the mysqljs/mysql API surface while adding prepared statements, binary log protocol and a promise wrapper. It suits teams migrating an existing Node MySQL codebase or starting one from scratch.
Who is it for?
Adopt mysql2 if you are writing or maintaining Node.js code that talks to MySQL and want prepared statements, pooling and a promise wrapper behind the mysqljs/mysql API you already know. Do not adopt it if your queries need a Node MySQL feature outside the majority that mysql2 supports, and do not assume every documented Node MySQL flag survived the rewrite.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 2 days ago.
What is it written in?
Mainly TypeScript, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 14, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • sidorares/node-mysql24,392 ★ · +6
Star history
Repository2026-09-232026-11-14
sidorares/node-mysql24.4k4.4k

6 Stars in the last 52 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

A protocol parser rewritten to match the mysqljs/mysql surface

mysql2 began as a continuation of MySQL-Native, then had its protocol parser rewritten from scratch while keeping the API shaped after the popular Node MySQL driver. That decision explains most of what follows. The package description in package.json reads "fast mysql driver. Implements core protocol, prepared statements, ssl and compression in native JS", which is a claim about pure JavaScript, not about a wrapper around anything older.

The cost of matching an API you did not design is that some of it is inherited rather than chosen. Constants, the SQL parameter interpolation, the pooling code and the ConnectionConfig class were taken from Node MySQL, and the SSL upgrade path is based on code published by TooTallNate as a gist. Secure connection and compressed connection API flags line up with the node-mariasql client. The result is a driver that feels familiar to mysqljs/mysql users and carries a few conventions from two other projects at the same time.

The MySQL2 team is also working with the Node MySQL team to factor shared code out under the mysqljs organization, so the two drivers are not sealed off from each other.

What the pure JavaScript build gives up and what it avoids

The README states that mysql2 is free from native bindings and installs on Linux, Mac OS or Windows without any issues. The package is at version 3.24.6, released on 2026-10-13, and the last push to master was on 2026-11-02. That removes the compile toolchain problem that native MySQL addons carry on Alpine images and on Windows hosts where a C++ build is unwelcome. It also removes the ABI mismatch class of bug entirely, since there is no compiled artifact to drift against the Node version.

What you trade for that is direct control over the wire protocol, because the protocol code is the project's own rather than a binding to libmysqlclient. That is where prepared statements, the MySQL binary log protocol and compression come from. The repository layout backs this up: a src/ directory, a lib/ directory, typings under typings/, index.d.ts and promise.d.ts at the root, plus a rollup.config.mjs for packaging.

One detail a skim misses: the package is written in TypeScript while shipping as CommonJS. package.json sets "type": "commonjs", with "main": "index.js" and "typings": "typings/mysql/index".

Installing the package and opening the first connection

Installation is a single npm command, and there is no second step because there is nothing to compile.

bash
npm install --save mysql2

If your project is written in TypeScript, the README adds a separate type dependency for the Node runtime definitions.

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

The promise API lives behind a separate entry point, promise.js at the root, rather than being mixed into the callback code. Which of the two you import decides how every query returns.

The documentation site at sidorares.github.io/node-mysql2 carries a Quickstart with a First Query page, a Using Prepared Statements page and a Using Connection Pools page, alongside documentation pages for the promise wrapper, the authentication switch, custom streams and TypeScript examples. Those pages are translated into Simplified Chinese and Brazilian Portuguese, which tells you the maintainers treat the docs as part of the product rather than an afterthought. The README does not document a rollback procedure, so if you are evaluating the driver for a production switch, read the compatibility notes yourself rather than waiting for a documented escape hatch.

Prepared statements, binary log and the server mode the driver can enter

The feature list is where mysql2 parts company with a plain mysqljs/mysql setup, and two entries on it are unusual. MySQL Binary Log Protocol means the driver can subscribe to change events rather than only issuing queries. MySQL Server is listed as a separate feature with its own documentation page. For a Node.js application that needs replication awareness, that is a capability change, not a performance tweak.

Prepared statements are the everyday one. They are documented on their own page and again in the Quickstart.

Extended support for encoding and collation is listed alongside them, which matters when a schema carries latin1 or other legacy collations. A promise wrapper sits beside the callback API as a separate import, so an existing codebase can migrate call sites one at a time. SSL and authentication switch support is what lets the driver follow a server that replies with an auth method the client did not request.

Pooling, streams and the connection shape inherited from Node MySQL

Pooling is not a bolt-on here. The pool implementation and the ConnectionConfig class were taken directly from Node MySQL. Using Connection Pools has its own Quickstart page because the pool object has its own lifecycle, separate from a single connection.

Custom streams appear in the feature list and again on an extras page in the documentation.

The API compatibility claim in the README is a majority claim, not a total one: mysql2 is "mostly API compatible with Node MySQL and supports majority of features". Read that as a careful statement. Anything your old code depends on that sits outside that majority, particularly driver-specific hooks, is where a migration will stall, and the README does not enumerate the exceptions.

The test suite needs a live MySQL server, not a mock

The scripts in package.json give away how the project is verified. The default test script is poku, the JavaScript test runner, and coverage runs through c8. Alongside those sit Docker variants that bring up a real server first: a docker compose file at test/docker-compose.yml, started with --abort-on-container-exit and torn down afterwards, and separate targets for Node, for bun and for deno.

That means contributors are expected to exercise the driver against an actual MySQL, not against a stubbed socket. Benchmarks have their own entry point, node ./benchmarks/benchmark.js, which keeps performance work separate from correctness work.

The repository also ships 4 agent instruction files at the root, AGENTS.md, CLAUDE.md, .cursorrules and .windsurfrules, alongside .agents/ and .claude/ directories. Automated coding agents are part of how work is handed off here.

How the driver differs from mysqljs/mysql and from a native binding

The alternative this project actually competes with is mysqljs/mysql, the driver it was written to match. The difference in approach is not that mysql2 is faster on a benchmark table. The difference is that the protocol implementation is its own code in pure JavaScript, which is what makes prepared statements, compression and the binary log protocol part of the same package rather than dependent on an addon, and which is why the package at version 3.24.6 installs identically on Linux, Mac OS and Windows with no toolchain.

A native binding library is the other approach, and it trades the other way. It can offload work to a C library, but it brings a compile step, platform-specific binaries and an ABI surface that has to track Node releases. mysql2 removes that surface entirely and accepts whatever a JavaScript implementation costs.

Neither choice removes the hard part, which is protocol correctness against a real server. mysql2's answer to that is the docker-compose test path and the benchmark script. When choosing, the deciding question is not speed but whether your deployment can tolerate a JavaScript protocol implementation at all, and whether you need the binary log or server mode features that mysqljs/mysql does not carry.

Editorial conclusion

Adopt mysql2 if you are writing or maintaining Node.js code that talks to MySQL and want prepared statements, pooling and a promise wrapper behind the mysqljs/mysql API you already know. Do not adopt it if your queries need a Node MySQL feature outside the majority that mysql2 supports, and do not assume every documented Node MySQL flag survived the rewrite. Before anything else, read src/ and lib/ for the connection options your application actually sets, then run the first query against a real server and confirm the authentication switch and collation paths behave as your deployment expects.

Frequently asked questions

How do I install mysql2 in a Node.js project?

Run npm install --save mysql2. The package has no native bindings, so the README states it installs on Linux, Mac OS or Windows without any issues and needs no compile step.

Does mysql2 support promises or only callbacks?

It ships both. A promise wrapper is listed among the driver's additional features and has its own documentation page, separate from the callback API whose shape follows Node MySQL.

Is mysql2 a drop-in replacement for mysqljs/mysql?

Mostly. The README describes it as mostly API compatible with Node MySQL and supporting the majority of features, with the protocol parser rewritten from scratch and pooling, ConnectionConfig and SQL parameter interpolation taken from the original.

Do I need extra packages to use mysql2 with TypeScript?

The README says to install @types/node as a dev dependency, and the package ships its own typings at typings/mysql/index along with index.d.ts and promise.d.ts. TypeScript examples live on the documentation site.

Official sources

  1. License: MIT
  2. Project website
  3. README
  4. Releases
  5. sidorares/node-mysql2 on GitHub
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/sidorares-node-mysql2.svg)](https://hysenlabs.com/projects/sidorares-node-mysql2)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/sidorares-node-mysql2.svg)](https://hysenlabs.com/projects/sidorares-node-mysql2)

Was this useful?