{"id":43928,"library":"sql-patch","title":"sql-patch","description":"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.","status":"active","version":"1.2.2","language":"javascript","source_language":"en","source_url":"https://github.com/chbrown/sql-patch","tags":["javascript","sql","migrate"],"install":[{"cmd":"npm install sql-patch","lang":"bash","label":"npm"},{"cmd":"yarn add sql-patch","lang":"bash","label":"yarn"},{"cmd":"pnpm add sql-patch","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"provides the Connection class used in the API example","package":"sqlcmd-pg","optional":true}],"imports":[{"note":"ESM import; the package is CJS but can be imported as default in ESM environments.","wrong":"const sqlPatch = require('sql-patch')","symbol":"default","correct":"import sqlPatch from 'sql-patch'"},{"note":"Type definitions available if using TypeScript.","symbol":"types","correct":"import type { PatchOptions } from 'sql-patch'"}],"quickstart":{"code":"const path = require('path');\nconst Connection = require('sqlcmd-pg').Connection;\nconst sqlPatch = require('sql-patch');\n\nconst db = new Connection({\n  user: 'postgres',\n  database: 'example_db',\n  password: process.env.PGPASSWORD ?? 'default',\n});\n\ndb.createDatabaseIfNotExists(function(err) {\n  if (err) throw err;\n\n  const patchesDir = path.join(__dirname, 'migrations');\n  sqlPatch.executePatches(db, '_schema_patches', patchesDir, function(err) {\n    if (err) throw err;\n    console.log('All patches applied successfully.');\n    process.exit();\n  });\n});","lang":"javascript","description":"Shows how to use sql-patch programmatically with sqlcmd-pg to create a database and apply all .sql migrations from a directory."},"warnings":[{"fix":"Always append new patches instead of editing existing ones. Rollbacks must be handled manually.","message":"Patches are one-way; once applied, changing the SQL file has no effect and may lead to inconsistent state.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Install sqlcmd-pg and use its Connection class.","message":"Only PostgreSQL is supported via sqlcmd-pg. The Connection object must be from sqlcmd-pg, not generic pg.Client.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Manually wrap patches in BEGIN/COMMIT within the SQL file, or use a different tool for transactional guarantees.","message":"The package does not run each patch inside a transaction, so if a patch fails midway, partial changes persist.","severity":"gotcha","affected_versions":">=0.0.0"}],"env_vars":null,"search_vec":"'1.2.2':17 'appli':19,33 'cadenc':58 'code':79 'configur':74 'databas':31 'differenti':70 'directori':25 'dsl':54 'extrem':71 'file':22 'generat':80 'idempot':10 'javascript':83 'key':69 'limit':66 'low':60 'migrat':12,42,85 'minim':9 'node.js':15 'one':46 'one-way':45 'order':27 'orm':56 'patch':3,6,34,38,43 'postgresql':30,68 'project':62 'pure':76 'rail':41 'releas':57 'rollback':82 'schema':37 'simpl':72 'sql':2,5,11,21,50,77,84 'sql-on':49 'sql-patch':1,4 'stabl':64 'tabl':39 'tool':13 'track':32 'unlik':40 'version':16 'way':47","created_at":"2026-06-05T17:02:08.995040+00:00","updated_at":"2026-06-05T17:02:08.995040+00:00","problems":[{"fix":"Use `import sqlPatch from 'sql-patch'` or set type: 'module' in package.json and use dynamic import if needed.","cause":"Using Node.js in ESM mode or incorrect import syntax.","error":"Error: require() of ES Module /path/to/sql-patch/index.js from /path/to/app.js not supported."},{"fix":"Use `const sqlPatch = require('sql-patch');` or `import * as sqlPatch from 'sql-patch';`","cause":"Incorrect import (e.g., using default import on CJS module directly).","error":"sqlPatch.executePatches is not a function"},{"fix":"Ensure PostgreSQL is running and update connection parameters (host, port, user, password).","cause":"PostgreSQL not running or connection credentials incorrect.","error":"Error: connect ECONNREFUSED 127.0.0.1:5432"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"https://github.com/chbrown/sql-patch","github":"https://github.com/chbrown/sql-patch","docs":null,"changelog":null,"pypi":null,"npm":"sql-patch","openapi_spec":null,"status_page":null,"smithery":null,"categories":["database"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-05","next_check":"2026-09-03","install_tag":null}}