sql-watch

library0.1.0jsnpmunverified

sql-watch is a command-line utility for rapid SQL development that automatically applies idempotent SQL scripts to a PostgreSQL database on file change. It is NOT a migration tool—no up/rollback patterns. Designed for TDD/BDD workflows, it watches file changes and re-runs SQL scripts atomically. Version 0.1.0 is the latest stable release with a low cadence (no recent updates). Key differentiator: it focuses on development speed with automatic execution, unlike traditional migration tools. Supports ESM and TypeScript.

devops database

npm install sql-watch

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · SQL-WATCH

sql-watch

devopsjavascriptv0.1.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.

sql-watch (CLI)

✓ npx sql-watch [options]

✗ npm run sql-watch (unless in scripts)

CLI tool, not a library. Use npx or global install.

runSqlScripts

✓ import { runSqlScripts } from 'sql-watch'

ESM-only; no CommonJS exports.

initDatabase

✓ import { initDatabase } from 'sql-watch'

✗ const initDatabase = require('sql-watch').initDatabase

TypeScript types included, but package is ESM-only.

Shows initialization, single-run, and watch modes for rapid SQL development with PostgreSQL.

// Set required environment variables (use .env or export) // PGDATABASE, PGUSER, PGPORT, PGPASSWORD, PGHOST, NODE_ENV // Initialize sql-watch schema and directories npx sql-watch --init development // Run SQL scripts once npx sql-watch --run // Watch for changes and auto-apply npx sql-watch --watch --always-run

Debug

Known issues

breakingsql-watch does NOT support migration up/down rollback pattern. It is designed for idempotent scripts only.

fix

Use traditional migration tools if you need rollback support.

affects: >=0.0.0

gotchaEnvironment variables for database connection are required; see README for required vars.

fix

Set PGDATABASE, PGUSER, PGPORT, PGPASSWORD, PGHOST, NODE_ENV in .env or export.

affects: >=0.0.0

gotchaThe --init command creates tables and directories; it prompts before resetting in production unless --bypass is used.

fix

Use --bypass for CI/CD.

affects: >=0.0.0

deprecatedOptions like --log-level may change; check version compatibility.

fix

Update to latest version or refer to updated docs.

affects: <0.2.0

Errors

Common errors & fixes

Error: connect ECONNREFUSED 127.0.0.1:5432

PostgreSQL not running or wrong host/port in env vars.

fix

Start PostgreSQL or check PGHOST and PGPORT in environment.

sql-watch: command not found

sql-watch not installed globally or locally.

fix

Run 'npm install -g sql-watch' or use 'npx sql-watch'.

Error: Cannot find module 'pg'

Missing pg dependency.

fix

Run 'npm install pg' as peer dependency.

Upgrade

Version history

0.1.0latest on npm

Audit

Dependencies

chokidaroptionalFile watching dependency

pgrequiredPostgreSQL client for database connections

Agent activity

19 hits · last 30 days

node