postgrator

library8.0.0jsnpmunverified

SQL migration tool for Node.js using plain SQL or JavaScript files, supporting PostgreSQL, MySQL, SQL Server, and SQLite. Version 8.0.0 requires Node >=20 and publishes TypeScript types. Postgrator is ESM-only as of v6, tracks migrations in a schema table, and automatically determines directional migration (up/down). Key differentiators: file-based versioning with .do.sql/.undo.sql convention, optional JS/async migration scripts, and no ORM dependency. Released under MIT license, maintained by Rick Bergfalk.

database

npm install postgrator

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · POSTGRATOR

postgrator

databasejavascriptv8.0.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.

Postgrator

✓ import Postgrator from 'postgrator';

✗ const Postgrator = require('postgrator');

Postgrator is ESM-only since v6. CommonJS require will fail.

Postgrator

✓ import Postgrator from 'postgrator';

Default export only; TypeScript types included.

PostgratorConfig

✓ import type { PostgratorConfig } from 'postgrator';

TypeScript type import for configuration object.

Migration

✓ import type { Migration } from 'postgrator';

TypeScript type for migration objects.

Creates a Postgrator instance with a PostgreSQL client, runs migrations to version '005' using a migration folder.

import Postgrator from 'postgrator'; import pg from 'pg'; const client = new pg.Client({ host: 'localhost', port: 5432, database: 'mydb', user: 'user', password: process.env.DB_PASSWORD ?? '', }); await client.connect(); const postgrator = new Postgrator({ migrationPattern: 'migrations/*', driver: 'pg', database: 'mydb', schemaTable: 'schemaversion', execQuery: (query) => client.query(query), }); const result = await postgrator.migrate('005'); console.log(`Migrated to version ${result}`); await client.end();

Debug

Known issues

breakingPostgrator v6.0.0 switched to ESM-only. CommonJS require() will throw an error.

fix

Use import (ESM) or migrate to dynamic import(). Set type: 'module' in package.json.

affects: >=6.0.0

breakingPostgrator v8 requires Node.js >=20.0.0. Older Node versions will fail.

fix

Upgrade Node.js to version 20 or later.

affects: >=8.0.0

deprecatedThe option 'currentSchema' was deprecated in v6; use 'schemaTable' to specify schema and table.

fix

Change 'currentSchema' to 'schemaTable' with format 'schema.table' if needed.

affects: >=6.0.0

gotchaMigration files must follow the pattern [version].[action].[description].sql/.js. Files with wrong extension or naming are silently ignored.

fix

Ensure files match pattern exactly, e.g., 001.do.my-migration.sql.

affects: >=0.0.0

gotchaWhen using JavaScript migrations, the file must export a function named `generateSql`. Exporting a default function or other names will be ignored.

fix

Use module.exports.generateSql = function() { ... } or export function generateSql() { ... } for ESM.

affects: >=0.0.0

gotchaUndo scripts are optional but if missing and Postgrator needs to roll back, it throws an error. No automatic undo generation.

fix

Always provide an undo script for each migration, or ensure you never need to downgrade past a migration without one.

affects: >=0.0.0

Errors

Common errors & fixes

Error [ERR_REQUIRE_ESM]: require() of ES Module /path/to/postgrator/index.js from /path/to/script.js not supported.

Postgrator v6+ is an ES module; require() cannot load it.

fix

Switch to import statement, or use dynamic import() inside a CommonJS module.

PostgratorError: No files found for pattern 'migrations/*'

The migrationPattern glob does not match any files, or the directory does not exist.

fix

Verify the pattern path relative to process.cwd(). Use absolute paths or __dirname based paths.

The "driver" property must be one of "pg", "mysql", "mssql", "sqlite", "mysql2".

Invalid driver string passed to Postgrator config.

fix

Set driver to exactly one of the supported drivers: 'pg', 'mysql', 'mssql', 'sqlite', 'mysql2'.

Cannot find module 'pg'

Postgrator expects the database driver to be installed separately.

fix

npm install pg (or mysql2, mssql, better-sqlite3 depending on driver).

Upgrade

Version history

8.0.0latest on npm

Audit

Dependencies

pgoptionalPostgreSQL driver; required when using 'pg' driver

mysql2optionalMySQL driver; required when using 'mysql' driver

mssqloptionalSQL Server driver; required when using 'mssql' driver

better-sqlite3optionalSQLite driver; required when using 'sqlite' driver (or 'sqlite3')

Agent activity

4 hits · last 30 days

node

Resources

githubgit://github.com/rickbergfalk/postgrator ↗

packagepostgrator ↗

homepagehttps://github.com/rickbergfalk/postgrator#readme ↗