{"id":43593,"library":"pg-toolbox","title":"pg-toolbox","description":"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.","status":"active","version":"1.1.34","language":"javascript","source_language":"en","source_url":"https://github.com/WilliamConnatser/pg-toolbox","tags":["javascript","pg","postgres","helpers","migrate","rollback","seed"],"install":[{"cmd":"npm install pg-toolbox","lang":"bash","label":"npm"},{"cmd":"yarn add pg-toolbox","lang":"bash","label":"yarn"},{"cmd":"pnpm add pg-toolbox","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for the sql template tag used in toolbox files; listed as a peer dependency for the package to function.","package":"slonik","optional":false},{"reason":"Used to load environment variables (PGURI, PGMIGRATIONS) for CLI commands; typically a dev dependency but needed at runtime.","package":"dotenv","optional":true}],"imports":[{"note":"CJS require works in older versions but ESM is recommended; the package exports the sql tagged template from slonik.","wrong":"const { sql } = require('pg-toolbox')","symbol":"sql","correct":"import { sql } from 'pg-toolbox'"},{"note":"Default import provides a CLI runner or main object; not directly used in toolbox files.","wrong":"","symbol":"default","correct":"import pgToolbox from 'pg-toolbox'"},{"note":"Named exports for programmatic API may not exist; prefer the CLI interface.","wrong":"const migrate = require('pg-toolbox').migrate","symbol":"migrate","correct":"import { migrate } from 'pg-toolbox'"}],"quickstart":{"code":"// Install as dev dependency\nnpm install pg-toolbox --save-dev\n\n// Create .env file in project root\nPGURI=postgres://user:pass@localhost:5432/mydb\nPGMIGRATIONS=./db/migrations\n\n// Create a migration file: ./db/migrations/001-create-users.js\nconst { sql } = require('pg-toolbox');\n\nmodule.exports = async () => ({\n  migrate: sql`CREATE TABLE users (\n    id SERIAL PRIMARY KEY,\n    name VARCHAR(100) NOT NULL\n  )`,\n  rollback: sql`DROP TABLE IF EXISTS users`,\n  seed: sql`INSERT INTO users (name) VALUES ('Alice'), ('Bob')`\n});\n\n// Run migrations (development only)\nnpx pg-toolbox migrate","lang":"javascript","description":"This shows installation, environment setup, creating a migration file with the expected export format, and running the migration via CLI."},"warnings":[{"fix":"Wait for v1.2.0 release or pin to stable once available. Avoid relying on the current API contract.","message":"API is unstable in versions <1.2.0. The author explicitly warns against using the package until v1.2 due to frequent breaking changes.","severity":"breaking","affected_versions":"<1.2.0"},{"fix":"Ensure every toolbox file exports an async function returning { migrate: sql`...`, rollback: sql`...`, seed?: ..., truncate?: ... }.","message":"Toolbox 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Monitor release notes; use Node.js 20+ and --env-file as an alternative, or manually load environment variables.","message":"The dotenv dependency is used directly; some future versions may remove dotenv in favor of Node.js --env-file flag.","severity":"deprecated","affected_versions":">=1.1.0"},{"fix":"Use zero-padded numeric prefixes or ISO 8601 timestamps (e.g., '20250101') to guarantee correct ordering.","message":"Migrations 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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"search_vec":"'1.1.34':29 'advis':41 'alongsid':23 'alphabet':93 'api':82 'async':99 'author':40 'break':86 'chang':87 'cjs':73 'cli':9 'client':27 'contain':107 'databas':13 'depend':63,71 'design':19 'dev':70 'dotenv':65 'esm':75 'export':97 'file':95 'format':77 'function':100 'helper':115 'javascript':112 'key':106 'knex.js':46 'mark':31 'migrat':14,90,116 'migrate/rollback/seed/truncate':105 'modul':76 'must':96 'object':103 'order':92 'orm':48 'packag':50 'pg':2,5,113 'pg-toolbox':1,4 'postgr':114 'postgresql':12 'product':38,62 'promot':51 'pure':53 'recommend':36 'return':101 'rollback':15,117 'seed':16,118 'skill':58 'slonik':25,67,108 'sql':26,54,57,109 'strengthen':56 'subject':84 'support':79 'tag':110 'templat':111 'tool':10 'toolbox':3,6 'truncat':18 'unlik':45 'unstabl':33 'use':22,64 'v1.2':44,89 'version':28 'wait':42 'write':52 'zero':61","created_at":"2026-06-05T17:00:32.373418+00:00","updated_at":"2026-06-05T17:00:32.373418+00:00","problems":[{"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.","cause":"Package not installed or installed as dev dependency but used in production.","error":"Error: Cannot find module 'pg-toolbox'"},{"fix":"Use the sql tagged template: `sql`CREATE TABLE ...`, not `sql('...')`.","cause":"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.","error":"TypeError: sql is not a function"},{"fix":"Check PGMIGRATIONS path in .env: it should be relative to project root. Ensure the directory exists and contains .js migration files.","cause":"PGMIGRATIONS environment variable points to a directory that does not exist or contains no valid .js files exporting the correct structure.","error":"No toolbox files found at path /path/to/folder"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"https://github.com/WilliamConnatser/pg-toolbox#readme","github":"https://github.com/WilliamConnatser/pg-toolbox","docs":null,"changelog":null,"pypi":null,"npm":"pg-toolbox","openapi_spec":null,"status_page":null,"smithery":null,"categories":["database"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-05","next_check":"2026-09-03","install_tag":null}}