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
✓ export default async function (sql) { ... }
✗ module.exports = async function (sql) { ... }
Migrations are ES modules with a default async function export; CommonJS module.exports will fail.
pgChange CLI
✓ npx pgChange create migration_name
✗ npm run pgChange create migration_name
The CLI is invoked via npx or global install; npm run-script not defined unless in package.json scripts.
sql
✓ sql`CREATE TABLE ...`
✗ sql.query('CREATE TABLE ...')
sql is the Postgres.js tagged template function, not a query method.
Demonstrates project setup: config file, creating a migration, defining a table with SQL template literal, and running migrations via CLI.
// 1. Create pgChange.json in project root
// {
// "migrationsPath": "migrations",
// "postgresHost": "localhost",
// "postgresPort": "5432",
// "postgresUser": "postgres",
// "postgresPassword": "password",
// "postgresDb": "postgres"
// }
// 2. Create a migration file
// Run: pgChange create users
// This creates: migrations/1724709481967_users.js
// 3. Write your SQL in the migration file
export default async function (sql) {
await sql`
CREATE TABLE users (
id SERIAL PRIMARY KEY,
email TEXT NOT NULL
);
`;
}
// 4. Run all pending migrations
// Run: pgChange run-latest
// 5. Run a specific migration
// Run: pgChange run 1724709481967_users.js
Debug
Known issues
gotchaThe pgChange.json configuration file contains plaintext database credentials. It must be added to .gitignore to avoid committing secrets.fixAdd 'pgChange.json' to your .gitignore file before committing.
affects: all
breakingMigrations must use ES module syntax (export default async function). Using CommonJS module.exports will cause the migration to be silently skipped or error.fixUse 'export default async function (sql) { ... }' instead of 'module.exports = ...'. affects: >=0.1.0
gotchaThe sql function inside a migration is the Postgres.js instance; calling it without 'await' may cause the migration to complete before the SQL actually runs, leading to inconsistent state.fixAlways await the SQL template literal: await sql`...`;
affects: all
gotchaThe CLI command 'pgChange create migrationName' creates a file with a timestamp prefix; filenames must remain sorted chronologically or migration order may be incorrect.fixEnsure migration filenames maintain chronological ordering; do not rename timestamp prefixes.
affects: all
deprecatedNo known deprecated features in current version.
Errors
Common errors & fixes
Error: Cannot find module 'postgres'
Postgres.js is not installed as a dependency.
fixRun 'npm install postgres' in your project.
SyntaxError: Unexpected token 'export'
Node.js is running in CommonJS mode or the migration file lacks .mjs extension while target is CJS.
fixEnsure your project has 'type': 'module' in package.json, or rename migration files to .mjs.
Error: relation 'pgchange_migrations' does not exist
The meta table for tracking applied migrations has not been created; usually created automatically on first run, but may fail if schema or permissions are missing.
fixEnsure the database user has CREATE TABLE permissions, or manually run the SQL: CREATE TABLE pgchange_migrations (id SERIAL PRIMARY KEY, name TEXT, applied_at TIMESTAMP DEFAULT NOW());
pgChange: command not found
pg-change is not installed globally or you are not using npx.
fixRun 'npx pgChange' instead of bare 'pgChange', or install globally with 'npm install -g pg-change'.
Audit
Dependencies
postgresrequiredpg-change uses Postgres.js as the underlying PostgreSQL client driver.