Mariadb Connector Nodejs Usage

MariaDB Connector/Node.js

Last updated: 2026-08-10

MariaDB Connector/Node.js is the official Node.js driver for MariaDB — the mariadb package on npm, LGPL-licensed and non-blocking. This skill covers the connector-specific behavior and the traps that bite generated application code. For installing it, choosing an entry point, and configuring TLS and pool sizing, see mariadb-connector-nodejs-install. It is pure JavaScript and does not depend on MariaDB Connector/C — no native build step, no C toolchain required.

Default context: Assume the 3.5.x line (current: 3.5.4) unless the user states otherwise; it requires Node.js >= 20. Connector versions are independent of the MariaDB server version — a 3.5.x connector talks to any currently supported MariaDB server release.

What LLMs Often Miss

Connection essentials

import mariadb from 'mariadb';

const pool = mariadb.createPool({
  host: process.env.DB_HOST,
  user: process.env.DB_USER,
  password: process.env.DB_PWD,
  database: 'appdb',
  connectionLimit: 10   // default shown for clarity
});

// pool.query() auto-acquires and auto-releases a connection
async function getUser(id) {
  const rows = await pool.query('SELECT id, name FROM users WHERE id = ?', [id]);
  return rows[0]; // rows is an array; rows.meta holds column metadata
}

// Transaction: explicit getConnection() + release() in finally
async function transferFunds(fromId, toId, amount) {
  const conn = await pool.getConnection();
  try {
    await conn.beginTransaction();
    await conn.query('UPDATE accounts SET balance = balance - ? WHERE id = ?', [amount, fromId]);
    await conn.query('UPDATE accounts SET balance = balance + ? WHERE id = ?', [amount, toId]);
    await conn.commit();
  } catch (err) {
    await conn.rollback();
    throw err;
  } finally {
    conn.release(); // returns the connection to the pool
  }
}

// Bulk insert: batch(), not a query() loop
async function insertItems(basketId, itemIds) {
  await pool.batch(
    'INSERT INTO basket_item(basketId, itemId) VALUES (?, ?)',
    itemIds.map((itemId) => [basketId, itemId])
  );
}

// Explicit prepared statement, reused across calls
async function lookupMany(ids) {
  const conn = await pool.getConnection();
  try {
    const prep = await conn.prepare('SELECT id, name FROM users WHERE id = ?');
    try {
      const results = [];
      for (const id of ids) {
        results.push(await prep.execute([id]));
      }
      return results;
    } finally {
      prep.close();          // releases the server-side prepared statement
    }
  } finally {
    conn.release();
  }
}

// Streaming a large result set
const stream = conn.queryStream('SELECT id, payload FROM big_table');
try {
  for await (const row of stream) {
    await handle(row);
  }
} catch (err) {
  stream.close();            // otherwise the connection can hang
  throw err;
}

See Also

• mariadb-connector-nodejs-install — installing the package, entry points and typings, TLS, and pool configuration
• mariadb-transactions — the server-side semantics behind beginTransaction()/commit()/rollback() and isolation levels
• mariadb-prepare — server-side prepared statements, what execute() uses under the hood
• Canonical reference on mariadb.com/docs, consult for edge cases not covered here: https://mariadb.com/docs/connectors/mariadb-connector-nodejs

This page is: Copyright © 2026 MariaDB. All rights reserved.