{"id":43922,"library":"sql-migrations","title":"node-sql-migrations","description":"A simple Node.js library for running raw SQL database migrations. Current stable version is 1.0.7, with infrequent releases. It supports PostgreSQL and MySQL via the 'pg' and 'mysql' npm packages as runtime adapters. Key differentiators include a simple file-based migration system, CLI and programmatic API, customizable parameter substitution in SQL scripts, and optional migration time filtering. Suitable for projects that prefer plain SQL over ORM-based migrations.","status":"active","version":"1.0.7","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/dmitriiabramov/node-sql-migrations","tags":["javascript","node","sql","database","migration"],"install":[{"cmd":"npm install sql-migrations","lang":"bash","label":"npm"},{"cmd":"yarn add sql-migrations","lang":"bash","label":"yarn"},{"cmd":"pnpm add sql-migrations","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"PostgreSQL adapter – required if using pg adapter","package":"pg","optional":true},{"reason":"MySQL adapter – required if using mysql adapter","package":"mysql","optional":true}],"imports":[{"note":"Package is CommonJS only, no ESM exports.","wrong":"import { run } from 'sql-migrations';","symbol":"run","correct":"const { run } = require('sql-migrations');"},{"note":"Destructuring works; direct property access also fine.","wrong":"const migrate = require('sql-migrations').migrate;","symbol":"migrate","correct":"const { migrate } = require('sql-migrations');"},{"note":"Same as migrate.","wrong":"const rollback = require('sql-migrations').rollback;","symbol":"rollback","correct":"const { rollback } = require('sql-migrations');"}],"quickstart":{"code":"const path = require('path');\nconst { run } = require('sql-migrations');\n\nrun({\n  migrationsDir: path.resolve(__dirname, 'migrations'),\n  host: 'localhost',\n  port: 5432,\n  db: 'my_database',\n  user: 'user',\n  password: process.env.DB_PASSWORD ?? '',\n  adapter: 'pg',\n  parameters: {\n    TABLE_NAME: 'users'\n  }\n});","lang":"javascript","description":"Shows how to run database migrations programmatically using the pg adapter."},"warnings":[{"fix":"Ensure migration filenames start with a 13-digit Unix timestamp followed by underscore.","message":"Migration files must be named with Unix timestamp in milliseconds (e.g., 1415860098827_up_migration_name.sql). Invalid filenames are silently ignored.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Manually create the database before running migrations.","message":"The library does not create the database; it only connects to an existing one.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Sanitize or validate parameters before passing them.","message":"Parameter substitution uses simple string replacement. SQL injection possible if parameters come from untrusted input.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Use setLogger() to provide a custom logger with log and error methods.","message":"The library uses the global `console` object for logging by default. Custom logger must implement both `log` and `error` methods.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Pass new Date('2018-01-01').getTime() instead of the Date object directly.","message":"minMigrationTime option expects a timestamp in milliseconds (number), not a Date object.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"search_vec":"'1.0.7':19 'adapt':37 'api':51 'base':45,73 'cli':48 'current':15 'customiz':52 'databas':13,78 'differenti':39 'file':44 'file-bas':43 'filter':62 'includ':40 'infrequ':21 'javascript':75 'key':38 'librari':8 'migrat':4,14,46,60,74,79 'mysql':27,32 'node':2,76 'node-sql-migr':1 'node.js':7 'npm':33 'option':59 'orm':72 'orm-bas':71 'packag':34 'paramet':53 'pg':30 'plain':68 'postgresql':25 'prefer':67 'programmat':50 'project':65 'raw':11 'releas':22 'run':10 'runtim':36 'script':57 'simpl':6,42 'sql':3,12,56,69,77 'stabl':16 'substitut':54 'suitabl':63 'support':24 'system':47 'time':61 'version':17 'via':28","created_at":"2026-06-05T17:02:07.796314+00:00","updated_at":"2026-06-05T17:02:07.796314+00:00","problems":[{"fix":"Provide migrationsDir: path.resolve(__dirname, 'migrations') in config.","cause":"Missing required migrationsDir property in configuration object.","error":"Error: The 'migrationsDir' configuration option is missing"},{"fix":"Run: npm install pg","cause":"pg adapter selected but pg package not installed.","error":"Cannot find module 'pg'"},{"fix":"Ensure migrationsDir is correct and migration files exist.","cause":"Migration directory missing or incorrect path.","error":"Error: Migration file 1415860098827_up_migration_name.sql not found"}],"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/dmitriiabramov/node-sql-migrations#readme","github":"ssh://git@github.com/dmitriiabramov/node-sql-migrations","docs":null,"changelog":null,"pypi":null,"npm":"sql-migrations","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}}