{"id":43682,"library":"postgres-shift","title":"postgres-shift","description":"A simple forwards-only migration tool designed specifically for postgres.js. Version 0.1.0 provides a single function to run SQL migrations in order. It is lightweight, has no external dependencies beyond postgres.js, and follows the philosophy of the parent library. Ideal for projects already using postgres.js who want minimal migration overhead without the complexity of other tools.","status":"active","version":"0.1.0","language":"javascript","source_language":"en","source_url":"https://github.com/porsager/postgres-shift","tags":["javascript","migration","driver","postgresql","postgres.js","postgres","postgre","client","sql"],"install":[{"cmd":"npm install postgres-shift","lang":"bash","label":"npm"},{"cmd":"yarn add postgres-shift","lang":"bash","label":"yarn"},{"cmd":"pnpm add postgres-shift","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Runtime peer dependency; postgres-shift requires a postgres.js sql instance to execute migrations","package":"postgres"}],"imports":[{"note":"The library is ESM-only; CommonJS require will fail. Use import or dynamic import.","wrong":"const shift = require('postgres-shift')","symbol":"shift","correct":"import { shift } from 'postgres-shift'"}],"quickstart":{"code":"import { shift } from 'postgres-shift';\nimport postgres from 'postgres';\n\nconst sql = postgres(process.env.DATABASE_URL ?? '');\n\n// Run all pending migrations from the 'migrations' folder\nawait shift({ sql, path: './migrations' });\n\n// Optional: specify a custom migrations table name\nawait shift({ sql, path: './migrations', table: '_migrations' });\n\nconsole.log('Migrations complete');","lang":"typescript","description":"Imports the shift function, connects to PostgreSQL using postgres.js, and runs migrations from a local directory."},"warnings":[{"fix":"Use import { shift } from 'postgres-shift' or dynamic import('postgres-shift') instead of require().","message":"The library is ESM-only and does not support CommonJS. Using require() will throw an error.","severity":"breaking","affected_versions":">=0.1.0"},{"fix":"Ensure you import and create a postgres.js instance with postgres(connectionString) and pass sql to shift.","message":"The shift function expects a postgres.js sql object, not a pg client or any other database driver. Using an incompatible driver will cause errors.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Name migration files with a timestamp or sequential number (e.g., 001_create_users.sql, 002_add_email.sql).","message":"The migration file naming convention matters; files are sorted alphabetically and applied in order. Non-standard sorting may lead to unexpected migration order.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"search_vec":"'0.1.0':16 'alreadi':47 'beyond':34 'client':68 'complex':57 'depend':33 'design':11 'driver':63 'extern':32 'follow':37 'forward':7 'forwards-on':6 'function':20 'ideal':44 'javascript':61 'librari':43 'lightweight':29 'migrat':9,24,53,62 'minim':52 'order':26 'overhead':54 'parent':42 'philosophi':39 'postgr':2,66,67 'postgres-shift':1 'postgres.js':14,35,49,65 'postgresql':64 'project':46 'provid':17 'run':22 'shift':3 'simpl':5 'singl':19 'specif':12 'sql':23,69 'tool':10,60 'use':48 'version':15 'want':51 'without':55","created_at":"2026-06-05T17:00:59.024631+00:00","updated_at":"2026-06-05T17:00:59.024631+00:00","problems":[{"fix":"Use import { shift } from 'postgres-shift' in your code, or if using CommonJS, use dynamic import: const { shift } = await import('postgres-shift');","cause":"Trying to use require() instead of import for the ESM-only package.","error":"Error [ERR_REQUIRE_ESM]: require() of ES Module not supported"},{"fix":"Ensure you have imported postgres from 'postgres' and created the sql object correctly: const sql = postgres(connectionString); Then pass sql to shift().","cause":"The shift function received an incorrect object instead of a postgres.js sql instance.","error":"TypeError: sql is not a function"}],"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/porsager/postgres-shift#readme","github":"https://github.com/porsager/postgres-shift","docs":null,"changelog":null,"pypi":null,"npm":"postgres-shift","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}}