or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

callbacks.mdclustering.mdconfiguration.mdconnections.mderrors.mdindex.mdpooling.mdqueries.mdtypes.md
tile.json

tessl/npm-mariadb

Fast MariaDB and MySQL connector for Node.js with Promise and callback APIs

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/mariadb@3.4.x

To install, run

npx @tessl/cli install tessl/npm-mariadb@3.4.0

index.mddocs/

MariaDB Node.js Connector

MariaDB Node.js Connector is a high-performance MariaDB and MySQL connector for Node.js applications. It offers both Promise-based and callback-based APIs with TypeScript definitions, featuring advanced capabilities like insert streaming, pipelining, bulk inserts, and zero-configuration SSL.

Package Information

  • Package Name: mariadb
  • Package Type: npm
  • Language: JavaScript with TypeScript definitions
  • Installation: npm install mariadb

Core Imports

// Promise-based API (main entry point)
const mariadb = require("mariadb");
const { createConnection, createPool, createPoolCluster, importFile, SqlError, version } = require("mariadb");

ES Modules:

import * as mariadb from "mariadb";
import { createConnection, createPool, createPoolCluster, importFile, SqlError, version } from "mariadb";

Callback-based API:

const mariadb = require("mariadb/callback");
const { createConnection, createPool, createPoolCluster, importFile, SqlError, version } = require("mariadb/callback");

Basic Usage

const mariadb = require("mariadb");

// Create connection
const connection = await mariadb.createConnection({
  host: "localhost",
  user: "root", 
  password: "password",
  database: "test"
});

// Execute query
const rows = await connection.query("SELECT * FROM users WHERE age > ?", [18]);
console.log(rows);

// Close connection
await connection.end();

Architecture

The MariaDB connector is built around several key components:

  • Connection API: Individual database connections with Promise or callback interfaces
  • Pool API: Connection pooling for efficient resource management and scalability
  • Cluster API: Pool clustering for load balancing and high availability
  • Configuration System: Comprehensive options for connection behavior, timeouts, and data formatting
  • Type System: Full TypeScript support with detailed type definitions for all APIs
  • Error Handling: Structured error objects with SQL state codes and detailed error information

Capabilities

Connection Management

Core database connection functionality for establishing, managing, and executing queries on individual database connections. Supports both Promise-based and callback-based APIs.

function createConnection(config: string | ConnectionConfig): Promise<Connection>;

interface Connection {
  query<T>(sql: string | QueryOptions, values?: any): Promise<T>;
  execute<T>(sql: string | QueryOptions, values?: any): Promise<T>;
  beginTransaction(): Promise<void>;
  commit(): Promise<void>;
  rollback(): Promise<void>;
  end(): Promise<void>;
}

Connection Management

Connection Pooling

Connection pooling system for managing multiple database connections efficiently. Provides automatic connection lifecycle management, configurable pool sizing, and resource optimization.

function createPool(config: string | PoolConfig): Pool;

interface Pool {
  getConnection(): Promise<PoolConnection>;
  query<T>(sql: string | QueryOptions, values?: any): Promise<T>;
  execute<T>(sql: string | QueryOptions, values?: any): Promise<T>;
  end(): Promise<void>;
  totalConnections(): number;
  activeConnections(): number;
  idleConnections(): number;
}

Connection Pooling

Pool Clustering

Pool clustering functionality for load balancing across multiple database pools and high availability scenarios. Supports node management, failover, and flexible connection routing.

function createPoolCluster(config?: PoolClusterConfig): PoolCluster;

interface PoolCluster {
  add(id: string, config: PoolConfig): void;
  remove(pattern: string): void;
  getConnection(pattern?: string, selector?: string): Promise<PoolConnection>;
  of(pattern?: string, selector?: string): FilteredPoolCluster;
  end(): Promise<void>;
}

Pool Clustering

Configuration Options

Comprehensive configuration system covering connection parameters, timeouts, data formatting, SSL settings, and performance tuning options.

interface ConnectionConfig {
  host?: string;
  port?: number;
  user?: string;
  password?: string;
  database?: string;
  ssl?: boolean | SSLConfig;
  connectTimeout?: number;
  queryTimeout?: number;
  // ... extensive configuration options
}

function defaultOptions(config?: ConnectionConfig): any;

Configuration

Query Operations

Advanced querying capabilities including prepared statements, batch operations, streaming queries, and transaction management with comprehensive type safety.

interface QueryOptions {
  sql: string;
  nestTables?: boolean;
  typeCast?: TypeCastFunction;
  rowsAsArray?: boolean;
  timeout?: number;
}

interface Prepare {
  execute<T>(values?: any): Promise<T>;
  executeStream(values?: any): Readable;
  close(): void;
}

Query Operations

Error Handling

Structured error handling with detailed SQL error information, error codes, and connection state management for robust application development.

interface SqlError extends Error {
  code: string | null;
  errno: number;
  sqlState?: string | null;
  sqlMessage: string | null;
  sql: string | null;
  fatal: boolean;
}

const SqlError: SqlErrorConstructor;

Error Handling

SQL File Import

Import and execute SQL files directly into the database. Supports both Promise-based and callback-based APIs for database initialization and migration tasks.

/** Import SQL file (Promise-based) */
function importFile(config: ImportFileConfig): Promise<void>;

interface ImportFileConfig extends ConnectionConfig {
  /** SQL file path to import */
  file: string;
}

SQL File Import

Callback API

Complete callback-based API matching the Promise API but using Node.js-style callbacks. All async methods use (err, result, meta?) => void callback signature.

// Callback-based entry points
function createConnection(config: string | ConnectionConfig): Connection; // Returns callback-based Connection
function createPool(config: string | PoolConfig): Pool; // Returns callback-based Pool
function createPoolCluster(config?: PoolClusterConfig): PoolCluster; // Returns callback-based PoolCluster
function importFile(config: ImportFileConfig, callback: (err: SqlError | null) => void): void;

Callback API

Package Constants

Core package constants and utilities exported by the mariadb module.

/** Package version string */
const version: string;

/** SQL Error constructor class */
const SqlError: SqlErrorConstructor;

/** Get default connection options */
function defaultOptions(config?: ConnectionConfig): any;

Type Definitions

Type Definitions

interface UpsertResult {
  affectedRows: number;
  insertId: number | bigint;
  warningStatus: number;
}

interface ConnectionInfo {
  threadId: number | null;
  status: number;
  serverVersion: ServerVersion;
  serverCapabilities: number;
  isMariaDB(): boolean;
  hasMinVersion(major: number, minor: number, patch: number): boolean;
}

interface ServerVersion {
  raw: string;
  mariaDb: boolean;
  major: number;
  minor: number;
  patch: number;
}

interface FieldInfo {
  collation: Collation;
  columnLength: number;
  columnType: TypeNumbers;
  scale: number;
  type: Types;
  flags: Flags;
  db(): string;
  table(): string;
  name(): string;
  string(): string | null;
  buffer(): Buffer | null;
  float(): number | null;
  int(): number | null;
  date(): Date | null;
}