# node-mysql2: a pure JavaScript MySQL driver for Node.js

> MySQL2 is the maintained fork of the original mysqljs driver, rewritten around a TypeScript protocol parser. It is aimed at Node.js services that need prepared statements, connection pools and a promise API without native bindings.

**sidorares/node-mysql2** — :zap: fast mysqljs/mysql compatible mysql driver for node.js

- Repository: https://github.com/sidorares/node-mysql2
- Website: https://sidorares.github.io/node-mysql2/
- Stars: 4,387 · Forks: 681
- Language: TypeScript
- License: MIT
- Published: 2026-09-23 · Updated: 2026-09-23 · Language: en
- Canonical page: https://hysenlabs.com/projects/sidorares-node-mysql2

## What MySQL2 replaces, and what it does not

The README frames the project as a continuation of MySQL-Native, with the protocol parser rewritten from scratch and the API changed to match the older mysqljs/mysql package. That lineage matters when you are choosing a driver. If your codebase already calls connection.query and connection.end, MySQL2 is mostly a drop-in replacement, and the README states that the two teams work together to factor out shared code under the mysqljs organisation.

The scope is a wire protocol client, not a data layer. It speaks the MySQL protocol, handles prepared statements, binary log events, compression, SSL and pooling. It does not model your tables, generate SQL for you, or run migrations. Teams that pick it up expecting an ORM will be disappointed, and that is a deliberate boundary rather than a missing feature.

It is for backend engineers running Node.js against MySQL or MariaDB who want control over the SQL they send and the connections they hold. It is a poor fit for anyone who wants the database abstracted away.

## How the driver is put together

The repository is a CommonJS package with TypeScript sources under src/ and compiled output at the package root: index.js, index.d.ts, promise.js and promise.d.ts. The package.json main field points at index.js and the typings field at typings/mysql/index, so both the callback and the promise entry points ship with type definitions.

The README lists the capabilities that come out of that protocol layer: prepared statements, the MySQL binary log protocol, a MySQL server implementation, extended encoding and collation support, a promise wrapper, compression, SSL with an authentication switch, custom streams and pooling. The server-side piece is the one people overlook. The same parser that reads result packets from a server can be pointed the other way, which is why the repository has a mysql-server documentation page.

The build is split. Source is compiled with tsc through the src:build script, and a rollup config exists for a bundled build. Tests run under poku, with separate scripts for Node, Bun and Deno, plus docker compose files for integration runs. That multi-runtime test setup is a reasonable signal about which environments the maintainers care about, though the README itself only promises installation on Linux, macOS and Windows.

## Installing MySQL2 and running a first query

There are no native bindings, so installation is a single npm command. The README states the package installs on Linux, macOS and Windows without issues, which removes the node-gyp step that older native drivers required.

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

TypeScript users need the Node type definitions as a development dependency. The README calls this out explicitly.

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

From there, the quickstart covers a first query, prepared statements and connection pools. The pool is the pattern most services want, because it keeps a set of connections open and hands them out per request instead of reconnecting for every statement. The exact pool API is documented on the pooling page rather than in the README, so read that page before wiring it into a request handler.

One design decision to note early: the package exposes two entry points. The default require gives you the callback API, and requiring mysql2/promise gives you the promise wrapper. Pick one and stay consistent, because mixing them in the same module is a common source of confusion.

## Where MySQL2 is the wrong choice

The README does not document rollback behaviour, connection retry semantics or what happens to in-flight queries when a pool connection is destroyed. If your service depends on precise failure handling, you will be reading the source or the test suite rather than the documentation. That is a real gap for anyone running this in production against a flaky network.

Prepared statements are supported, but the README does not present them as a default. Whether a given query is sent as a prepared statement or as interpolated SQL is something you choose at the call site, and getting that wrong reintroduces the injection surface the feature exists to close.

The driver also assumes you are talking to MySQL or MariaDB over their protocol. If your architecture is built around a connection proxy, an HTTP-based database gateway or a serverless driver that speaks a different transport, MySQL2's socket-and-protocol model will not fit, and the pooling model assumes long-lived processes rather than short-lived function invocations.

