Command line utility to synchronize and version control relational database objects across databases
Last updated a month ago by kabirbaidhya .
MIT · Repository · Bugs · Original npm · Tarball · package.json
$ cnpm install @leapfrogtechnology/sync-db 
SYNC missed versions from official npm registry.


Command line utility to synchronize and version control relational database objects across databases.

Version Travis Language Grade: TypeScript Codecov PRs Welcome LICENSE


Using npm:

$ npm install @leapfrogtechnology/sync-db

You can install it globally as well.

$ npm install -g @leapfrogtechnology/sync-db

Drivers Installation

You'll need to install the database driver specific to your project separately.

For instance - if your project uses MSSQL, you will need to do:

$ yarn add mssql

This utility uses Knex under the hood so these are the supported drivers.


You can use sync-db both as a CLI utility and programmatically.


When installed globally, you can invoke the CLI directly.

The CLI exposes a single command sync-db that runs synchronize operation based on your configuration.

CLI Options

Below shown are the available CLI options , which is also the output printed by sync-db --help.

Synchronize database

  $ sync-db

  -f, --force                 Force synchronization
  -h, --help                  Print help information
  -v, --version               Print version
  -c, --generate-connections  Generate connections.sync-db.json file

Refer to the examples section below for full example with CLI usage.

Programmatic Usage

You may use programmatic API as shown below in case you need better flexibility based on your needs.

import { synchronize, loadConfig, resolveConnections } from '@leapfrogtechnology/sync-db';

(async () => {
  const config = await loadConfig(); // Load sync-db.yml
  const connections = await resolveConnections(); // Load connections.sync-db.json

  // Invoke the command.
  await synchronize(config, connections);

You can also pass your own database connection (eg: Knex connection) instead of resolving connections.sync-db.json file.

import * as Knex from 'knex';
import { synchronize, loadConfig } from '@leapfrogtechnology/sync-db';

(async () => {
  const config = await loadConfig(); // Load sync-db.yml
  const connection = Knex({
    // Your Knex connection instance.
    client: 'mssql',
    connection: {
      host: 'host',
      user: 'userName',
      password: 'password',
      database: 'dbName'
  const options = { force: false };

  // Invoke the command.
  await synchronize(config, connection, options);


  1. Sync Configuration
  2. Database Connections

1. Sync Configuration

sync-db expects the configuration file sync-db.yml to be present in your working directory. This holds all your configurations.


# Base path for the SQL source files.
basePath: /path/to/sql

  - schema/<schema_name>.sql
  - function/<schema_name>/<function_name>.sql
  - procedure/<schema_name>/<procedure_name>.sql

Configuration Options

  • basePath (string) - Base directory to hold all your SQL & migrations codebase (default: "src").
  • sql (array) - A series of SQL file paths that are to be run in ordered sequence (top to bottom), based on dependency. It should be noted that the source files needs to follow this convention of directory hierarchy. File paths listed here are relative to ${basePath}/sql value.

2. Database Connections

Database connections are configured in connections.sync-db.json file in your project root directory as shown below.

Since it contains all your database credentials, it is recommended that you DO NOT COMMIT it to VCS.


  "connections": [
      "id": "db1",
      "host": "localhost",
      "port": 1433,
      "user": "db1user",
      "database": "db1",
      "password": "password",
      "client": "mssql"

Note: The connections key expects an array, so you can also provide multiple databases and sync-db ensures your configured db objects are synced across all these databases.


Setup and Teardown steps aren't always run within a single transaction. You need to pass the transaction instance object explicitly to make sure this happens.

await db.transaction(async trx => {
  // Rollback and create all db objects using config.
  await synchronize(config, trx);


  1. Node MSSQL Sample
  2. Node MSSQL Programmatic Usage Sample
  3. Node PostgreSQL Sample


Check the CHANGELOG for release history.


Feel free to send pull requests.


Setting up

# Clone the repository.
$ git clone https://github.com/leapfrogtechnology/sync-db.git

# Go to the project directory.
$ cd sync-db

# Install dependencies. (Notice that we use yarn for this.)
$ yarn

Building / Testing

# Generate build.
$ yarn build

# Run tests
$ yarn test

# Invoke the CLI locally (development mode).
$ bin/run-dev.sh


Publish a new version.

$ NEXT=v1.0.0-beta.6 yarn release


Licensed under The MIT License.

FOSSA Status

Current Tags

25 Versions

  • 1.0.0-experimental.20200428                                ...           a month ago
  • 1.0.0-experimental.20200427                                ...           a month ago
  • 1.0.0-beta.6                                ...           2 months ago
  • 1.0.0-beta.5                                ...           3 months ago
  • 1.0.0-beta.4                                ...           3 months ago
  • 1.0.0-beta.3                                ...           3 months ago
  • 1.0.0-beta.2                                ...           3 months ago
  • 1.0.0-beta.1                                ...           3 months ago
  • 1.0.0-experimental.9-2                                ...           4 months ago
  • 1.0.0-experimental.9-1                                ...           4 months ago
  • 1.0.0-alpha.9                                ...           4 months ago
  • 1.0.0-experimental.8-6                                ...           4 months ago
  • 1.0.0-experimental.8-5                                ...           4 months ago
  • 1.0.0-experimental.8-4                                ...           5 months ago
  • 1.0.0-experimental.8-3                                ...           5 months ago
  • 1.0.0-experimental.8-2                                ...           5 months ago
  • 1.0.0-experimental.8-1                                ...           5 months ago
  • 1.0.0-alpha.8                                ...           6 months ago
  • 1.0.0-alpha.7                                ...           6 months ago
  • 1.0.0-alpha.6                                ...           9 months ago
  • 1.0.0-alpha.5                                ...           9 months ago
  • 1.0.0-alpha.4                                ...           9 months ago
  • 1.0.0-alpha.3                                ...           9 months ago
  • 1.0.0-alpha.2                                ...           10 months ago
  • 1.0.0-alpha.1                                ...           10 months ago
Today 0
This Week 0
This Month 0
Last Day 0
Last Week 25
Last Month 25
Dependencies (11)
Dev Dependencies (21)
Dependents (0)

Copyright 2014 - 2017 © taobao.org |