Registry / database / postgres-migrations

postgres-migrations

library5.3.0jsnpmunverified

The `postgres-migrations` package provides a robust database migration solution for PostgreSQL, directly inspired by Stack Overflow's deployment methodology. Currently at version 5.3.0, it offers a stable and opinionated approach to managing database schema changes. Key differentiators include its strict sequential SQL file-based ordering, which explicitly avoids timestamp-based naming to ensure consistent execution order across all environments. The library deliberately eschews 'down' migrations, advocating for a 'roll forward' philosophy where issues are addressed by applying new incremental migrations. It enforces database integrity by performing hash checks on previously applied migration files, preventing accidental or unauthorized modifications. The package maintains a hidden `migrations` table to track applied scripts and requires Node.js 10.17.0+ and PostgreSQL 9.4+.

database

npm install postgres-migrations

github ↗package ↗

INSTALL

IMPORT

SIG · POSTGRES-MIGRATION

postgres-migrations

databasejavascriptv5.3.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

migrate

✓ import { migrate } from 'postgres-migrations'

✗ const { migrate } = require('postgres-migrations')

Primary function to apply migrations. Accepts either a `pg` client/pool instance or a database connection config object.

loadMigrationFiles

✓ import { loadMigrationFiles } from 'postgres-migrations'

✗ const { loadMigrationFiles } = require('postgres-migrations')

Utility to programmatically validate migration files for conflicts before application.

pg.Client

✓ import { Client } from 'pg'

✗ const { Client } = require('pg')

While not part of `postgres-migrations`, the `pg` client or pool is often used in conjunction with this library.

Demonstrates how to apply migrations using an existing `pg.Client` instance, ensuring proper connection handling and error reporting. It uses environment variables for database credentials.

import { migrate } from 'postgres-migrations'; import { Client } from 'pg'; import path from 'path'; async function runMigrations() { const dbConfig = { database: process.env.DB_NAME ?? 'your_database', user: process.env.DB_USER ?? 'postgres', password: process.env.DB_PASSWORD ?? 'password', host: process.env.DB_HOST ?? 'localhost', port: parseInt(process.env.DB_PORT ?? '5432', 10), // ensureDatabaseExists: true // Uncomment if you want the library to create the database if it doesn't exist }; const client = new Client(dbConfig); await client.connect(); try { console.log('Starting database migrations...'); const migrationsPath = path.resolve(__dirname, 'migrations'); await migrate({ client }, migrationsPath); console.log('Database migrations completed successfully.'); } catch (error) { console.error('Migration failed:', error); process.exit(1); } finally { await client.end(); } } // Example migrations directory structure: // my-project/ // ├── src/ // │ └── index.ts (or .js) // └── migrations/ // ├── 1_create_users_table.sql // └── 2_add_posts_table.sql runMigrations();

Debug

Known issues

breakingThis library intentionally does not support 'down' migrations or rollbacks. The philosophy is to 'roll forward' by applying new migrations to correct any issues, which may be a significant paradigm shift for users accustomed to rollback mechanisms.

fix

Plan for all schema changes to be additive or corrective via new migration files, rather than relying on reversions.

affects: >=1.0.0

gotchaModifying migration files that have already been applied to a database will cause the migration process to fail due to hash mismatches. The library performs integrity checks to ensure that previously run migrations remain unchanged.

fix

Never alter migration files after they have been committed and applied to any environment. Create a new migration file to introduce any necessary changes or corrections.

affects: >=1.0.0

gotchaIf two migration files are created with the same sequential prefix (e.g., `5_add_column_a.sql` and `5_add_column_b.sql`), the migration process will detect this conflict and refuse to proceed. This is to prevent inconsistent migration ordering.

fix

Ensure all migration files have unique, sequential prefixes. Use `loadMigrationFiles` or the `pg-validate-migrations` bin script to check for conflicts early in development.

affects: >=1.0.0

gotchaThe `ensureDatabaseExists` option, which defaults to `false`, might change its default behavior in future major versions. If `false`, the database must exist before migrations can run.

fix

Explicitly set `ensureDatabaseExists: true` if you want the library to create the target database for you, or ensure the database exists manually before running migrations.

affects: >=1.0.0

gotchaThe library requires Node.js version 10.17.0 or higher and PostgreSQL version 9.4 or higher. Older environments are not supported and may lead to unexpected behavior or errors.

fix

Upgrade your Node.js runtime and PostgreSQL database to meet the minimum version requirements.

affects: >=1.0.0

Errors

Common errors & fixes

ERROR: Migration file 'X_my-migration.sql' has been modified since it was applied. Aborting.

A migration SQL file that was previously successfully applied to the database has been altered on the filesystem.

fix

Revert the changes to the migration file `X_my-migration.sql` to its original state, or ensure no applied migration files are modified. All subsequent changes should be in new migration files.

ERROR: Found multiple migration files with the same sequence number: X_migration1.sql, X_migration2.sql. Please resolve this conflict.

Two or more migration files in the specified directory share the same numerical prefix, leading to an ambiguous execution order.

fix

Rename one of the conflicting migration files (e.g., `X_migration2.sql` to `Y_migration2.sql` where `Y` is the next available sequence number) to ensure all migration files have unique, sequential prefixes.

TypeError: client.connect is not a function

An invalid `pg` client object (e.g., a raw configuration object or an uninstantiated `pg` class) was passed where a connected client or pool was expected.

fix

Ensure you are passing an instantiated `pg.Client`, `pg.Pool`, or `pg.PoolClient` instance that has already called `.connect()` (for `Client`) or is ready for use (for `Pool`). Alternatively, pass the database connection config directly.

Upgrade

Version history

5.3.0latest on npm

Audit

Dependencies

pgrequiredUsed for database connectivity; can be passed directly to the `migrate` function.

Agent activity

9 hits · last 30 days

node

Resources

githubhttps://github.com/thomwright/postgres-migrations ↗

packagehttps://www.npmjs.com/package/postgres-migrations ↗