dbmate/README.md

Dbmate

Dbmate is a database migration tool, to keep your database schema in sync across multiple developers and your production servers. It is a standalone command line tool, which can be used with any language or framework. This is especially helpful if you are writing many services in different languages, and want to maintain some sanity with consistent development tools.

Features

• Currently supports PostgreSQL only.
• Powerful, purpose-built DSL for writing schema migrations.
• Migrations are timestamp-versioned, to avoid version number conflicts with multiple developers.
• Supports creating and dropping databases (handy in development/test).
• Database connection URL is definied using an environment variable (DATABASE_URL by default), or specified on the command line.
• Built-in support for reading environment variables from your .env file.
• Easy to distribute, single self-contained binary.

Installation

Dbmate is currently under development. To install the latest build, run:

$ go get -u github.com/adrianmacneil/dbmate

Commands

dbmate          # print help
dbmate new      # generate a new migration file
dbmate up       # create the database (if it does not already exist) and run any pending migrations
dbmate create   # create the database
dbmate drop     # drop the database
dbmate migrate  # run any pending migrations
dbmate rollback # roll back the most recent migration

Usage

Dbmate locates your database using the DATABASE_URL environment variable by default. If you are writing a twelve-factor app, you should be storing all connection strings in environment variables.

To make this easy in development, dbmate looks for a .env file in the current directory, and treats any variables listed there as if they were specified in the current environment (existing environment variables take preference, however).

If you do not already have a .env file, create one and add your database connection URL:

$ cat .env
DATABASE_URL="postgres://postgres@127.0.0.1:5432/myapp_development?sslmode=disable"

It is generally recommended to commit this file to source control, to make it easier for other developers to get up and running with your project. However, this is completely up to your personal preference.

Note: When connecting to Postgres, you may need to add the sslmode=disable flag to your connection URL, as dbmate by default requires an SSL/TLS connection (some other frameworks/languages use unencrypted connections by default).

Creating Migrations

To create a new migration, run dbmate new create_users_table. You can name the migration anything you like. This will create a file db/migrations/20151127184807_create_users_table.sql in the current directory:

-- migrate:up

-- migrate:down

To write a migration, simply add your SQL to the migrate:up section:

-- migrate:up
CREATE TABLE users (
  id INT PRIMARY KEY,
  name VARCHAR,
  email VARCHAR NOT NULL
);

-- migrate:down

Running Migrations

Run dbmate up to run any pending migrations.

$ dbmate up
Creating: myapp_development
Applying: 20151127184807_create_users_table.sql

Note: dbmate up will create the database if it does not already exist (assuming the current user has permission to create databases). If you want to run migrations without creating the database, run dbmate migrate.

Rolling Back Migrations

By default, dbmate doesn't know how to roll back a migration. In development, it's often useful to be able to revert your database to a previous state. To accomplish this, implement the migrate:down section:

-- migrate:up
CREATE TABLE users (
  id INT PRIMARY KEY,
  name VARCHAR,
  email VARCHAR NOT NULL
);

-- migrate:down
DROP TABLE users;

Run dbmate rollback to roll back the most recent migration:

$ dbmate rollback
Rolling back: 20151127184807_create_users_table.sql

Options

The following command line options are available with all commands. You must use command line arguments in the order dbmate [global options] command [command options].

• --migrations-dir, -d "./db/migrations" - where to keep the migration files.
• --env, -e "DATABASE_URL" - specify an environment variable to read the database connection URL from.

For example, before running your test suite, you may wish to drop and recreate the test database. One easy way to do this is to store your test database connection URL in the TEST_DATABASE_URL environment variable:

$ cat .env
TEST_DATABASE_URL="postgres://postgres@127.0.0.1:5432/myapp_test?sslmode=disable"

You can then specify this environment variable in your test script (Makefile or similar):

$ dbmate -e TEST_DATABASE_URL drop
Dropping: myapp_test
$ dbmate -e TEST_DATABASE_URL up
Creating: myapp_test
Applying: 20151127184807_create_users_table.sql

Contributing

Dbmate is written in Go, pull requests are welcome.

Tests are run against a real database using docker-compose. First, install the Docker Toolbox.

Make sure you have docker running:

$ docker-machine start default && eval "$(docker-machine env default)"

To build a docker image and run the tests:

$ make

To run just the lint and tests (without completely rebuilding the docker image):

$ make lint test