{"id":49413,"library":"sqerge","title":"sqerge","description":"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.","status":"active","version":"3.2.0","language":"javascript","source_language":"en","source_url":"https://github.com/eezing/sqerge","tags":["javascript","postgres","postgresql","sql","migrate","migration","schema","typescript"],"install":[{"cmd":"npm install sqerge","lang":"bash","label":"npm"},{"cmd":"yarn add sqerge","lang":"bash","label":"yarn"},{"cmd":"pnpm add sqerge","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Postgres.js library used for database connection and query execution","package":"postgres","optional":false}],"imports":[{"note":"CLI tool, typically run via npx. Ensure postgres.js is installed as a dependency.","wrong":"sqerge <directory> (without npx, if not installed globally)","symbol":"sqerge CLI","correct":"npx sqerge <directory>"},{"note":"For .js files, use CommonJS default export. For .mjs, use default export.","wrong":"export default async (sql) => { ... } (only works in ESM files with .mjs extension)","symbol":"JavaScript migration default export","correct":"module.exports = async (sql) => { ... }"},{"note":"sqerge does not export TypeScript types for direct use; the sql parameter type is from postgres.","wrong":"import { Sql } from 'sqerge' (no such export)","symbol":"TypeScript types","correct":"No explicit import needed; types are shipped but used implicitly via Postgres.js instance"}],"quickstart":{"code":"mkdir migrations\ncat > migrations/1-create-users.sql << EOF\nCREATE TABLE users (\n  id SERIAL PRIMARY KEY,\n  name text NOT NULL\n);\nEOF\ncat > migrations/2-insert-user.js << EOF\nmodule.exports = async (sql) => {\n  await sql`INSERT INTO users (name) VALUES ('Alice')`;\n};\nEOF\nPGHOST=localhost PGPORT=5432 PGUSER=postgres PGPASSWORD= PGDATABASE=mydb npx sqerge migrations","lang":"typescript","description":"Creates a migration directory with SQL and JS files, then runs sqerge with environment variables for database connection."},"warnings":[{"fix":"Upgrade Node.js to version 20 or higher.","message":"sqerge v3 removed support for Node.js versions below 20. Ensure Node >= 20.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Install postgres@^3.x as a dependency.","message":"sqerge v3 requires postgres.js peer dependency version ^3.x; incompatible with postgres.js v2 or v4.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Migrate from 'pg' to 'postgres.js' and update any custom migration scripts.","message":"Previous versions used 'pg' library, but v3 switched to 'postgres.js'. Old migrations relying on 'pg' may not work.","severity":"deprecated","affected_versions":">=3.0.0"},{"fix":"Ensure all migration files follow the pattern '<integer>-<any-name>.sql' or '<integer>-<any-name>.js' or '<integer>-<any-name>.mjs'.","message":"Migration filenames must start with a unique integer followed by a hyphen; otherwise they are ignored.","severity":"gotcha","affected_versions":">=3.0.0"},{"fix":"Ensure the database user has permission to assume the specified role (e.g., via membership).","message":"ROLE 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.","severity":"gotcha","affected_versions":">=3.0.0"}],"env_vars":null,"search_vec":"'3.2.0':15 'connect':38 'current':11 'databas':37 'differenti':22 'environ':34 'file':31 'focus':47 'forward':4,50 'forward-on':3,49 'github':20 'javascript':56 'js/esm':29 'key':21 'librari':25 'manag':44 'migrat':7,30,52,55,60,61 'minim':45 'need':18 'option':39 'postgr':57 'postgres.js':10,24 'postgresql':6,58 'privileg':43 'releas':16 'reli':32 'role':40 'schema':62 'set':41 'sqerg':1 'sql':27,59 'stabl':12 'support':26 'tool':8 'typescript':63 'use':9,23 'variabl':35 'version':13 'without':53","created_at":"2026-06-07T17:01:39.715631+00:00","updated_at":"2026-06-07T17:01:39.715631+00:00","problems":[{"fix":"Run 'npm install postgres' in your project.","cause":"postgres.js peer dependency not installed.","error":"Error: Cannot find module 'postgres'"},{"fix":"Grant the role to the user or remove the ROLE variable.","cause":"The ROLE environment variable is set but the current user cannot assume that role.","error":"error: permission denied to set role"},{"fix":"Rename file to e.g., '1-foo.sql'.","cause":"Filename missing integer prefix and hyphen.","error":"Error: Migration file 'foo.sql' does not match pattern"}],"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/eezing/sqerge#readme","github":"https://github.com/eezing/sqerge","docs":null,"changelog":null,"pypi":null,"npm":"sqerge","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-07","next_check":"2026-09-05","install_tag":null}}