dbsync

library2.0.0jsnpmunverified

dbsync is a schema migration and database change management tool similar to Flyway but unopinionated and flexible. It scans a directory for SQL migration files and applies them in order, tracking which have been run. Version 2.0.0 (stable, current) includes a breaking change removing the need to manually escape '?' characters in migrations. Supports any database supported by Knex.js (Postgres, MySQL, MariaDB, SQLite3, Oracle experimental). Release cadence is irregular; maintained as of 2023.

database

npm install dbsync

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · DBSYNC

dbsync

databasejavascriptv2.0.0

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

✓ import dbsync from 'dbsync'

✗ const dbsync = require('dbsync')

Package is ESM-only from v2.0.0. Use default import for programmatic usage.

Migrator

✓ import { Migrator } from 'dbsync'

Named export for the Migrator class. Available since v2.0.0.

runMigrations

✓ import { runMigrations } from 'dbsync'

Named export for the runMigrations utility function. Similar to CLI behavior.

Programmatic migration with dbsync using ESM import and configuration object.

import dbsync from 'dbsync'; const config = { client: 'pg', connection: { host: process.env.DB_HOST ?? 'localhost', user: process.env.DB_USER ?? 'user', password: process.env.DB_PASS ?? '', database: process.env.DB_NAME ?? 'mydb' }, path: './migrations' }; dbsync.run(config) .then(() => console.log('Migrations applied successfully')) .catch(err => console.error('Migration failed:', err));

Debug

Known issues

breakingIn version 2.0.0, migration files no longer require manual escaping of '?' characters. If you previously added manual escaping (e.g., doubling '?'), those will be double-escaped and may cause errors.

fix

Remove any manual escaping of '?' in migration files before upgrading to v2.0.0.

affects: 2.0.0

deprecatedThe old CommonJS require pattern (const dbsync = require('dbsync')) is deprecated and will not work in v2.0.0+.

fix

Use ESM import statements: import dbsync from 'dbsync'

affects: >=2.0.0

gotchaMigrations must be run in alphabetical order; the filename determines execution order. Changing a migration file after it has been run will not re-run it.

fix

Ensure migration filenames follow a consistent naming scheme (e.g., YYYYMMDDHHMMSS_description.sql) to enforce order.

affects: >=0.1.0

gotchadbsync requires Knex.js to be installed separately. Not doing so will result in a runtime error.

fix

Install knex and a database driver (e.g., pg, mysql, sqlite3) before using dbsync.

affects: >=0.1.0

Errors

Common errors & fixes

Error: Cannot find module 'knex'

Knex is a peer dependency and must be installed separately.

fix

Run: npm install knex

Error: Client does not support authentication protocol requested by server; consider upgrading MySQL client

MySQL database requires specific authentication plugin (e.g., caching_sha2_password) which is not supported by older mysql package.

fix

Use mysql2 instead of mysql: npm install mysql2

Error: relation "migrations" does not exist

The default schema table 'migrations' has not been created yet; dbsync should create it automatically but may fail if permissions are insufficient.

fix

Ensure the database user has CREATE TABLE permissions.

TypeError: dbsync.run is not a function

CommonJS require was used but dbsync exports an ES module.

fix

Switch to ESM import (import dbsync from 'dbsync') or use dynamic import (const dbsync = await import('dbsync')).

Upgrade

Version history

2.0.0latest on npm

Audit

Dependencies

knexrequiredRequired as a peer dependency to connect to databases; must be installed separately with a database driver

pgoptionalDatabase client for PostgreSQL; required if using Postgres

mysqloptionalDatabase client for MySQL/MariaDB; required if using MySQL

sqlite3optionalDatabase client for SQLite3; required if using SQLite

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/realtymaps/dbsync ↗

packagedbsync ↗

homepagehttps://github.com/realtymaps/dbsync ↗