pg-toolbox

library1.1.34jsnpmunverified

pg-toolbox is a CLI tool for PostgreSQL database migrations, rollbacks, seeding, and truncation, designed to be used alongside the slonik SQL client. Version 1.1.34 is marked as unstable and not recommended for production—the author advises waiting for v1.2+. Unlike Knex.js or ORMs, this package promotes writing pure SQL to strengthen SQL skills. It has zero production dependencies, using dotenv and slonik only as dev dependencies. Both CJS and ESM module formats are supported, but the API is subject to breaking changes until v1.2. Migrations are ordered alphabetically, and files must export an async function returning an object with migrate/rollback/seed/truncate keys containing slonik SQL tagged templates.

database

npm install pg-toolbox

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · PG-TOOLBOX

pg-toolbox

databasejavascriptv1.1.34

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.

sql

✓ import { sql } from 'pg-toolbox'

✗ const { sql } = require('pg-toolbox')

CJS require works in older versions but ESM is recommended; the package exports the sql tagged template from slonik.

default

✓ import pgToolbox from 'pg-toolbox'

Default import provides a CLI runner or main object; not directly used in toolbox files.

migrate

✓ import { migrate } from 'pg-toolbox'

✗ const migrate = require('pg-toolbox').migrate

Named exports for programmatic API may not exist; prefer the CLI interface.

This shows installation, environment setup, creating a migration file with the expected export format, and running the migration via CLI.

// Install as dev dependency npm install pg-toolbox --save-dev // Create .env file in project root PGURI=postgres://user:pass@localhost:5432/mydb PGMIGRATIONS=./db/migrations // Create a migration file: ./db/migrations/001-create-users.js const { sql } = require('pg-toolbox'); module.exports = async () => ({ migrate: sql`CREATE TABLE users ( id SERIAL PRIMARY KEY, name VARCHAR(100) NOT NULL )`, rollback: sql`DROP TABLE IF EXISTS users`, seed: sql`INSERT INTO users (name) VALUES ('Alice'), ('Bob')` }); // Run migrations (development only) npx pg-toolbox migrate

Debug

Known issues

breakingAPI is unstable in versions <1.2.0. The author explicitly warns against using the package until v1.2 due to frequent breaking changes.

fix

Wait for v1.2.0 release or pin to stable once available. Avoid relying on the current API contract.

affects: <1.2.0

gotchaToolbox files must export an async function that returns an object with exactly 'migrate' and 'rollback' keys; 'seed' and 'truncate' are optional. Missing required keys causes silent failures.

fix

Ensure every toolbox file exports an async function returning { migrate: sql`...`, rollback: sql`...`, seed?: ..., truncate?: ... }.

affects: >=1.0.0

deprecatedThe dotenv dependency is used directly; some future versions may remove dotenv in favor of Node.js --env-file flag.

fix

Monitor release notes; use Node.js 20+ and --env-file as an alternative, or manually load environment variables.

affects: >=1.1.0

gotchaMigrations are executed in alphabetical file name order. If numeric prefixes are used (e.g., 001, 002), ensure they sort correctly; otherwise migration order may be unexpected.

fix

Use zero-padded numeric prefixes or ISO 8601 timestamps (e.g., '20250101') to guarantee correct ordering.

affects: >=1.0.0

Errors

Common errors & fixes

Error: Cannot find module 'pg-toolbox'

Package not installed or installed as dev dependency but used in production.

fix

Ensure pg-toolbox is installed: `npm install pg-toolbox --save-dev`. If running in production, consider moving to dependencies or using a production-compatible fork.

TypeError: sql is not a function

Importing 'sql' from pg-toolbox incorrectly: the 'sql' export is a template literal tag, not a function. Using it without backticks or calling it as a function fails.

fix

Use the sql tagged template: `sql`CREATE TABLE ...`, not `sql('...')`.

No toolbox files found at path /path/to/folder

PGMIGRATIONS environment variable points to a directory that does not exist or contains no valid .js files exporting the correct structure.

fix

Check PGMIGRATIONS path in .env: it should be relative to project root. Ensure the directory exists and contains .js migration files.

Upgrade

Version history

1.1.34latest on npm

Audit

Dependencies

slonikrequiredRequired for the sql template tag used in toolbox files; listed as a peer dependency for the package to function.

dotenvoptionalUsed to load environment variables (PGURI, PGMIGRATIONS) for CLI commands; typically a dev dependency but needed at runtime.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/WilliamConnatser/pg-toolbox ↗

packagepg-toolbox ↗

homepagehttps://github.com/WilliamConnatser/pg-toolbox#readme ↗