MySQL Memory Server

Common errors

• Timeout exceeded

  cause The MySQL database took longer than the default test framework timeout to start or initialize.
  fix Increase the timeout settings for your test runner (e.g., `jest.setTimeout(30000)` for Jest) or for the operation itself.

• Error: process already killed

  cause A race condition or an underlying issue caused the MySQL process to be terminated unexpectedly before `stop()` was fully handled, often seen on Windows.
  fix Upgrade to `mysql-memory-server` v1.12.1 or newer, which contains a fix for this specific Windows-related issue.

• Lock not released on binary redirect URL fetch failure

  cause During the download of MySQL binaries on Alpine Linux, a failure occurred, and the internal lock was not properly released, leading to subsequent issues.
  fix Upgrade to `mysql-memory-server` v1.13.0 or newer, which addresses this lock-release bug on Alpine Linux.

• Errors when stopping the MySQL database on Windows with Node 23.x

  cause Specific issues were identified in older versions preventing clean shutdown of the MySQL database on Windows when running Node.js 23.x.
  fix Update to `mysql-memory-server` v1.12.2 or higher to resolve database stopping errors on Windows with Node.js 23.x.

• Database not starting in Windows Server 2025

  cause Compatibility issues with Windows Server 2025 prevented the MySQL database from initiating correctly in older package versions.
  fix Upgrade to `mysql-memory-server` v1.10.0 or higher to ensure compatibility and correct database startup on Windows Server 2025.

Warnings

• gotcha When `mysql-memory-server` downloads MySQL binaries (i.e., the version is not pre-installed), specific system dependencies are required on Linux distributions. For Ubuntu, `libnuma-dev` and `libaio-dev` are critical. Refer to the official documentation for a full list of prerequisites for your OS.
  Fix: Install required system packages, e.g., `sudo apt-get install libnuma-dev libaio-dev` on Ubuntu before running.
• gotcha Database initialization can take time, especially on first-time binary downloads or slower systems. Jest (and other test runners) might report 'Timeout exceeded' errors. This is usually due to the default test timeout being too short.
  Fix: Increase the timeout for your test suite or individual tests. For Jest, use `jest.setTimeout(ms)` in your setup file or test block.
• breaking The package requires Node.js version 16.6.0 or higher, or Bun version 1.0.0 or higher. Older Node.js versions are not supported and will result in runtime errors.
  Fix: Upgrade your Node.js runtime to 16.6.0 or newer. Consider using a version manager like nvm or fnm.
• gotcha Specific fixes related to stopping the MySQL database on Windows with Node.js 23.x were introduced in v1.12.2. Running on affected versions might lead to resources not being properly released or errors on shutdown.
  Fix: Ensure you are using `mysql-memory-server` version 1.12.2 or newer, especially if running on Windows with Node.js 23.x.

Install

• npm install mysql-memory-server npm
• yarn add mysql-memory-server yarn
• pnpm add mysql-memory-server pnpm

Imports

• createDB
  wrong:

  const { createDB } = require('mysql-memory-server')

  correct:

  import { createDB } from 'mysql-memory-server'

  The primary function to start a new ephemeral MySQL instance. Supports both ESM and CJS.
• MySQLDB

  import type { MySQLDB } from 'mysql-memory-server'

  TypeScript interface for the resolved database instance object, providing properties like `port`, `dbName`, and `stop()`.
• ServerOptions

  import type { ServerOptions } from 'mysql-memory-server'

  TypeScript interface for the configuration object passed to `createDB`.

Quickstart

Demonstrates how to spin up an ephemeral MySQL instance, connect to it using `mysql2/promise`, run a simple query, and then properly shut down the database. Requires `mysql2` as a separate dependency.

import { createDB } from 'mysql-memory-server';
import sql from 'mysql2/promise'; // Remember to `npm install mysql2`

async function runEphemeralMySQL() {
  // Create a new database with default options, or specify a version
  const db = await createDB({
    version: '8.4.x' // Example: specify a MySQL 8.4 version
  });

  console.log(`MySQL server started on port: ${db.port}, database: ${db.dbName}`);

  // Connect to the new database
  const connection = await sql.createConnection({
    host: '127.0.0.1',
    user: db.username,
    port: db.port,
    database: db.dbName,
    password: '' // Default password is an empty string
  });

  try {
    // Run your queries here
    const [rows] = await connection.execute('SELECT 1 + 1 AS solution');
    console.log('Query result:', rows);

    await connection.execute('CREATE TABLE users (id INT PRIMARY KEY, name VARCHAR(255))');
    console.log('Table "users" created.');

  } finally {
    // Once done, disconnect from the database
    await connection.end();
    console.log('Database connection closed.');

    // Then stop the database instance
    await db.stop();
    console.log('MySQL server stopped.');
  }
}

runEphemeralMySQL().catch(console.error);