Registry / database / sql-patch

sql-patch

JSON →
library1.2.2jsnpmunverified

sql-patch is a minimal, idempotent SQL migration tool for Node.js, version 1.2.2. It applies all `.sql` files in a directory in order to a PostgreSQL database, tracking applied patches in a `_schema_patches` table. Unlike Rails migrations, patches are one-way and SQL-only, with no DSL or ORM. Release cadence is low; the project is stable but limited to PostgreSQL. Key differentiator: extremely simple, no configuration, and pure SQL — no code generation or rollbacks.

database
npm install sql-patch
github ↗package ↗homepage ↗
INSTALL
IMPORT
SIG · SQL-PATCH
S
sql-patch
databasejavascriptv1.2.2
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 sqlPatch from 'sql-patch'
✗ const sqlPatch = require('sql-patch')
ESM import; the package is CJS but can be imported as default in ESM environments.
types
✓ import type { PatchOptions } from 'sql-patch'
Type definitions available if using TypeScript.

Shows how to use sql-patch programmatically with sqlcmd-pg to create a database and apply all .sql migrations from a directory.

const path = require('path'); const Connection = require('sqlcmd-pg').Connection; const sqlPatch = require('sql-patch'); const db = new Connection({ user: 'postgres', database: 'example_db', password: process.env.PGPASSWORD ?? 'default', }); db.createDatabaseIfNotExists(function(err) { if (err) throw err; const patchesDir = path.join(__dirname, 'migrations'); sqlPatch.executePatches(db, '_schema_patches', patchesDir, function(err) { if (err) throw err; console.log('All patches applied successfully.'); process.exit(); }); });
Debug
Known issues
gotchaPatches are one-way; once applied, changing the SQL file has no effect and may lead to inconsistent state.
fix
Always append new patches instead of editing existing ones. Rollbacks must be handled manually.
affects: >=0.0.0
gotchaOnly PostgreSQL is supported via sqlcmd-pg. The Connection object must be from sqlcmd-pg, not generic pg.Client.
fix
Install sqlcmd-pg and use its Connection class.
affects: >=0.0.0
gotchaThe package does not run each patch inside a transaction, so if a patch fails midway, partial changes persist.
fix
Manually wrap patches in BEGIN/COMMIT within the SQL file, or use a different tool for transactional guarantees.
affects: >=0.0.0
Errors
Common errors & fixes
Error: require() of ES Module /path/to/sql-patch/index.js from /path/to/app.js not supported.
Using Node.js in ESM mode or incorrect import syntax.
fix
Use `import sqlPatch from 'sql-patch'` or set type: 'module' in package.json and use dynamic import if needed.
sqlPatch.executePatches is not a function
Incorrect import (e.g., using default import on CJS module directly).
fix
Use `const sqlPatch = require('sql-patch');` or `import * as sqlPatch from 'sql-patch';`
Error: connect ECONNREFUSED 127.0.0.1:5432
PostgreSQL not running or connection credentials incorrect.
fix
Ensure PostgreSQL is running and update connection parameters (host, port, user, password).
Upgrade
Version history
1.2.2latest on npm
Audit
Dependencies
sqlcmd-pgoptionalprovides the Connection class used in the API example
Agent activity
8 hits · last 30 days
node
6
Meta
1
OpenAI (training)
1
Resources
githubhttps://github.com/chbrown/sql-patch ↗
packagesql-patch ↗
homepagehttps://github.com/chbrown/sql-patch ↗
sql-patch — npm install sql-patch · libregistry