sqerge

library3.2.0jsnpmunverified

A forward-only PostgreSQL migration tool using Postgres.js. Current stable version is 3.2.0. Released as needed on GitHub. Key differentiators: uses Postgres.js library, supports SQL and JS/ESM migration files, relies on environment variables for database connection, optional ROLE setting for privilege management. Minimal and focused on forward-only migrations without down migrations.

database

npm install sqerge

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · SQERGE

sqerge

databasejavascriptv3.2.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.

sqerge CLI

✓ npx sqerge <directory>

✗ sqerge <directory> (without npx, if not installed globally)

CLI tool, typically run via npx. Ensure postgres.js is installed as a dependency.

JavaScript migration default export

✓ module.exports = async (sql) => { ... }

✗ export default async (sql) => { ... } (only works in ESM files with .mjs extension)

For .js files, use CommonJS default export. For .mjs, use default export.

TypeScript types

✓ No explicit import needed; types are shipped but used implicitly via Postgres.js instance

✗ import { Sql } from 'sqerge' (no such export)

sqerge does not export TypeScript types for direct use; the sql parameter type is from postgres.

Creates a migration directory with SQL and JS files, then runs sqerge with environment variables for database connection.

mkdir migrations cat > migrations/1-create-users.sql << EOF CREATE TABLE users ( id SERIAL PRIMARY KEY, name text NOT NULL ); EOF cat > migrations/2-insert-user.js << EOF module.exports = async (sql) => { await sql`INSERT INTO users (name) VALUES ('Alice')`; }; EOF PGHOST=localhost PGPORT=5432 PGUSER=postgres PGPASSWORD= PGDATABASE=mydb npx sqerge migrations

Debug

Known issues

breakingsqerge v3 removed support for Node.js versions below 20. Ensure Node >= 20.

fix

Upgrade Node.js to version 20 or higher.

affects: >=3.0.0

breakingsqerge v3 requires postgres.js peer dependency version ^3.x; incompatible with postgres.js v2 or v4.

fix

Install postgres@^3.x as a dependency.

affects: >=3.0.0

deprecatedPrevious versions used 'pg' library, but v3 switched to 'postgres.js'. Old migrations relying on 'pg' may not work.

fix

Migrate from 'pg' to 'postgres.js' and update any custom migration scripts.

affects: >=3.0.0

gotchaMigration filenames must start with a unique integer followed by a hyphen; otherwise they are ignored.

fix

Ensure all migration files follow the pattern '<integer>-<any-name>.sql' or '<integer>-<any-name>.js' or '<integer>-<any-name>.mjs'.

affects: >=3.0.0

gotchaROLE environment variable sets a database role via SET ROLE; the role must have necessary privileges and the connection user must be able to SET ROLE to that role.

fix

Ensure the database user has permission to assume the specified role (e.g., via membership).

affects: >=3.0.0

Errors

Common errors & fixes

Error: Cannot find module 'postgres'

postgres.js peer dependency not installed.

fix

Run 'npm install postgres' in your project.

error: permission denied to set role

The ROLE environment variable is set but the current user cannot assume that role.

fix

Grant the role to the user or remove the ROLE variable.

Error: Migration file 'foo.sql' does not match pattern

Filename missing integer prefix and hyphen.

fix

Rename file to e.g., '1-foo.sql'.

Upgrade

Version history

3.2.0latest on npm

Audit

Dependencies

postgresrequiredPostgres.js library used for database connection and query execution

Agent activity

17 hits · last 30 days

node