{"id":43671,"library":"postgres-migrate","title":"postgres-migrate","description":"PostgreSQL migration tool using advisory locks for safe concurrent execution. Version 1.1.2 is the latest stable release with low maintenance cadence. Executes .sql migration files sequentially with automatic locking to prevent race conditions. Minimal configuration, supports custom reporters and connection strings. Differentiates from alternatives like node-pg-migrate by its simplicity and reliance on PostgreSQL advisory locks.","status":"active","version":"1.1.2","language":"javascript","source_language":"en","source_url":null,"tags":["javascript"],"install":[{"cmd":"npm install postgres-migrate","lang":"bash","label":"npm"},{"cmd":"yarn add postgres-migrate","lang":"bash","label":"yarn"},{"cmd":"pnpm add postgres-migrate","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"PostgreSQL client for database connection","package":"pg","optional":false}],"imports":[{"note":"The module exports a default function. Named export does not exist.","wrong":"const { migrate } = require('postgres-migrate')","symbol":"default (migrate)","correct":"import migrate from 'postgres-migrate'"},{"note":"CommonJS require works as default import.","wrong":null,"symbol":"default (migrate) with require","correct":"const migrate = require('postgres-migrate')"},{"note":"Type definitions may not be bundled; use @types/postgres-migrate if available, or declare module.","wrong":"import * as migrate from 'postgres-migrate'","symbol":"TypeScript usage","correct":"import migrate from 'postgres-migrate'"},{"note":"Direct default import is the intended pattern.","wrong":"import { default as migrate } from 'postgres-migrate'","symbol":"Default export (ESM)","correct":"import migrate from 'postgres-migrate'"}],"quickstart":{"code":"const migrate = require('postgres-migrate');\n\nmigrate({\n    conString: 'postgres://' + process.env.PGUSER + ':' + process.env.PGPASSWORD + '@' + process.env.PGHOST + ':5432/' + process.env.PGDATABASE,\n    migrationsDir: './migrations',\n    reporter: console.log.bind(console)\n}).then(() => {\n    console.log('Migrations completed');\n}).catch((err) => {\n    console.error('Migration failed:', err);\n});","lang":"javascript","description":"Shows minimal setup to run SQL migrations from a directory against a PostgreSQL database using connection string from environment variables."},"warnings":[{"fix":"Ensure all migration files have .sql extension and no other files in the directory.","message":"migrationsDir must contain only .sql files; non-.sql files may cause errors or be ignored.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Use an existing pg client instance or switch to 'client' option if supported.","message":"The 'conString' option is deprecated in favor of using 'pg' client's connection configuration.","severity":"deprecated","affected_versions":">=1.0.0"},{"fix":"Upgrade PostgreSQL to 9.4 or later.","message":"Advisory lock requires PostgreSQL 9.4+; older versions will fail silently.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Check the 'reporter' function logs for detailed error messages.","message":"Promise rejection on migration failure may not include full stack trace due to internal error handling.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Implement a manual timeout or use a monitoring tool to release stale locks.","message":"Multiple workers will wait indefinitely if the lock is held by a crashed worker (no timeout).","severity":"gotcha","affected_versions":">=0.0.0"}],"env_vars":null,"search_vec":"'1.1.2':15 'advisori':8,60 'altern':47 'automat':31 'cadenc':24 'concurr':12 'condit':36 'configur':38 'connect':43 'custom':40 'differenti':45 'execut':13,25 'file':28 'javascript':62 'latest':18 'like':48 'lock':9,32,61 'low':22 'mainten':23 'migrat':3,5,27,52 'minim':37 'node':50 'node-pg-migr':49 'pg':51 'postgr':2 'postgres-migr':1 'postgresql':4,59 'prevent':34 'race':35 'releas':20 'relianc':57 'report':41 'safe':11 'sequenti':29 'simplic':55 'sql':26 'stabl':19 'string':44 'support':39 'tool':6 'use':7 'version':14","created_at":"2026-06-05T17:00:55.036909+00:00","updated_at":"2026-06-05T17:00:55.036909+00:00","problems":[{"fix":"Start PostgreSQL service and verify connection string.","cause":"PostgreSQL server not running or incorrect host/port.","error":"Error: connect ECONNREFUSED <host>:<port>"},{"fix":"Create the migrations table manually: CREATE TABLE IF NOT EXISTS migrations (id SERIAL PRIMARY KEY, name VARCHAR(255) UNIQUE, run_on TIMESTAMP DEFAULT NOW());","cause":"Migrations table not created automatically; package expects it to exist.","error":"error: relation \"migrations\" does not exist"},{"fix":"Use const migrate = require('postgres-migrate') (not destructured).","cause":"Using named import instead of default import.","error":"TypeError: migrate is not a function"},{"fix":"Check that the migrations directory path is absolute or relative to working directory.","cause":"migrationsDir path does not exist or is incorrect.","error":"Error: ENOENT: no such file or directory, scandir '...'"},{"fix":"Grant necessary privileges: GRANT CREATE ON SCHEMA public TO <user>;","cause":"Database user lacks CREATE TABLE permissions.","error":"error: permission denied for schema public"}],"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":null,"github":null,"docs":null,"changelog":null,"pypi":null,"npm":"postgres-migrate","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}}