fast mysql driver. Implements core protocol, prepared statements, ssl and compression in native JS

npm install mysql2
37 downloads in the last day
325 downloads in the last week
1 310 downloads in the last month


Build Status TODO:

Mysql client for node.js. Written in native JavaScript and aims to be mostly api compatible with node-mysql



In addition to client-side query/escape and connection pooling

  • MySQL server API for proxies and mocks
  • SSL and compression
  • prepared statements


See node-mysql documentation. If you see api incompatibilities, please report via github issue.


Simple select:

var mysql      = require('mysql2');
var connection = mysql.createConnection({ user: 'test', database: 'test'});

connection.query('SELECT 1+1 as test1', function(err, rows) {

Prepared statement and parameters:

var mysql      = require('mysql2');
var connection = mysql.createConnection({ user: 'test', database: 'test'});

connection.execute('SELECT 1+? as test1', [10], function(err, rows) {

Connecting over encrypted connection:

var fs         = require('fs');
var mysql      = require('mysql2');
var connection = mysql.createConnection({
   user: 'test',
   database: 'test',
   ssl: {
     key: fs.readFileSync('./certs/client-key.pem'),
     cert: fs.readFileSync('./certs/client-cert.pem')
connection.query('SELECT 1+1 as test1', console.log);

You can use 'Amazon RDS' string as value to ssl property to connect to Amazon RDS mysql over ssl (in that case CA cert is used)

var mysql      = require('mysql2');
var connection = mysql.createConnection({
   user: 'foo',
   password: 'bar',
   host: '',
   ssl: 'Amazon RDS'

conn.query('show status like \'Ssl_cipher\'', function(err, res) {
  console.log(err, res);

Connecting using custom stream:

var net        = require('net');
var mysql      = require('mysql2');
var shape      = require('shaper');
var connection = mysql.createConnection({
   user: 'test',
   database: 'test',
   stream: net.connect('/tmp/mysql.sock').pipe(shape(10)) // emulate 10 bytes/sec link
connection.query('SELECT 1+1 as test1', console.log);

Simple mysql proxy server:

var mysql = require('mysql2');

var server = mysql.createServer();
server.on('connection', function(conn) {

    protocolVersion: 10,
    serverVersion: 'node.js rocks',
    connectionId: 1234,
    statusFlags: 2,
    characterSet: 8,
    capabilityFlags: 0xffffff

  conn.on('field_list', function(table, fields) {
    console.log('field list:', table, fields);

  var remote = mysql.createConnection({user: 'root', database: 'dbname', host:'', password: 'secret'});

  conn.on('query', function(sql) {
    console.log('proxying query:' + sql);
    remote.query(sql, function(err) { // overloaded args, either (err, result :object)
                                      // or (err, rows :array, columns :array)
      if (Array.isArray(arguments[1])) {
        // response to a 'select', 'show' or similar
        var rows = arguments[1], columns = arguments[2];
        console.log('rows', rows);
        console.log('columns', columns);
        conn.writeTextResult(rows, columns);
      } else {
        // response to an 'insert', 'update' or 'delete'
        var result = arguments[1];
        console.log('result', result);

  conn.on('end', remote.end.bind(remote));

MySQL Server API


  • createServer() - creates server instance
  • Server.listen - listen port / unix socket (same arguments as net.Server.listen)


  • connect - new incoming connection.


  • serverHandshake({serverVersion, protocolVersion, connectionId, statusFlags, characterSet, capabilityFlags}) - send server handshake initialisation packet, wait handshake response and start listening for commands
  • writeOk({affectedRows: num, insertId: num}) - send OK packet to client
  • writeEof(warnings, statusFlags) - send EOF packet
  • writeTextResult(rows, fields) - write query result to client. Rows and fields are in the same format as in connection.query callback.
  • writeColumns(fields) - write fields + EOF packets.
  • writeTextRow(row) - write array (not hash!) ov values as result row
  • TODO: binary protocol


  • query(sql) - query from client




  • Internal protocol is written from scratch using my experience with mysql-native
  • constants, sql parameters interpolation, pool, connection config class taken from node-mysql (I tried to preserve git history)
  • SSL upgrade code based on @TooTallNate code
  • Secure connection / compressed connection api flags compatible to mariasql client.
  • contributors


Examples using MySQL server API:

  • Mysql-pg-proxy - mysql to postgres proxy server.
  • Mysqlite.js - mysql server with JS-only (emscripten compiled) sqlite backend.
  • sql-engine - mysql server with leveldb backend.

See also:


Feel free to create pull requests. TODO in order of importance:

  • node-mysql api incompatibility fixes
  • documentation
  • tests
  • benchmarks
  • bug fixes
  • TODOs in source code
  • performance improvements
  • features

Features TODO

  • more server side commands support (binary protocol, etc)
  • named parameters interpolarion into unnamed parameters translation for prepared statements

Bitdeli Badge

npm loves you