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.
MigrationBuilder
✓ import { MigrationBuilder } from 'node-pg-migrate'
✗ import { MigrationBuilder } from 'pgstrap'
pgstrap does not export MigrationBuilder; it re-exports from node-pg-migrate. Always import from node-pg-migrate.
ColumnDefinitions
✓ import { ColumnDefinitions } from 'node-pg-migrate'
✗ import { ColumnDefinitions } from 'pgstrap'
ColumnDefinitions is from node-pg-migrate, not pgstrap.
pgstrap.config.js (CommonJS)
✓ module.exports = { ... }
✗ export default { ... }
pgstrap uses CommonJS config file (pgstrap.config.js). ESM export may not be supported.
Shows full workflow: install, init, create migration, write migration, run migration, and generate types.
// 1. Install pgstrap
npm install pgstrap --save-dev
// 2. Initialize pgstrap in your project
npx pgstrap init
// 3. Create a migration
npm run db:create-migration my-first-migration
// 4. Write your migration (example migration file)
import { MigrationBuilder, ColumnDefinitions } from 'node-pg-migrate'
export const shorthands: ColumnDefinitions | undefined = undefined
export async function up(pgm: MigrationBuilder): Promise<void> {
pgm.createTable('users', {
id: 'id',
username: { type: 'text', notNull: true },
email: { type: 'text', notNull: true, unique: true },
created_at: {
type: 'timestamptz',
notNull: true,
default: pgm.func('current_timestamp'),
},
})
pgm.createIndex('users', 'username')
}
export async function down(pgm: MigrationBuilder): Promise<void> {
pgm.dropTable('users')
}
// 5. Run migration
npm run db:migrate
// 6. Generate types and structure
npm run db:generate
Debug
Known issues
gotchapgstrap requires esbuild-register to run TypeScript migrations, but does not auto-install it. Users must manually install esbuild-register as a dev dependency.fixnpm install esbuild-register --save-dev
affects: >=1.0.0
gotchaMigration functions must be exported with exact names 'up' and 'down'. Named exports like 'migrateUp' or default exports will not be recognized.fixEnsure migration files have 'export async function up' and optionally 'export async function down'.
affects: >=1.0.0
breakingIn pgstrap 1.0.0, the config file format changed from JSON to CommonJS (pgstrap.config.js). JSON files are no longer supported.fixConvert pgstrap.config.json to pgstrap.config.js with module.exports = { ... } affects: <1.0.0 || >=1.0.0
deprecatedUsing node-pg-migrate v7.x syntax is deprecated. pgstrap uses node-pg-migrate internally, and some older patterns may break.fixReference node-pg-migrate docs for latest API (v7+). Avoid old patterns like 'pgm.sql' for DDL.
affects: >=1.0.0
gotchapgstarap generates types and structure into 'src/db/zapatos' and 'src/db/structure' by default. If your project uses a different directory structure, you must update pgstrap.config.js.fixSet 'dbDir' in pgstrap.config.js to your custom path.
affects: >=1.0.0
Errors
Common errors & fixes
ERR_REQUIRE_ESM: Must use import to load ES Module: /path/to/pgstrap.config.js
pgstrap expects CommonJS config, but the file uses ES modules (e.g., export default).
fixChange config file to use module.exports = { ... } or rename to .cjs. Error: Cannot find module 'esbuild-register'
Missing required peer dependency esbuild-register.
fixRun: npm install esbuild-register --save-dev
Migration '20240101000000-my-migration.ts' does not export 'up'
Migration file must export a function named 'up'.
fixAdd 'export async function up(pgm: MigrationBuilder): Promise<void> { ... }' Audit
Dependencies
esbuild-registerrequiredRequired to run TypeScript migrations and scripts at runtime
kyselyoptionalPeer dependency for TypeScript query builder compatibility
node-pg-migraterequiredCore migration engine used by pgstrap
pg-connection-from-envrequiredReads database connection from environment variables
zapatosoptionalPeer dependency for generating typed schema definitions