pg-bump3.0.0-beta.4 • Public • Published
An opinionated, minimalist SQL migration CLI for PostgreSQL.
What is it?
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 and b) you are using environment variables for your application configuration.
pg-bump is primarily intended for use as an executable in
package.json scripts. Applying or reverting migrations is always run in a single transaction, ensuring atomic schema transitions.
pg-bump to your
λ npm i -D pg-bump
It is possible to install
pg-bump globally, but it's not recommended.
λ npm i -g pg-bump
Creating a Migration
pg-bump create command generates a new
.sql migration file in your migrations directory (defaults to
λ pg-bump create create_table_users
-- up----- down
The file is split into two sections,
down, separated by a
--- three-dash SQL comment. The separator comment is used by
pg-bump to determine which section of code to execute while applying (
up) or reverting (
down) migrations. It is safe to delete the
down comments, but the
--- separator should be preserved.
-- up(id serial,username text unique not null,created_at timestamptz(6) not null default now(),primary (id));----- downusers;
pg-bump <command> [args]Commands:create <filename> Create a new migration file.up Apply pending migrations.down [--to|-t <filename>] Revert applied migrations.status Show pending migrationsOptions:--config Relative path to optional configuration file.[default: ".pgbumprc"]--connectionVar, -c Connection string environment variable.[default: "DATABASE_URL"]--journalTable, -j Database table used to record migration history.[default: "schema_journal"]--files, -f Relative path to migrations directory.[default: "migrations"]--help Show help [boolean]
pg-bump will attempt to find an optional
.pgbumprc configuration file in the root of the current working directory. Here is an example with default settings:
The environment variable that
pg-bump will use to connect to your PostgreSQL server. Defaults to
DATABASE_URL. Should you forgo configuring a
connectionVar and/or exporting an environment variable,
pg-bump will attempt to connect using the
pg module's default behavior. You should be using
dotenv, so if you include a
POSTGRESL_URL, in your
.env file, then
pg-bump will use it to connect to PostgreSQL.
The database table that
pg-bump will use to record the names of applied migrations. Defaults to
schema_journal. This table will be created for you by
(applied_at timestamptz(6) not null default now(),file_name text unique not null);
The directory in your project that
pg-bump will use to generate and read
.sql migration files. Defaults to
./migrations. This directory will be created for you by
project/├─ node_modules/├─ migrations/ <--├─ package.json├─ .env└─ .pgbumprc
After cloning the project repository, you'll need a
.env file in the root of the project. See
# spin up a PostgreSQL servernpm run db:start# run the testsnpm test# tear the server downnpm run db:stop