MySQL2

MySQL2 is a high-performance MySQL client for Node.js written entirely in JavaScript, with no native bindings to compile or install. It is a continuation of MySQL-Native with a protocol parser rewritten from scratch, and it is largely API-compatible with the popular mysqljs/mysql driver while adding faster performance and a broader feature set.

Beyond basic querying, MySQL2 supports server-side prepared statements, a promise-based API, connection pooling and pool clusters, SSL/TLS, protocol compression, extended encoding and collation handling, the MySQL binary log protocol, and even acting as a MySQL server. It powers a large share of the Node.js ecosystem and is the underlying driver for many ORMs and query builders.

What You Get

• A pure-JavaScript MySQL/MariaDB driver that installs without native compilation
• Both callback and promise-based APIs, plus connection pooling and pool clusters
• Server-side prepared statements for safer, faster repeated queries
• SSL/TLS, protocol compression, authentication switch, and AWS SSL profiles
• Extended encoding/collation support and the MySQL binary log protocol
• Near drop-in compatibility with the mysqljs/mysql API

Common Use Cases

• Backing web and API servers that read from and write to MySQL or MariaDB
• Serving as the low-level driver under ORMs and query builders such as Sequelize, Drizzle, and Knex
• Running high-throughput workloads that benefit from prepared statements and pooling
• Connecting securely to managed databases (e.g. Amazon RDS/Aurora) over SSL

Under The Hood

Architecture — MySQL2’s entry point (index.js) wires up factory functions (createConnection, createPool, createPoolCluster, createServer) over a core Connection class in lib/connection.js. Each connection owns a PacketParser (lib/packet_parser.js) that incrementally reads bytes off the socket and dispatches complete MySQL protocol packets to a queue of command objects in lib/commands/ (handshake, query, execute, prepare, ping, change_user, binlog_dump, etc.), each modeled as a small state machine extending command.js. Packet encode/decode lives in lib/packets/, result parsing and caching in lib/parsers/, and pooling logic in lib/pool.js / lib/pool_cluster.js, with a parallel promise API layer in lib/promise/ and promise.js.

Tech Stack — The library is authored in JavaScript (with TypeScript typings under typings/) targeting Node.js >= 8 and CommonJS. Runtime dependencies are deliberately small and pure-JS: denque for fast queues, iconv-lite for encodings, long for 64-bit integers, lru.min for statement/parser caches, named-placeholders and sql-escaper for query building/escaping, generate-function for compiled parsers, and aws-ssl-profiles for managed-DB TLS. Build/test tooling includes Rollup, ESLint, Prettier, TypeScript, the Poku test runner, and c8 for coverage.

Code Quality — The project is mature and well-tested, with test/unit and test/integration suites plus Dockerized runs against real MySQL, a test/tsc-build typecheck harness, and CI with Codecov coverage reporting. Cross-runtime tests target Node.js, Bun, and Deno. Code is linted and Prettier-formatted, and the codebase is organized into clearly separated protocol, command, packet, and pooling modules.

API Design — The public API mirrors the widely-known mysqljs/mysql surface, easing migration, and layers a clean promise wrapper on top (require('mysql2/promise')). Common tasks — a first query, prepared statements via execute, and connection pools — require little boilerplate, and extensive multi-language documentation, examples, and an FAQ back up the ergonomics.