mariadb

MariaDB Node.js connector

Non-blocking MariaDB and MySQL client for Node.js.

MariaDB and MySQL client, 100% JavaScript, compatible with Node.js 6+, with the Promise API.

Why a New Client?

While there are existing MySQL clients that work with MariaDB, (such as the mysql and mysql2 clients), the MariaDB Node.js Connector offers new functionality, like Insert Streaming and Pipelining while making no compromises on performance.

Insert Streaming

Using a Readable stream in your application, you can stream INSERT statements to MariaDB through the Connector.

    
    https.get('https://someContent', readableStream => {
        //readableStream implement Readable, driver will stream data to database 
        connection.query("INSERT INTO myTable VALUE (?)", [readableStream]);
    });

Pipelining

With Pipelining, the Connector sends commands without waiting for server results, preserving order. For instance, consider the use of executing two INSERT statements.

The Connector doesn't wait for query results before sending the next INSERT statement. Instead, it sends queries one after the other, avoiding much of the network latency.

For more information, see the Pipelining documentation.

Benchmarks

MariaDB provides benchmarks comparing the Connector with popular Node.js MySQL clients, including:

• promise-mysql version 3.3.1 + mysql version 2.15.0
• mysql2 version 1.5.3

promise-mysql  : 1,366 ops/sec ±1.42%
mysql2         : 1,469 ops/sec ±1.63%
mariadb        : 1,802 ops/sec ±1.19%

For more information, see the Benchmarks page.

Quick Start

The MariaDB Connector is available through the Node.js repositories. You can install it using npm :

$ npm install mariadb

Using ECMAScript < 2017:

const mariadb = require('mariadb');
const pool = mariadb.createPool({host: 'mydb.com', user:' myUser', connectionLimit: 5});
pool.getConnection()
    .then(conn => {
    
      conn.query("SELECT 1 as val")
        .then((rows) => {
          console.log(rows); //[ {val: 1}, meta: ... ]
          return conn.query("INSERT INTO myTable value (?, ?)", [1, "mariadb"]);
        })
        .then((res) => {
          console.log(res); // { affectedRows: 1, insertId: 1, warningStatus: 0 }
          conn.end();
        })
        .catch(err => {
          //handle error
          conn.end();
        })
        
    }).catch(err => {
      //not connected
    });

Using ECMAScript 2017:

const mariadb = require('mariadb');
const pool = mariadb.createPool({host: 'mydb.com', user: 'myUser', connectionLimit: 5});

async function asyncFunction() {
  let conn;
  try {
	conn = await pool.getConnection();
	const rows = await conn.query("SELECT 1 as val");
	console.log(rows); //[ {val: 1}, meta: ... ]
	const res = await conn.query("INSERT INTO myTable value (?, ?)", [1, "mariadb"]);
	console.log(res); // { affectedRows: 1, insertId: 1, warningStatus: 0 }

  } catch (err) {
	throw err;
  } finally {
	if (conn) return conn.end();
  }
}

Documentation

The MariaDB Node.js Connector can use different APIs on the back-end: Promise and Callback.
The default API is Promise API.

Callback API is provided for compatibility with the mysql and mysql2 APIs.

Road Map

The Connector remains in development. Here's a list of features being developed for future releases:

• PoolCluster
• MariaDB ed25519 plugin authentication
• Query Timeouts
• Bulk Insertion, (that is, fast batch).

Contributing

If you would like to contribute to the MariaDB Node.js Connector, please follow the instructions given in the Developers Guide.

To file an issue or follow the development, see JIRA.

Changelog

2.0.0-alpha - 20 Sep. 2018

• [CONJS-42] check other connections in pool when an unexpected connection error occur
• [CONJS-44] Create option to permit setting Object to one prepareStatement parameter
• [CONJS-43] Callback API is missing
• [CONJS-39] support geometric GeoJSON structure format
• [CONJS-24] new option "sessionVariables" to permit setting session variable at connection
• [misc] connection.end() immediate resolution on socket QUIT packet send.
• [misc] improve documentation and set Promise API documentation to a dedicated page.
• [misc] change pool implementation to permit node 6 compatibility (removal of async await)