{"id":16450,"library":"mysql-memory-server","title":"MySQL Memory Server","description":"mysql-memory-server is a JavaScript/TypeScript library designed to spin up ephemeral MySQL databases programmatically, primarily for testing, continuous integration, and local development. It automatically downloads the necessary MySQL binaries from MySQL's CDN if a specified version is not already installed on the system, supporting a wide range of MySQL versions from 5.7.19 up to 9.6.0. The package supports Linux, macOS, and Windows environments, including Alpine Linux. It is actively maintained with frequent releases, often introducing support for the latest MySQL versions and fixing platform-specific issues. The current stable version is 1.14.1. Key differentiators include its ability to manage multiple concurrent database instances, automatic shutdown upon process exit, and robust cross-platform compatibility.","status":"active","version":"1.14.1","language":"javascript","source_language":"en","source_url":"https://github.com/Sebastian-Webster/mysql-memory-server-nodejs","tags":["javascript","MySQL","ephemeral database","continuous integration","CI","CI/CD","memory database","typescript"],"install":[{"cmd":"npm install mysql-memory-server","lang":"bash","label":"npm"},{"cmd":"yarn add mysql-memory-server","lang":"bash","label":"yarn"},{"cmd":"pnpm add mysql-memory-server","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The primary function to start a new ephemeral MySQL instance. Supports both ESM and CJS.","wrong":"const { createDB } = require('mysql-memory-server')","symbol":"createDB","correct":"import { createDB } from 'mysql-memory-server'"},{"note":"TypeScript interface for the resolved database instance object, providing properties like `port`, `dbName`, and `stop()`.","symbol":"MySQLDB","correct":"import type { MySQLDB } from 'mysql-memory-server'"},{"note":"TypeScript interface for the configuration object passed to `createDB`.","symbol":"ServerOptions","correct":"import type { ServerOptions } from 'mysql-memory-server'"}],"quickstart":{"code":"import { createDB } from 'mysql-memory-server';\nimport sql from 'mysql2/promise'; // Remember to `npm install mysql2`\n\nasync function runEphemeralMySQL() {\n  // Create a new database with default options, or specify a version\n  const db = await createDB({\n    version: '8.4.x' // Example: specify a MySQL 8.4 version\n  });\n\n  console.log(`MySQL server started on port: ${db.port}, database: ${db.dbName}`);\n\n  // Connect to the new database\n  const connection = await sql.createConnection({\n    host: '127.0.0.1',\n    user: db.username,\n    port: db.port,\n    database: db.dbName,\n    password: '' // Default password is an empty string\n  });\n\n  try {\n    // Run your queries here\n    const [rows] = await connection.execute('SELECT 1 + 1 AS solution');\n    console.log('Query result:', rows);\n\n    await connection.execute('CREATE TABLE users (id INT PRIMARY KEY, name VARCHAR(255))');\n    console.log('Table \"users\" created.');\n\n  } finally {\n    // Once done, disconnect from the database\n    await connection.end();\n    console.log('Database connection closed.');\n\n    // Then stop the database instance\n    await db.stop();\n    console.log('MySQL server stopped.');\n  }\n}\n\nrunEphemeralMySQL().catch(console.error);\n","lang":"typescript","description":"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."},"warnings":[{"fix":"Install required system packages, e.g., `sudo apt-get install libnuma-dev libaio-dev` on Ubuntu before running.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Increase the timeout for your test suite or individual tests. For Jest, use `jest.setTimeout(ms)` in your setup file or test block.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Upgrade your Node.js runtime to 16.6.0 or newer. Consider using a version manager like nvm or fnm.","message":"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.","severity":"breaking","affected_versions":"<16.6.0"},{"fix":"Ensure you are using `mysql-memory-server` version 1.12.2 or newer, especially if running on Windows with Node.js 23.x.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0 <1.12.2"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Increase the timeout settings for your test runner (e.g., `jest.setTimeout(30000)` for Jest) or for the operation itself.","cause":"The MySQL database took longer than the default test framework timeout to start or initialize.","error":"Timeout exceeded"},{"fix":"Upgrade to `mysql-memory-server` v1.12.1 or newer, which contains a fix for this specific Windows-related issue.","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.","error":"Error: process already killed"},{"fix":"Upgrade to `mysql-memory-server` v1.13.0 or newer, which addresses this lock-release bug on Alpine Linux.","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.","error":"Lock not released on binary redirect URL fetch failure"},{"fix":"Update to `mysql-memory-server` v1.12.2 or higher to resolve database stopping errors on Windows with Node.js 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.","error":"Errors when stopping the MySQL database on Windows with Node 23.x"},{"fix":"Upgrade to `mysql-memory-server` v1.10.0 or higher to ensure compatibility and correct database startup on Windows Server 2025.","cause":"Compatibility issues with Windows Server 2025 prevented the MySQL database from initiating correctly in older package versions.","error":"Database not starting in Windows Server 2025"}],"ecosystem":"npm"}