dmut

library0.5.7jsnpmunverified

A PostgreSQL migration utility that lets you write migrations in SQL, with support for modular namespaces, automatic down migration storage in the database, and code tracking for functions and triggers. Current stable version: 0.5.7. Release cadence is irregular. Key differentiators: no ORM lock-in, no need to write separate down migration files (downs are stored in DB), and a focus on server-side PL code management. Primarily for developers who treat PostgreSQL as the application platform, not just a data store.

database

npm install dmut

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · DMUT

dmut

databasejavascriptv0.5.7

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.

pgMutate

✓ import pgMutate from 'pgmutate'

✗ const pgMutate = require('pgmutate')

Default import works in both ESM and CJS projects; pgMutate is CommonJS internally but exports a default.

✓ import { up } from 'pgmutate'

✗ const { up } = require('pgmutate')

Named export 'up' is available starting v0.5.0; previously it was only accessible as pgMutate.up.

down

✓ import { down } from 'pgmutate'

Named export 'down' available since v0.5.0.

config

✓ import { config } from 'pgmutate'

✗ import config from 'pgmutate/config'

Config is a named export, not a separate module.

Shows initialization, running all pending migrations, and rolling back one step.

import pgMutate, { up } from 'pgmutate'; // Initialize with connection string from environment const mutator = pgMutate({ databaseUrl: process.env.DATABASE_URL ?? 'postgres://user:pass@localhost:5432/mydb' }); // Run all pending migrations await mutator.up(); // Or use the 'up' function directly await up({ databaseUrl: process.env.DATABASE_URL }); // Rollback one migration await mutator.down({ steps: 1 });

Debug

Known issues

gotchapgmutate stores down migration SQL in the database; if you lose the database, you cannot automatically rollback. Always back up down migration SQL or version control it separately.

fix

Periodically export down migrations using `pgmutate dump-downs` or maintain manual SQL scripts.

affects: >=0.0.1

deprecatedThe `track` and `untrack` CLI commands for file operations are deprecated as of v0.5.0 and may be removed in a future major release.

fix

Use the `auto/` directory mechanism for code files instead of manual tracking.

affects: >=0.5.0

breakingVersion 0.5.0 changed the default migration directory structure; old projects may not find pgmutate.json if it is placed in the project root. Ensure pgmutate.json is in the `migrations/` directory or specify the path explicitly.

fix

Move pgmutate.json to `migrations/` or use the `--config` option to point to the correct location.

affects: >=0.5.0

gotchapgmutate relies on filename ordering for migration sequence. If two migrations have the same timestamp prefix, the order is undefined. Use sequences like '001', '002' or timestamps with millisecond precision.

fix

Ensure migration filenames are unique and sort correctly (e.g., YYYYMMDDHHMMSS.sql).

affects: >=0.0.1

gotchaDown migrations are stored in the database and are not automatically version-controlled. If you deploy a new version without running down migrations, you might have orphaned objects or incompatible state.

fix

Always run down migrations before reverting code changes, or keep a manual log of down SQL.

affects: >=0.0.1

Errors

Common errors & fixes

Error: Cannot find module 'pgmutate'

pgmutate is not installed or import path is wrong.

fix

Run `npm install pgmutate --save-dev` and ensure your import is correct: `import pgMutate from 'pgmutate'`.

pgmutate: no pgmutate.json found

pgmutate looks for pgmutate.json in the current directory and parent directories; if not present, it errors.

fix

Create a pgmutate.json file in the root of your migration directory (default is `migrations/`).

Error: connect ECONNREFUSED ::1:5432

No PostgreSQL server running or wrong connection string.

fix

Start your PostgreSQL server or set the DATABASE_URL environment variable to a valid connection string.

TypeError: pgMutate is not a function

Using a named import for something that expects default import.

fix

Use `import pgMutate from 'pgmutate'` instead of `import { pgMutate } from 'pgmutate'`.

Upgrade

Version history

0.5.7latest on npm

Audit

Dependencies

pgrequiredPostgreSQL client for Node.js

Agent activity

25 hits · last 30 days

node

Resources

githubhttps://github.com/ceymard/dmut ↗

packagedmut ↗

homepagehttps://github.com/ceymard/dmut#readme ↗