Registry / database / tiny-postgres-migrator

tiny-postgres-migrator

library2.0.0jsnpmunverified

Tiny Postgres Migrator is a lightweight, zero-config database schema migration tool specifically designed for the 'postgres' Node.js driver (ESM-native). Version 2.0.0 runs entirely from the command line or programmatically, supports both async/await and simple SQL file migrations. Unlike larger ORM-based tools (e.g., Sequelize, TypeORM), it offers minimal overhead, no external dependencies besides 'postgres', and a straightforward up/down migration pattern with plain SQL files. The library has a monthly release cadence and is actively maintained for bug fixes and Node.js compatibility.

database

npm install tiny-postgres-migrator

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · TINY-POSTGRES-MIGR

tiny-postgres-migrator

databasejavascriptv2.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.

migrate

✓ import { migrate } from 'tiny-postgres-migrator'

✗ const migrate = require('tiny-postgres-migrator')

The library is ESM-only. CommonJS require() will fail.

default export (migrate)

✓ import migrate from 'tiny-postgres-migrator'

✗ const migrate = require('tiny-postgres-migrator').default

Named export 'migrate' is the recommended usage, but default export also exists.

type imports

✓ import type { MigrationConfig } from 'tiny-postgres-migrator'

✗ import { MigrationConfig } from 'tiny-postgres-migrator' (if using transpilation)

Types are exported for TypeScript usage, best imported as type-only to avoid runtime overhead.

Shows programmatic usage: connect to PostgreSQL, run all 'up' migrations from a directory, and close the connection.

import { migrate } from 'tiny-postgres-migrator'; import postgres from 'postgres'; const sql = postgres({ host: 'localhost', port: 5432, database: 'mydb', user: 'user', password: process.env.DB_PASSWORD ?? '', }); await migrate({ sql, migrationsTable: 'migrations', dir: './migrations', direction: 'up', // or 'down' }); await sql.end();

Debug

Known issues

breakingVersion 2.0.0 changed the default export from a function to an object. Migrating from v1 requires destructuring 'migrate' or using default import.

fix

Update imports: either use named import { migrate } or default import with object destructuring.

affects: >=2.0.0

deprecatedThe CLI usage via npx tiny-postgres-migrator may be removed in future versions; prefer programmatic invocation.

fix

Switch to programmatic usage using the 'migrate' function.

affects: >=1.0.0 <2.0.0

gotchaMigration files must export 'up' and 'down' functions or be SQL files. Forgetting to export a named function causes silent failures.

fix

Ensure each migration file exports at least an 'up' function. Example: export async function up(sql) { ... }.

affects: *

gotchaThe 'migrationsTable' option is required in v2.0.0. If omitted, migration fails with 'Cannot read properties of undefined'.

fix

Always provide a 'migrationsTable' in the config object.

affects: >=2.0.0

breakingNode.js 18+ is required. Users on Node.js 16 will see 'ERR_FEATURE_UNAVAILABLE_ON_PLATFORM'.

fix

Upgrade to Node.js 18 or later.

affects: >=2.0.0

Errors

Common errors & fixes

Cannot find package 'postgres'

The 'postgres' driver is not installed as a dependency.

fix

Install the peer dependency: npm install postgres

Cannot use import statement outside a module

The project is not configured as a module (ESM).

fix

Add "type": "module" in package.json or rename file to .mjs

migrate is not a function

Incorrect import style. Likely using require() on ESM package.

fix

Use dynamic import: const { migrate } = await import('tiny-postgres-migrator');

Upgrade

Version history

2.0.0latest on npm

Audit

Dependencies

postgresrequiredRequired peer: the underlying PostgreSQL driver for Node.js. Migration uses the 'postgres' client for database connections.

Agent activity

12 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/tomm/tiny-postgres-migrator ↗

packagetiny-postgres-migrator ↗

homepagehttps://github.com/tomm/tiny-postgres-migrator#readme ↗