#+STARTUP: hidestars showall
* Migratus
  MIGRATE ALL THE THINGS!

A Leiningen plugin for the [[https://github.com/yogthos/migratus][Migratus]] library.

[[http://clojars.org/migratus-lein][http://clojars.org/migratus-lein/latest-version.svg]]

  A general migration framework, with an implementation for database migrations.

  Designed to be compatible with a git based work flow where multiple topic
  branches may exist simultaneously, and be merged into a master branch in
  unpredictable order.

  This is accomplished two ways:
  1. Migration ids are not assumed to be incremented integers.  It is
     recommended that they be timestamps (e.g. '20111202091200').
  2. Migrations are considered for completion independently.

  In contrast, using a single global version for a store and incremented
  integers for migration versions, it is possible for a higher numbered
  migration to get merged to master and deployed before a lower numbered
  migration, in which case the lower numbered migration would never get run,
  unless it is renumbered.

  Migratus does not use a single global version for a store.  It considers each
  migration independently, and runs all uncompleted migrations in sorted order.
** Quick Start
   - Add Migratus as a dependency and the plugin:
     : :dependencies [[migratus <VERSION>]]
     : :plugins [[migratus-lein <VERSION>]]

   - Add the following key and value to your project.clj:
     : :migratus {:store :database
     :            :migration-dir "migrations"
     :            :db {:classname "com.mysql.jdbc.Driver"
     :                 :subprotocol "mysql"
     :                 :subname "//localhost/migratus"
     :                 :user "root"
     :                 :password ""}}

   - Add the following code to
     "src/migrations/20111206154000-create-foo-table.up.sql"
     : CREATE TABLE IF NOT EXISTS foo(id BIGINT);

   - Run `lein migratus migrate`
** Configuration
   Migratus is configured via a configuration map that you pass in as its first
   parameter.  The :store key describes the type of store against which
   migrations should be run.  All other keys/values in the configuration map are
   store specific.
*** Databases
    To run migrations against a database use a :store of :database, and specify
    the database connection configuration in the :db key of the configuration
    map.  This connection information is passed directly to clojure.java.jdbc.
    For example:

    : {:store :database
    :  :migration-dir "migrations"
    :  :db {:classname "com.mysql.jdbc.Driver"
    :       :subprotocol "mysql"
    :       :subname "//localhost/migratus"
    :       :user "root"
    :       :password ""}}

    or:

    : {:store :database
    :  :migration-dir "migrations"
    :  :db ~(get (System/getenv) "DATABASE_URL")}

    When using the second option, it's also possible to put the config in =profiles.clj=, e.g:

    : {:provided {:env {:database-url "jdbc:h2:./my_app_dev.db"}}}

    The second method is preferred as it doesn't hardcode database connection values in files that
    are checked into the repository.

    The :migration-dir key specifies the directory on the classpath in which to
    find SQL migration files.  Each file should be named with the following
    pattern "[id]-[name]-[direction].sql" where id is a unique integer id for
    the migration, name is some human readable description of the migration, and
    direction is either 'up' or 'down'.

    If Migratus is trying to run either the up or down migration and it does not
    exist, then an Exception will be thrown.

    If you would like to run multiple statements in your migration, then
    separate them with '--;;'.  For example:

    : CREATE TABLE IF NOT EXISTS quux(id bigint, name varchar(255));
    : --;;
    : CREATE INDEX quux_name on quux(name);

    This is necessary because JDBC does not have a method that allows you to
    send multiple SQL commands for execution.  Migratus will split your
    commands, and send the each to the database inside of a transaction.

    See test/migrations in this repository for an example of how database
    migrations work.

** Usage
   Migratus can be used programmatically by calling one of the following
   functions:

   | Function                   | Description                                                                               |
   |----------------------------+-------------------------------------------------------------------------------------------|
   | migratus.core/create       | Run 'init' to initialize the database, e.g: create a schema.                              |
   | migratus.core/create       | Run 'create' to generate migration files.                                                 |
   | migratus.core/migrate      | Run 'migrate' for any migrations that have not been run.                                  |
   | migratus.core/rollback     | Run 'rollback' to revert last successful migration.                                       |
   | migratus.core/up           | Run 'up' for the specified migration ids. Will skip any migration that is already up.     |
   | migratus.core/down         | Run 'down' for the specified migration ids. Will skip any migration that is already down. |
   | migratus.core/reset        | Run 'down' for all migrations that have been run, and 'up' for all migrations.            |
   | migratus.core/pending-list | Run 'pending-list' to list pending migrations                                             |

   The 'create' command will generate the migration files with the supplied name. The files will be placed in the migrations
   directory. Each file will be prefixed with the current timestamp and the up migration file will be postfixed with '.up.sql`,
   while the down migration file will be postfixed with '.down.sql', e.g:

   : lein migratus create add-users-table

   will generate the following files:

   : 20160303102023-add-users-table.down.sql
   : 20160303102023-add-users-table.up.sql

   See the docstrings of each function for more details.

   Migratus can also be used from leiningen if you add it (and a database driver) as a dev dependency.

   : :dev-dependencies [[migratus <VERSION>]
   :                    [postgresql/postgresql <VERSION>]]

   And add a configuration :migratus key to your project.clj.

   : :migratus {:store :database
   :            :migration-dir "migrations"
   :            :db "postgres://localhost/mydb"}

** License
   : Copyright © 2012 Paul Stadig, Dmitri Sotnikov
   :
   : Licensed under the Apache License, Version 2.0.