Finally, the project does not manage schema. If you need migrations, seed data and a typed model layer, MySQL2 sits underneath those tools rather than replacing them.

## MySQL2 against an ORM such as Sequelize or Prisma

The honest comparison is not driver against driver, because MySQL2 is compatible with the older mysqljs package and the difference there is mostly feature coverage: prepared statements, the binary log protocol, a promise wrapper and the server implementation are the additions the README lists.

The more useful comparison is against an ORM or query builder such as Sequelize or Prisma. Those tools give you a model layer, migrations, relation loading and generated types. They also decide what SQL runs. MySQL2 gives you a connection and a query method, and you decide everything else. The trade is explicit: more control over statements and fewer moving parts, in exchange for writing your own data access layer and your own migration story.

Prisma in particular does not use the MySQL protocol from your process in the same way, since it relies on a query engine binary. MySQL2 has no such component, which is the point of the pure JavaScript implementation. If your deployment target is a constrained container where adding a binary is awkward, that difference is the deciding factor.

## Maintenance, licence and upgrade cost

The repository is not archived and the last push was on 2026-09-22. Releases are frequent and versioned as 3.x, with v3.24.4 published on 2026-09-08, v3.24.3 on 2026-09-02 and v3.24.2 on 2026-08-24. A Changelog.md sits at the repository root, so upgrade notes have a home.

The package is MIT licensed, which places few restrictions on commercial use, though the repository also carries a SECURITY.md, so security reports have a defined channel. Nothing here is legal advice; read the License file if your organisation has specific requirements.

Upgrade cost within the 3.x line looks low, since the release cadence is steady and the API is stable by design for compatibility with mysqljs/mysql. The larger cost is the missing documentation around failure modes noted above: when something goes wrong at the connection layer, the answer is likely in the test suite rather than the docs. Budget for that if you are running this at scale.

## Deciding whether to adopt it

MySQL2 is the right pick when you want a MySQL client in Node.js with no compilation step, a promise API available at mysql2/promise, and explicit control over pooling and prepared statements. It is also the natural choice when you are migrating from the mysqljs/mysql package, since the README states the APIs are mostly compatible.

It is the wrong pick when you want the database abstracted, when your queries run in a short-lived serverless context that the pooling model does not suit, or when you need documented retry and rollback semantics out of the box.

Before you start, check three things: the Node.js version your runtime reports, whether your codebase should use the callback entry point or mysql2/promise, and whether your server's authentication plugin is covered by the authentication switch page. Those three answers determine how much of the quickstart you can follow unchanged.

## Conclusion

Adopt MySQL2 if you are writing a Node.js service against MySQL or MariaDB and want a driver with no native build step, a promise API and prepared statements. Skip it if you need an ORM, a query builder, migrations or schema management; MySQL2 is a protocol client and does none of that. Before committing, verify the Node.js version your runtime reports against the engines field, confirm whether you need the callback or promise entry point, and check that your authentication plugin is covered by the authentication switch documentation.

## FAQ

### Can I use MySQL with Node.js?

Yes. MySQL2 is a MySQL client for Node.js that implements the core protocol, prepared statements, SSL and compression in native JavaScript, so no native bindings are needed.

### How do I connect Node.js to a database with MySQL2?

Install the package with npm install --save mysql2, then follow the quickstart pages for the first query, prepared statements and connection pools. The README points to a first query page and a pooling page rather than inlining the connection code.

### Can I connect to MySQL from JavaScript?

MySQL2 is written in TypeScript and runs from JavaScript, and the README notes it installs on Linux, macOS and Windows without issues. TypeScript users additionally need @types/node as a development dependency.

## Sources

- [License: MIT](https://github.com/sidorares/node-mysql2/blob/master/LICENSE)
- [Project website](https://sidorares.github.io/node-mysql2/)
- [README](https://github.com/sidorares/node-mysql2/blob/master/README.md)
- [Releases](https://github.com/sidorares/node-mysql2/releases)
- [sidorares/node-mysql2 on GitHub](https://github.com/sidorares/node-mysql2)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/sidorares-node-mysql2