mysql-ddl-checker

library1.0.12jsnpmunverified

A tool to analyze MySQL DDL statements and determine the online DDL algorithm (INSTANT, INPLACE, COPY) and lock types used during schema changes. It connects to a MySQL server, simulates DDL operations by creating temporary table copies, and reports the algorithm and lock strategy. Current version 1.0.12 is stable but in early development. Unlike general MySQL profiling tools, it focuses specifically on DDL impact, but requires a live MySQL connection and creates temporary tables, so it's intended for test environments only. The package ships TypeScript definitions.

database

npm install mysql-ddl-checker

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · MYSQL-DDL-CHECKER

mysql-ddl-checker

databasejavascriptv1.0.12

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default (checkDDL)

✓ import checkDDL from 'mysql-ddl-checker'

✗ const { checkDDL } = require('mysql-ddl-checker')

Default export is a function that takes a DDL string and returns analysis results. The package does not export other named symbols.

DDLResult

✓ import type { DDLResult } from 'mysql-ddl-checker'

✗ import { DDLResult } from 'mysql-ddl-checker'

TypeScript type for the return value of checkDDL. Use import type to avoid bundling issues.

checkDDL (CommonJS legacy)

✓ const checkDDL = require('mysql-ddl-checker').default

✗ const checkDDL = require('mysql-ddl-checker')

In CommonJS, the default export is accessed via .default property.

Analyze a MySQL DDL statement using the programmatic API, requires a configured online-ddl-check.json file in the project root.

import { createConnection } from 'mysql2/promise'; import checkDDL from 'mysql-ddl-checker'; async function main() { const ddl = 'ALTER TABLE users ADD COLUMN email VARCHAR(255)'; const result = await checkDDL(ddl); console.log('Algorithm:', result.algorithm); console.log('Lock:', result.lock); } main().catch(console.error);

Debug

Known issues

gotchaRequires a running MySQL server with credentials configured - does not work offline or with mock databases

fix

Ensure a MySQL server is accessible and the configuration file 'online-ddl-check.json' is present with correct credentials.

affects: >=0.0.1

gotchaCreates temporary tables in the connected database to simulate DDL - can cause disk space usage and temporary locks

fix

Use a dedicated test database and avoid running on production. Clean up temporary tables manually if needed.

affects: >=0.0.1

gotchaOnly works with MySQL 5.7+ or MariaDB 10.2+ due to online DDL features; unsupported databases will return incorrect results

fix

Check MySQL version before using. The package does not validate server compatibility.

affects: >=0.0.1

breakingConfiguration file must be named exactly 'online-ddl-check.json' in the project root - no alternative paths or env vars supported

fix

Create the file in the root directory of your project or change working directory to project root before running.

affects: >=1.0.0

deprecatedNode.js versions below 12 are not supported - uses async/await and modern JS features

fix

Upgrade to Node.js 12+ (recommended 14+).

affects: >=1.0.0

Errors

Common errors & fixes

Error: ENOENT: no such file or directory, open 'online-ddl-check.json'

Configuration file missing or not in the current working directory

fix

Create a file named 'online-ddl-check.json' in the project root with valid MySQL credentials.

Error: Cannot find module 'mysql2'

Missing peer dependency mysql2

fix

Run 'npm install mysql2' to install the required database driver.

TypeError: (0 , _mysqlDdlChecker.default) is not a function

Using CommonJS require incorrectly on ESM default export

fix

Use 'const checkDDL = require('mysql-ddl-checker').default;' instead of direct require.

Error: ER_PARSE_ERROR: You have an error in your SQL syntax

Invalid DDL statement passed to the analyzer

fix

Verify the DDL syntax is correct for your MySQL version. Check for typos or unsupported operations.

Upgrade

Version history

1.0.12latest on npm

Audit

Dependencies

mysql2requiredMySQL database driver for connecting to MySQL server

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/One-armed-boy/mysql-ddl-checker ↗

packagemysql-ddl-checker ↗

homepagehttps://github.com/One-armed-boy/mysql-ddl-checker#readme ↗