node-pg-migrate
node-pg-migrate is a Node.js tool that manages database schema changes for PostgreSQL and compatible databases like CockroachDB. It lets teams write migrations as JavaScript code that can be applied forward and (sometimes) automatically reversed, avoiding manual SQL scripts.
Key facts
Objective fields from the source. Values we can't verify are shown as “Unknown” rather than guessed.
| Field | Value |
|---|---|
| Repository | salsita/node-pg-migrate |
| Owner | salsita |
| Primary language | TypeScript |
| License | MIT — OSI-approved |
| Stars | 1.5k |
| Forks | 194 |
| Open issues | 50 |
| Latest release | v8.0.4 (2025-12-11) |
| Last updated | 2026-07-08 |
| Source | https://github.com/salsita/node-pg-migrate |
What node-pg-migrate is
A TypeScript-based migration manager for PostgreSQL 13+ that provides a programmatic API (pgm object) to generate idempotent SQL, supports async operations within migrations, and tracks applied migrations in the database. Built on the pg driver and requires Node.js 20.11+.
Get the node-pg-migrate source
Clone the repository and explore it locally.
git clone https://github.com/salsita/node-pg-migrate.gitcd node-pg-migrate# follow the project's README for install & configurationNeed it deployed, integrated, or customized instead? DEV.co ships production installs.
Best use cases
Implementation considerations
- Install pg driver separately (peer dependency); ensure it matches your PostgreSQL server version.
- Set DATABASE_URL environment variable for all environments; use secrets management (e.g., .env files in dev, CI/CD secrets in prod).
- Write reversible up/down functions early; do not rely solely on automatic downgrade inference for production schemas.
- Test migrations against a replica of production schema and data volume before apply.
- Use migration naming conventions strictly (timestamps prefixed) to avoid ordering conflicts in teams.
When to avoid it — and what to weigh
- Non-PostgreSQL databases required — Tool is explicitly PostgreSQL-first. While CockroachDB compatibility is tested, use of other SQL databases is unsupported and untested.
- Pre-Node.js 20.11 environments — Hard requirement of Node.js 20.11+; cannot backport to older runtime versions.
- Seeking automated downward migrations — Downgrades are inferred 'sometimes' per docs—no guarantee. Requires explicit down() functions for safety-critical schemas.
- Zero-downtime deployment needs — Tool provides no built-in orchestration for zero-downtime deploys. Requires external coordination and careful index/constraint ordering.
License & commercial use
MIT License—permissive, OSI-approved. Allows commercial use, modification, and distribution with attribution and no warranty.
MIT is a standard permissive OSI license. Commercial use is permitted. No copyleft or enterprise licensing restrictions detected. No additional proprietary tiers or dual licensing stated in README.
DEV.co evaluation signals
Editorial assessment — not user reviews. Directional, with an explicit confidence level.
| Signal | Assessment |
|---|---|
| Maintenance | Active |
| Documentation | Adequate |
| License clarity | Clear |
| Deployment complexity | Low |
| DEV.co fit | Strong |
| Assessment confidence | High |
Migrations execute raw SQL generated from user code; no built-in protection against SQL injection if user functions construct dynamic SQL carelessly. DATABASE_URL contains credentials—must not be committed to version control; use environment variable injection in CI/CD. No explicit mention of transaction safety or rollback guarantees in README; requires review of rollback behavior on error.
Alternatives to consider
Flyway
Multi-database, battle-tested, compiled JVM tool with strong lock mechanisms; trade-off is no Node.js native runtime and less programmatic flexibility.
Liquibase
Supports many databases and XML/JSON/YAML syntax; enterprise features (approval workflows, audit); heavier than node-pg-migrate and not Node-native.
TypeORM migrations
Integrated into TypeORM ORM; simpler if already using TypeORM; less flexible for non-ORM use cases and PostgreSQL-specific features.
Build on node-pg-migrate with DEV.co software developers
Review the full documentation at salsita.github.io/node-pg-migrate and test a sample migration on a dev PostgreSQL instance. Confirm rollback behavior and DATABASE_URL secret handling for your CI/CD pipeline.
Talk to DEV.coRelated open-source tools
Surfaced by semantic similarity across the DEV.co open-source index.
Related on DEV.co
Explore the category and the services that help you build with it.
node-pg-migrate FAQ
Can I use node-pg-migrate without TypeScript?
How do I rollback a migration in production?
Does node-pg-migrate lock the database during migrations?
Can I use this with CockroachDB?
Software development & web development with DEV.co
DEV.co is a software development agency delivering custom software development services to companies building on open source. Our software developers and web developers design, integrate, and ship production systems — spanning web development, APIs, AI, data, and cloud. If node-pg-migrate is part of your open-source databases roadmap, our team can implement, customize, migrate, and maintain it.
Evaluate node-pg-migrate for your team
Review the full documentation at salsita.github.io/node-pg-migrate and test a sample migration on a dev PostgreSQL instance. Confirm rollback behavior and DATABASE_URL secret handling for your CI/CD pipeline.