Readme for dbmigrations-0.1.2
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!