or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

connections.mdindex.mdpool-clusters.mdpools.mdpromises.mdqueries.mdserver.mdsql-utilities.md
tile.json

tessl/npm-mysql2

Fast MySQL client for Node.js with support for prepared statements, SSL, compression, and promise-based APIs

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/mysql2@3.14.x

To install, run

npx @tessl/cli install tessl/npm-mysql2@3.14.0

index.mddocs/

MySQL2

MySQL2 is a fast MySQL client for Node.js that provides comprehensive database connectivity with focus on performance. It supports prepared statements, non-UTF8 encodings, binary log protocol, compression, SSL, and offers both callback-based and Promise-based APIs for maximum flexibility in modern JavaScript applications.

Package Information

  • Package Name: mysql2
  • Package Type: npm
  • Language: JavaScript/TypeScript
  • Installation: npm install mysql2

Core Imports

Callback-based API (main module)

const mysql = require('mysql2');

ES modules:

import * as mysql from 'mysql2';
import { createConnection, createPool, createPoolCluster } from 'mysql2';

Promise-based API

const mysql = require('mysql2/promise');

ES modules:

import * as mysql from 'mysql2/promise';
import { createConnection, createPool, createPoolCluster } from 'mysql2/promise';

Basic Usage

Simple Connection

const mysql = require('mysql2');

// Create a connection
const connection = mysql.createConnection({
  host: 'localhost',
  user: 'your_username',
  password: 'your_password',
  database: 'your_database'
});

// Execute a query
connection.query('SELECT * FROM users WHERE id = ?', [1], (error, results, fields) => {
  if (error) throw error;
  console.log(results);
});

connection.end();

Promise-based Usage

const mysql = require('mysql2/promise');

async function main() {
  const connection = await mysql.createConnection({
    host: 'localhost',
    user: 'your_username',
    password: 'your_password',
    database: 'your_database'
  });

  const [rows, fields] = await connection.execute('SELECT * FROM users WHERE id = ?', [1]);
  console.log(rows);
  
  await connection.end();
}

Connection Pool

const mysql = require('mysql2');

const pool = mysql.createPool({
  host: 'localhost',
  user: 'your_username',
  password: 'your_password',
  database: 'your_database',
  connectionLimit: 10
});

pool.query('SELECT * FROM users', (error, results) => {
  if (error) throw error;
  console.log(results);
});

Architecture

MySQL2 is built around several key components:

  • Connection Management: Single connections, connection pools, and pool clusters for scalability
  • Query Execution: Support for both text queries and prepared statements with parameter binding
  • Protocol Implementation: Native JavaScript implementation of MySQL client/server protocol
  • Type System: Comprehensive TypeScript definitions with full type safety
  • Authentication: Multiple authentication methods including caching_sha2_password and mysql_native_password
  • Compression & SSL: Built-in support for connection compression and SSL/TLS encryption
  • Binary Log: Support for MySQL binary log protocol for replication scenarios

Capabilities

Database Connections

Core connection functionality for establishing and managing database connections with flexible configuration options.

function createConnection(config: ConnectionOptions | string): Connection;
const connect = createConnection; // Alias for createConnection
function createQuery(sql: string, values?: any[]): Query;
interface ConnectionOptions {
  host?: string;
  port?: number;
  user?: string;
  password?: string;
  database?: string;
  charset?: string;
  timezone?: string;
  ssl?: SslOptions | string;
  acquireTimeout?: number;
  timeout?: number;
  // ... additional options
}

interface ConnectionConfig extends ConnectionOptions {
  mergeFlags(defaultFlags: string[], userFlags: string[] | string): number;
  getDefaultFlags(options?: ConnectionOptions): string[];
  getCharsetNumber(charset: string): number;
  getSSLProfile(name: string): { ca: string[] };
  parseUrl(url: string): {
    host: string;
    port: number;
    database: string;
    user: string;
    password: string;
    [key: string]: any;
  };
}

Database Connections

Connection Pools

Connection pooling for scalable database access with automatic connection management and load balancing.

function createPool(config: PoolOptions | string): Pool;
interface PoolOptions extends ConnectionOptions {
  connectionLimit?: number;
  waitForConnections?: boolean;
  queueLimit?: number;
  maxIdle?: number;
  idleTimeout?: number;
}

Connection Pools

Pool Clusters

Pool cluster management for multiple connection pools with pattern-based routing and load balancing across multiple databases.

function createPoolCluster(config?: PoolClusterOptions): PoolCluster;
interface PoolClusterOptions {
  canRetry?: boolean;
  removeNodeErrorCount?: number;
  restoreNodeTimeout?: number;
  defaultSelector?: string;
}

Pool Clusters

Query Execution

Comprehensive query execution with support for text queries, prepared statements, and parameter binding.

// Connection methods
query(sql: string, values?: any[], callback?: function): Query;
execute(sql: string, values?: any[], callback?: function): void;
interface QueryOptions {
  sql: string;
  values?: any[];
  timeout?: number;
  typeCast?: boolean | function;
}

Query Execution

SQL Utilities

SQL string manipulation and escaping utilities for safe query construction and SQL injection prevention.

function escape(value: any, stringifyObjects?: boolean, timeZone?: string): string;
function escapeId(value: any, forbidQualified?: boolean): string;
function format(sql: string, values?: any[], stringifyObjects?: boolean, timeZone?: string): string;
function raw(sql: string): { toSqlString: () => string };

SQL Utilities

Promise Integration

Promise-based wrappers providing modern async/await support for all database operations.

// Promise module functions
function createConnection(config: ConnectionOptions | string): Promise<PromiseConnection>;
function createPool(config: PoolOptions | string): PromisePool;
function createPoolCluster(config?: PoolClusterOptions): PromisePoolCluster;

Promise Integration

Server Creation

MySQL server implementation for creating custom MySQL protocol servers and handling client connections.

function createServer(handler?: (connection: Connection) => void): Server;

Server Creation

Constants and Types

// MySQL data types
const Types: {
  DECIMAL: number;
  TINY: number;
  SHORT: number;
  LONG: number;
  FLOAT: number;
  DOUBLE: number;
  NULL: number;
  TIMESTAMP: number;
  LONGLONG: number;
  INT24: number;
  DATE: number;
  TIME: number;
  DATETIME: number;
  YEAR: number;
  NEWDATE: number;
  VARCHAR: number;
  BIT: number;
  VECTOR: number;
  JSON: number;
  NEWDECIMAL: number;
  ENUM: number;
  SET: number;
  TINY_BLOB: number;
  MEDIUM_BLOB: number;
  LONG_BLOB: number;
  BLOB: number;
  VAR_STRING: number;
  STRING: number;
  GEOMETRY: number;
  // ... additional types
};

// MySQL charsets
const Charsets: {
  [key: string]: number;
  BIG5_CHINESE_CI: number;
  LATIN1_SWEDISH_CI: number;
  UTF8_GENERAL_CI: number;
  UTF8MB4_GENERAL_CI: number;
  // ... hundreds of charset constants
};

// Charset to encoding mappings
const CharsetToEncoding: {
  [key: number]: string;
};

Authentication Plugins

interface AuthPlugin {
  (pluginMetadata: {
    connection: Connection;
    command: string;
  }): Buffer | Promise<Buffer>;
}

const authPlugins: {
  caching_sha2_password: AuthPlugin;
  mysql_clear_password: AuthPlugin;
  mysql_native_password: AuthPlugin;
  sha256_password: AuthPlugin;
};

Parser Cache Management

function setMaxParserCache(max: number): void;
function clearParserCache(): void;