Registry / database / sql-schema-control

sql-schema-control

library1.7.1jsnpmunverified

Declarative database schema management tool for provisioning, tracking, syncing, and modifying database schemas using plain, version-controlled SQL. Current stable version is 1.7.1. It supports PostgreSQL and MySQL, and is inspired by Liquibase and Terraform. Key differentiators include a declarative approach with two schema management classes (changes and resources), automatic detection of out-of-sync resources, and seamless integration into CI/CD pipelines. Release cadence is not specified but appears active. It ships TypeScript types and requires Node >=8.0.0.

database

npm install sql-schema-control

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · SQL-SCHEMA-CONTROL

sql-schema-control

databasejavascriptv1.7.1

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.

apply

✓ import { apply } from 'sql-schema-control'

✗ const sqlSchemaControl = require('sql-schema-control'); sqlSchemaControl.apply()

Named export for applying changes; ESM usage requires 'type': 'module' or .mjs extension

plan

✓ import { plan } from 'sql-schema-control'

✗ import { plan } from 'sql-schema-control/plan'

plan is exported from the main package, not a subpath; do not use a subpath import

pull

✓ import { pull } from 'sql-schema-control'

✗ const pull = require('sql-schema-control').pull

CommonJS require works but ESM import is preferred; types are included

Shows how to plan and apply schema changes using sql-schema-control with PostgreSQL, including connection setup and error handling.

import { plan, apply } from 'sql-schema-control'; import pg from 'pg'; // Assuming a connection config is defined elsewhere const connectionConfig = { host: 'localhost', port: 5432, database: 'mydb', schema: 'public', username: 'user', password: process.env.DB_PASSWORD ?? '' }; async function run() { // Plan the actions needed to sync the schema const actions = await plan({ language: 'postgres', dialect: '10.7', connection: connectionConfig, strict: true, controlDir: './sql' // directory containing .sql files }); console.log('Planned actions:', actions); // Apply the changes const result = await apply({ language: 'postgres', dialect: '10.7', connection: connectionConfig, strict: true, controlDir: './sql' }); console.log('Applied result:', result); } run().catch(console.error);

Debug

Known issues

breakingThe schema user must have DDL permissions; otherwise operations will fail silently or with cryptic errors.

fix

Grant DDL privileges (e.g., CREATE, ALTER, DROP) to the user specified in the connection config.

affects: >=1.0.0

gotchaWhen using strict: true (default), any uncontrolled resources in the database cause failures; set strict: false to ignore them.

fix

Set strict: false in the control config if you expect uncontrolled resources.

affects: >=1.0.0

deprecatedThe old 'connection' field as a string path to a module is deprecated; use a connection object directly.

fix

Update your config to pass the connection object directly instead of a module path.

affects: <=1.6.0

gotchaThe 'dialect' version must match the actual database server version, otherwise SQL syntax errors may occur.

fix

Set the dialect to the exact version of your PostgreSQL or MySQL server (e.g., '10.7' for Postgres).

affects: >=1.0.0

gotchaThe control directory (controlDir) should only contain .sql files; other files may be ignored or cause unexpected behavior.

fix

Ensure your control directory contains only .sql files, organized by changes/ and resources/ subdirectories.

affects: >=1.0.0

Errors

Common errors & fixes

Error: Cannot find module 'pg'

Missing PostgreSQL driver when using Postgres connection.

fix

Run: npm install pg --save-dev

Error: connect ECONNREFUSED 127.0.0.1:5432

Database server is not running or connection config is wrong.

fix

Ensure the database server is running and the host/port are correct in the connection config.

Error: permission denied for schema public

The database user lacks DDL permissions.

fix

Grant USAGE, CREATE on schema and DDL privileges to the user. For example: GRANT ALL ON SCHEMA public TO your_user;

TypeError: promiseConfig is not a function

The connection config object is missing the promiseConfig function when using a module path.

fix

Pass a connection object directly instead of a module path, or ensure the module exports a promiseConfig function.

Upgrade

Version history

1.7.1latest on npm

Audit

Dependencies

pgoptionalPostgreSQL driver required for Postgres connections

mysqloptionalMySQL driver required for MySQL connections

Agent activity

11 hits · last 30 days

node