graphile-migrate

library1.4.1jsnpmunverified

Opinionated, SQL-powered migration tool for PostgreSQL. Current version is 1.4.1; releases are frequent. It differentiates from tools like Flyway or node-pg-migrate by focusing on direct SQL writing, watch mode for auto-migration during development, and declarative function/trigger management.

database

npm install graphile-migrate

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · GRAPHILE-MIGRATE

graphile-migrate

databasejavascriptv1.4.1

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.

runMigrations

✓ import { runMigrations } from 'graphile-migrate';

✗ import runMigrations from 'graphile-migrate';

Named export, not default.

parseSettings

✓ import { parseSettings } from 'graphile-migrate';

✗ import { parseSettings } from 'graphile-migrate/migrate';

Do not use deep imports; main entry exports parseSettings.

migrate

✓ import { migrate } from 'graphile-migrate';

✗ const migrate = require('graphile-migrate');

ESM module; CommonJS require requires .default.

getSettings

✓ import { getSettings } from 'graphile-migrate/settings';

✗ import { getSettings } from 'graphile-migrate';

getSettings is exported from a separate subpath 'graphile-migrate/settings'.

Connects to PostgreSQL and runs all pending migrations using runMigrations and parseSettings.

import { runMigrations, parseSettings } from 'graphile-migrate'; async function main() { const settings = parseSettings({ connectionString: process.env.DATABASE_URL ?? '', }); try { await runMigrations(settings); console.log('Migrations completed successfully'); } catch (error) { console.error('Migration failed:', error.message); process.exit(1); } } main();

Debug

Known issues

breakingIn v1.0.0, the API changed from callback-based to promise-based. runMigrations no longer accepts a callback.

fix

Use async/await with runMigrations.

affects: <1.0.0

deprecated`migrate` function was deprecated in v1.4.0; use `runMigrations` instead.

fix

Replace calls to migrate() with runMigrations().

affects: >=1.4.0

gotchaSettings object must include `connectionString`; using environment variable is recommended.

fix

Set DATABASE_URL environment variable and pass connectionString: process.env.DATABASE_URL

affects: >=1.0.0

gotchaWatch mode (`--watch`) re-runs migrations on SQL file changes; ensure idempotent SQL to avoid errors.

fix

Write migrations using DROP IF EXISTS, CREATE OR REPLACE, etc.

affects: >=1.0.0

gotchaThe package uses ESM; using require() may fail unless you use .default.

fix

Use dynamic import or enable ESM in Node.js.

affects: >=1.0.0

Errors

Common errors & fixes

Error: Must provide a connection string or a client

Missing connectionString in settings or DATABASE_URL not set.

fix

Set process.env.DATABASE_URL or pass connectionString in parseSettings.

Error: Cannot find module 'graphile-migrate'

Package not installed.

fix

Run `npm install graphile-migrate`.

TypeError: migrate is not a function

Using named import incorrectly (trying default import instead of named).

fix

Use `import { migrate } from 'graphile-migrate';` or use default import with `.default` if using require.

Error: SQL file not found: /path/to/migration.sql

Migration file path does not exist.

fix

Ensure migration files are in the correct directory (default 'migrations/').

Upgrade

Version history

1.4.1latest on npm

Audit

Dependencies

pgrequiredPostgreSQL client

Agent activity

4 hits · last 30 days

node

Resources

githubssh://git@github.com/graphile/migrate ↗

packagegraphile-migrate ↗

homepagehttps://github.com/graphile/migrate#readme ↗