migrō

(Latin) migrate

A relational database migration tool, written in Crystal. It uses the cql framework.

Installation

Requirements:

• Crystal (currently built & tested using 0.24.1)

Clone this repository

git clone https://github.com/aisrael/migro.git
cd migro

Run the tests

To run the tests, we use Docker + Compose to bring up a PostgreSQL environment. First go:

docker-compose up

Then, in another terminal

DATABASE_URL=postgres://migro:secret@localhost/migro_test crystal spec

Build the executable and place it in your $PATH

shards build --release

That will build bin/migro. Copy that file anywhere in your $PATH

Usage

migro expects database migrations to be in db/migrations (relative to the current directory).

Migration files can be named using one of the following patterns:

• text_only.yml - text only, will be executed before everything else (in alphabetical order)
• 001_some_text.yml, 201802240803-some-text.yml - numeric prefix plus text, will be executed in order of the numeric prefix first, then alphabetical order if same numeric prefix

Migration files

migro currently only supports YAML migrations of the form

metadata:
  version: 0.1
changes:
  - create_table:
    name: users
    columns:
    - name: id
      type: SERIAL
      null: false
      primary: true
    - name: username
      type: VARCHAR
      size: 40
      null: false
    - name: password_hash
      type: CHAR
      size: 128
      null: false
up:
  - insert:
      table: users
      rows:
        - username: system
        - password_hash: b37e50cedcd3e3f1ff64f4afc0422084ae694253cf399326868e07a35f4a45fb

Which is equivalent to running the following SQL commands:

CREATE TABLE users (id SERIAL NOT NULL PRIMARY KEY, username VARCHAR(40) NOT NULL, password_hash CHAR(128) NOT NULL);
INSERT INTO users (username, password_hash) VALUES ('system', 'b37e50cedcd3e3f1ff64f4afc0422084ae694253cf399326868e07a35f4a45fb');

Development

TODO:

• Support for .sql migrations ala micrate
• Improved CLI, e.g. migro up, migro down, migro rollback --to 042-some.yml

Contributing

1. Fork it ( https://github.com/aisrael/migro/fork )
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request

Contributors

• aisrael Alistair A. Israel - creator, maintainer