Skip to content

andywer/plow

master
Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
src
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Plow πŸ‘¨β€πŸŒΎ

Postgres migrations & seeding made easy

Plow is a no-non-sense tool to quickly and easily apply database migrations and seed PostgresQL databases.

The migrations are managed using postgres-migrations.

Installation

$ npm install @andywer/plow

Usage - Command line tool

Usage
  $ plow migrate ./migrations/*.sql
  $ plow seed ./seeds/*.sql

General options
  --help                Print this usage help
  --verbose             Enable more detailed logging
  --version             Print the installed plow version

Connection options
  --database <name>     Name of the database
  --host <host>         Database host, defaults to "localhost"
  --port <port>         Port the database listens on, defaults to 5432
  --user <name>         User name to authenticate as
  --password <password> Password to use for authentication

Environment variables
  You can also configure the connection using these environment variables.

  PGDATABASE, PGHOST, PGPASSWORD, PGPORT, PGUSER

Use npx to run a locally installed plow like this:

npx plow migrate ./migrations

Usage - Docker

Use the andywer/plow docker image. You can add it to your docker-compose.yml file like this:

version: "3.7"
services:
  postgres:
    image: postgres:12-alpine
    environment:
      POSTGRES_PASSWORD: $PGPASSWORD
    ports:
      - 5432:5432
  db_seeder:
    image: andywer/plow:0.0.0
    depends_on:
      - postgres
    env_file: ./.env
    environment:
      PGHOST: postgres
    restart: "no"
    volumes:
      - ./migrations:/migrations
      - ./seeds:/seeds

Now every time you run docker-compose up your database will automatically have all migrations and seeds applied! πŸš€

Note that we assume you have a local migrations and a seeds directory that we can mount into the container and that you have a .env file next to your docker-compose file:

PGDATABASE=postgres
PGHOST=localhost
PGUSER=postgres
PGPASSWORD=postgres

The output of docker-compose up will look something like this:

$ docker-compose up
twitter-daily_postgres_1 is up-to-date
Creating twitter-daily_db_seeder_1 ... done
Attaching to twitter-daily_postgres_1, twitter-daily_db_seeder_1
...
postgres_1   | 2020-01-05 04:50:04.266 UTC [1] LOG:  database system is ready to accept connections
db_seeder_1  | Database migration done.
db_seeder_1  | Migrations run:
db_seeder_1  |   - create-migrations-table
db_seeder_1  |   - v0.1.0-initial
db_seeder_1  | Database seeded.
db_seeder_1  | Applied seeds:
db_seeder_1  |   (None)
twitter-daily_db_seeder_1 exited with code 0

Migration files

Migration files can either be plain SQL files or JavaScript files. There are only up migrations, no down migrations – this is a design decision. Read more about it here.

A good scheme to name your migration files is:

<serial>-<version>-<description>.sql

So the very first migration file would be called 01-v0.1.0-initial.sql or similar.

Seed files

Seed files are supposed to be plain SQL files.

/* example.seed.sql */

INSERT INTO users
  (name, email, email_confirmed)
VALUES
  ('Alice', 'alice@example.org', TRUE);

FAQs

Error: Migration failed. Reason: Hashes don't match for migrations

Plow uses postgres-migrations which sets up a migration table and stores a hash for every migration run. You will see this error if you change a migration file (during development, I hope) that you already applied and run plow again.

Only during development: Assuming that you have no valuable data in your local development database, it's easy to just whipe the whole database and restart the containers to re-run the migrations to start off fresh again. If you have a local docker-compose setup with a database container without a mount, then just run docker-compose rm --stop postgres && docker-compose up to re-initialize the whole database.

License

MIT