sql-watch-lib

library0.1.0jsnpmunverified

sql-watch-lib v0.1.0 is a Node.js library for rapid SQL development that automatically applies idempotent SQL scripts to a PostgreSQL database when files change. It supports a watch mode for development and can be integrated into CI/CD pipelines. Unlike full migration tools (e.g., Flyway, Alembic), it focuses on idempotent SQL (CREATE OR REPLACE, etc.) and immediate feedback. Currently in early release with pre-1.0 API changes likely. It ships TypeScript types and is part of the sql-watch monorepo.

database devops

npm install sql-watch-lib

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · SQL-WATCH-LIB

sql-watch-lib

databasejavascriptv0.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.

init

✓ import { init } from 'sql-watch-lib'

✗ const { init } = require('sql-watch-lib')

ESM-only since v0.1.0

WatcherConfig

✓ import type { WatcherConfig } from 'sql-watch-lib'

✗ import { WatcherConfig } from 'sql-watch-lib'

Type import only; not a runtime value.

Creates a watcher that applies idempotent SQL scripts from ./sql on file changes.

import { init } from 'sql-watch-lib'; import { Pool } from 'pg'; const pool = new Pool({ connectionString: process.env.DATABASE_URL ?? 'postgresql://localhost/mydb' }); const watch = init(pool, { scriptsDir: './sql' }); watch.on('change', (file) => { console.log(`Applied ${file}`); }); watch.on('error', (err) => { console.error(err); });

Debug

Known issues

breakingAPI may break backwards compatibility until v1.0.0

fix

Pin to exact version and test upgrades.

affects: <1.0.0

gotchaSQL scripts must be idempotent; non-idempotent scripts may cause errors or data loss on reapplication.

fix

Use 'CREATE OR REPLACE' or 'IF NOT EXISTS' patterns.

affects: >=0.1.0

gotchaDefault watcher polls file system; may cause high CPU usage on large directories.

fix

Set 'pollInterval' in config or restrict scriptsDir.

affects: >=0.1.0

deprecatedThe 'events' option in config is deprecated; use 'on' methods on the watcher object.

fix

Replace 'events: { change: fn }' with 'watcher.on('change', fn)'.

affects: >=0.1.0

Errors

Common errors & fixes

Error: listen EADDRINUSE :::5432

Default port 5432 already in use by another Postgres instance.

fix

Specify a different port in DATABASE_URL, e.g., postgresql://localhost:5433/mydb

Error: SASL: Authentication failed

Invalid credentials or SCRAM-SHA-256 not supported by client.

fix

Ensure pg client supports SCRAM or use md5 authentication; update pg package.

TypeError: init is not a function

Importing from wrong path or CJS vs ESM mismatch.

fix

Use 'import { init } from 'sql-watch-lib'' (ESM) or update tsconfig.json.

Upgrade

Version history

0.1.0latest on npm

Audit

Dependencies

pgrequiredPostgreSQL client required for database connections

chokidarrequiredFile system watcher for detecting SQL file changes

Agent activity

17 hits · last 30 days

node