@hackage dbmigrations0.1

dbmigrations

This package contains a library and program for the creation, management, and installation of schema updates (called "migrations") for a relational database. In particular, this package lets the migration author express explicit dependencies between migrations and the management tool automatically installs or reverts migrations accordingly, using transactions for safety.

This package operates on two logical entities:

• The "backend", which is the relational database whose schema you want to manage.

• The "migration store" (or simply "store"), which is the collection of schema changes you want to apply to the database. These migrations are expressed using plain text files collected together in a single directory, although the library is general enough to permit easy implementation of other storage backends for migrations.

Migration file format

While the "moo" management tool included in this package will create new migration files for you, a description of the file format follows. A migration used by this package is a structured document containing these fields:

Description: (optional) a textual description of the migration

Dependencies: (required, but may be empty) a whitespace-separated list of migration names on which the migration depends; these names are the migration filenames without the filename extension

   Created: The UTC date and time at which this migration was
            created

     Apply: The SQL necessary to apply this migration to the
            database

    Revert: (optional) The SQL necessary to revert this migration
            from the database

The format of this file is somewhat flexible; any of the above fields may take up a single line, with all text coming after the field name and colon constituting the field's value; in the case of multi-line values (such as Apply and Revert SQL), multiple lines may follow the field name and colon, as long as they are indented by at least one whitespace character. The migration file format also supports comments, which are preceded by "#".

moo: the management tool

This package includes one program, "moo". For information about moo's usage and features, please see the file MOO.TXT.

Installation

If you've obtained this package in source form and would like to install it, you'll need the "cabal" program. To install this package, run:

cabal install

Getting the source

If you've obtained this package by some other means and would like to get a copy of the source code, you can do so with darcs:

darcs get http://repos.codevine.org/dbmigrations

For more information about the "darcs" revision control system, please see:

http://darcs.net/

Submitting patches

I'll gladly consider accepting patches to this package; please do not hesitate to send them to me with "darcs send", or mail them to me manually (see below). If you'd like to send me a patch, I'll be more likely to accept it if you can follow these guidelines where appropriate:

• Keep patches small; a single patch should make a single logical change with minimal scope.

• If possible, include tests with your patch.

• If possible, include haddock with your patch.

Submitting bug reports and feedback

If you've found a bug or would like to provide any feedback on the design, implementation, or behavior of this library or its programs, please do not hesitate to contact me directly at

drcygnus AT gmail DOT com

Enjoy!