{"id":16451774,"url":"https://github.com/thebearingedge/pg-bump","last_synced_at":"2025-10-07T23:49:36.371Z","repository":{"id":40610302,"uuid":"90567600","full_name":"thebearingedge/pg-bump","owner":"thebearingedge","description":":elephant: A minimalist SQL migration CLI for PostgreSQL.","archived":false,"fork":false,"pushed_at":"2023-03-14T17:31:02.000Z","size":287,"stargazers_count":13,"open_issues_count":0,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-18T19:36:29.777Z","etag":null,"topics":["migrations","node-cli","npm-package","postgresql","sql"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/thebearingedge.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-05-07T23:11:14.000Z","updated_at":"2024-04-04T12:09:18.000Z","dependencies_parsed_at":"2024-10-11T10:20:28.693Z","dependency_job_id":null,"html_url":"https://github.com/thebearingedge/pg-bump","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thebearingedge%2Fpg-bump","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thebearingedge%2Fpg-bump/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thebearingedge%2Fpg-bump/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thebearingedge%2Fpg-bump/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/thebearingedge","download_url":"https://codeload.github.com/thebearingedge/pg-bump/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245081972,"owners_count":20557877,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["migrations","node-cli","npm-package","postgresql","sql"],"created_at":"2024-10-11T10:10:20.335Z","updated_at":"2025-10-07T23:49:31.296Z","avatar_url":"https://github.com/thebearingedge.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"pg-bump\n--\n\nSQL migration CLI for PostgreSQL.\n\n[![Github Actions Test Status](https://github.com/thebearingedge/pg-bump/workflows/Test/badge.svg?branch=main)](https://github.com/thebearingedge/pg-bump/actions?query=workflow%3ATest+branch%3Amain)\n[![codecov](https://codecov.io/gh/thebearingedge/pg-bump/branch/main/graph/badge.svg)](https://codecov.io/gh/thebearingedge/pg-bump)\n[![Greenkeeper badge](https://badges.greenkeeper.io/thebearingedge/pg-bump.svg)](https://greenkeeper.io/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n## What is it?\n\n`pg-bump` provides command line management of PostgreSQL database schema migrations authored in \"Plain SQL\". It presumes that **a)** you are [checking schema migrations into source control](https://blog.codinghorror.com/get-your-database-under-version-control/) and **b)** you are [using environment variables for your application configuration](https://12factor.net/config).\n\n`pg-bump` is primarily intended for use as an executable in [`package.json` scripts](https://docs.npmjs.com/misc/scripts). By default, applying or reverting migrations is run in a single transaction. However, this can be disabled via command line options.\n\n## ESM-only\n\nAs of v4, `pg-bump` is an [ECMAScript module](https://nodejs.org/api/esm.html). This should not matter much as it is intended to be used as a CLI application and ESM has been supported since Node.js v12. v3 is still CommonJS.\n\n## Powered by [`@porsager/postgres`](https://github.com/porsager/postgres)\n\nAs of v4, `pg-bump` connects to PostgreSQL with the `postgres` package instead of `pg`.\n\n## Installation\n\nTo add `pg-bump` to your `dependencies` do:\n\n```bash\nλ npm i pg-bump\n```\n\nIt is possible to install `pg-bump` globally, but I never recommend global installs and I don't know why some people still suggest it.\n\n```bash\nλ npm i -g pg-bump\n```\n\n## Commands\n\nYou can view the CLI documentation using `npx pg-bump --help`.\n\n```\nUsage: pg-bump [options] [command]\n\nSQL migration CLI for PostgreSQL.\n\nOptions:\n  -v, --version             output the version number\n  -c, --config-path \u003cpath\u003e  relative path to config file\n  -r, --require \u003chook...\u003e   require modules for side effects\n  -f, --files \u003cpath\u003e        relative path to migrations directory\n  -e, --env-var \u003cvariable\u003e  database url environment variable\n  -j, --journal \u003ctable\u003e     table used to record migration history\n  -h, --help                display help for command\n\nCommands:\n  make|create \u003cmigration\u003e   create a new migration file\n  status                    show pending migrations\n  up [options]              apply pending migrations\n  down [options]            revert synced migrations\n  help [command]            display help for command\n```\n\n## Creating a Migration\n\nThe `pg-bump make` command generates new `.sql` migrations in your migrations directory (defaults to `./migrations`). The migration is split into two files: `up.sql` and `down.sql`.\n\n```shell\nλ npx pg-bump make --help\n# Usage: pg-bump make|create [options] \u003cmigration\u003e\n#\n# create a new migration file\n#\n# Arguments:\n#   migration   name of new migration\n#\n# Options:\n#   -h, --help  display help for command\n```\n\n### Example\n\n\n```shell\nλ npx pg-bump make create_table_users\n# [pg-bump]  created: \u003cunix-time-in-ms\u003e_create-table-users/{up,down}.sql\n\nλ tree migrations\n# migrations/\n# └── \u003cunix-time-in-ms\u003e_create-table-users\n#     ├── down.sql\n#     └── up.sql\n```\n\n## Applying Migrations\n\nThe `pg-bump up` command applies all pending migrations.\n\n```shell\nλ npx pg-bump up --help\n# Usage: pg-bump up [options]\n#\n# apply pending migrations\n#\n# Options:\n#   -l, --lock         acquire advisory lock during migration (default: true)\n#   --no-lock          skip advisory lock during migration\n#   -t, --transaction  wrap migrations in a transaction (default: true)\n#   --no-transaction   do not run migrations in a transaction\n#   -h, --help         display help for command\n```\n\n### Example\n\n```shell\nλ npx pg-bump up\n# [pg-bump] applied 3 migrations\n#        1: 1656785255267_create-table-foos\n#        2: 1656785259822_create-table-bars\n#        3: 1656785263539_create-table-bazzes\n```\n\n## Reverting Migrations\n\nThe `pg-bump down` command reverts migrations. Include `--to \u003cversion\u003e` to only revert migrations to, but not including `\u003cversion\u003e`.\n\n```shell\nλ npx pg-bump down --help\n# Usage: pg-bump down [options]\n#\n# revert synced migrations\n#\n# Options:\n#   --no-lock          skip advisory lock during migration\n#   -l, --lock         acquire advisory lock during migration (default: true)\n#   --no-transaction   do not run migrations in a transaction\n#   -t, --transaction  wrap migrations in a transaction (default: true)\n#   --to \u003cversion\u003e     revert to schema \u003cversion\u003e\n#   -h, --help         display help for command\n```\n\n### Example\n\n```shell\nλ npx pg-bump down\n# [pg-bump] reverted 3 migrations\n#        3: 1656785263539_create-table-bazzes\n#        2: 1656785259822_create-table-bars\n#        1: 1656785255267_create-table-foos\n```\n\n## Inspecting Migration State\n\nList applied and pending migrations with the `pg-bump status` command.\n\n```shell\nλ npx pg-bump status --help\n# Usage: pg-bump status [options]\n#\n# list applied and pending migrations\n#\n# Options:\n#   -h, --help  display help for command\n```\n\n### Example\n\n```shell\nλ npx pg-bump status\n# [pg-bump] found 1 pending migration\n#        1: 1656785255267_create-table-foos\n#        2: 1656785259822_create-table-bars\n# (pending) 1656785263539_create-table-bazzes\n```\n\n## Development\n\nContributions welcome! If you add functionality or options, please include tests.\n\n### Environment Variables and Docker\n\n[`docker-compose`](https://docs.docker.com/compose/) can be used to start and stop a local PostgreSQL instance if you don't have a server running on your machine. If necessary, you can [override `docker-compose.yml`](https://docs.docker.com/compose/extends/#understanding-multiple-compose-files).\n\n#### Copy the `.env` Template\n\n```shell\ncp .env.example .env\n```\n\n#### Start PostgreSQL Container and `pgweb`\n\n```shell\ndocker-compose up --build -d\n```\n\n#### Run Tests\n\n```shell\nnpm test\n```\n\n#### Generate Coverage Report\n\n```shell\nnpm run cover\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthebearingedge%2Fpg-bump","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthebearingedge%2Fpg-bump","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthebearingedge%2Fpg-bump/lists"}