pg-migrate
pg-migrate is a simple yet powerful migration framework for PostrgeSQL.
Configuration
There are 3 ways to configure pg-migrate:
- .gpgm.ts
- environment variables
- command line
The order of configuration priority is command line > environment variables > .gpgm.ts
, so command line flags always take priority.
.gpgm.ts
This file is compiled and executed at runtime. An example file:
export const db = {
host: "localhost",
port: 5432,
user: "postgres",
database: "postgres",
migrationSchema: "public",
migrationTable: "__migrations",
};
export const app = {
migrationsFolder: "migrations/",
};
Environment Variables
DB_HOST
DB_DATABASE
DB_PORT
DB_USER
DB_PASSWORD
DB_MIGRATION_SCHEMA
DB_MIGRATION_TABLE
DB_MIGRATIONS_FOLDER
DB_MIGRATION_TEMPLATE
Command Line
usage: pg-migrate [-h] [-v] [-db DATABASE] [--host HOST] [-p PORT] [-u USER]
[-pw PASSWORD] [-s SCHEMA] [-t TABLE]
[-cs CONNECTION_STRING] [-m MIGRATIONS] [-tpl TEMPLATE]
{migrate,create} ...
Standalone migration runner for @gerblins/pg-migration
Optional arguments:
-h, --help Show this help message and exit.
-v, --version Show program's version number and exit.
-db DATABASE, --database DATABASE
Name of the database to use
--host HOST Host to connect to
-p PORT, --port PORT Port to connect to
-u USER, --user USER Username to use when connecting
-pw PASSWORD, --password PASSWORD
Password to use when connecting
-s SCHEMA, --schema SCHEMA
Schema for migrations table
-t TABLE, --table TABLE
Table to keep track of migrations
-cs CONNECTION_STRING, --connection-string CONNECTION_STRING
Postgres connection string
-m MIGRATIONS, --migrations MIGRATIONS
Folder that contains the migrations
-tpl TEMPLATE, --template TEMPLATE
Template to use for creating migrations
command:
{migrate,create}
Flags for migrate
command:
usage: pg-migrate migrate [-h] [--damp]
Optional arguments:
-h, --help Show this help message and exit.
--damp Runs the queries but rolls them back
Migration Files
Migration files are pretty simple and can be created by running pg-migrate create
. An example migration:
import { Migration, MigrationClient } from "../../../lib";
export default new Migration(1, [
"CREATE TABLE test (id uuid not null primary key, value text)",
async (client: MigrationClient) => {
await client.query("SELECT 1 FROM test");
return true;
},
]);
Damp Runs
A damp run is the next step above a dry run. It actually runs the migration but rolls back the transaction. This allows you to be confident that the migrations will work in the case of a 2 part deploy (deploy code, migrate).