The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Migraine-0.54
River stage one • 1 direct dependent • 1 total dependent
++
/ migraine

NAME

migraine - DB schema MIGRAtor that takes headache out of the game

SYNOPSIS

 $ migraine db-conn-live.yml
 $ migraine -n db-conn-test.yml         # No act (a la Makefile)
 $ migraine -m alternative-migrations-dir db-conn-devel.yml
 $ migraine -V -v 5 db-conn-live.yml    # Verbose, migrate up to 5
 $ migraine -o 8 db-conn-devel.yml      # Apply ONLY migration 8
 $ migraine -f db-conn-test.yml         # Don't stop on missing migrations

DESCRIPTION

DB schema migrator inspired by Rails migrations. Allows developers to store changes to a DB schema in "migration" files, then run the migrator to get all the pending migrations for some DB executed. That allows for easy and automated upgrading of any database used for a given project. Executing migrations just up to a point (as opposed to "up to the latest version"), or applying single migrations (say, applying 4, even if 3 is still unapplied) is also supported.

There are two things migraine has to know to be able to update your database: first, which database should it connect to (given by the YAML configuration file in the migraine call); second, the list of available migrations (the files in a directory, by default migrations in the same directory as the YAML).

OPTIONS

-c db-conn.yml

Reads the configuration from db-conn.yml. This option is deprecated, and it's maintained just temporarily for compatibility with older versions of migraine. You should pass your configuration file as an argument, without the -c switch.

-f

"Force": don't stop executing migrations if there's one that doesn't exist or has a duplicated id.

-m /some/migrations/dir

Looks for migrations in the given /some/migrations/dir directory. The default is a directory called migrations at the same level as the given YAML file.

-n

Doesn't execute anything on the database ("no act", like Makefile)

-o mid

It applies only the given migration with id mid, regardless of which other migrations may be pending. It returns an error if the migration was already applied.

-u

Upgrades the migraine metadata in the target database, if needed. It will return an error if the migraine metadata is newer than migraine supports.

-v mid

Instead of trying to apply all available migrations, it only applies pending migrations up to the given migration id ("migration version") mid.

-V

Verbose mode. Give more information about what's going on, including showing the complete text of the migrations being applied.

DATABASE CONNECTION INFORMATION

It's stored in a YAML file (mandatory argument in migraine calls) which looks like this:

 dsn: dbi:mysql:dbname=mydb;host=mydbserver;port=3307
 user: dbuser
 # password: s3kr3t

MIGRATIONS

The migration filenames must have the form number-some_name.extension. Numbers should start at 1, and none of them should be skipped or repeated. You can use leading zeros to get nice ASCII-betical order in directory listings.

In the only format currently supported, SQL, the extension must be sql, so the files will be named something like 8-add_some_table.sql or 008-update_obsolete_field.sql. The contents will be executed as-is, without any processing, so they should be valid SQL for the DB server you're using.

LICENSE AND COPYRIGHT

This code is offered under the Open Source BSD license.

Copyright (c) 2009, Opera Software. All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  • Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

  • Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

  • Neither the name of Opera Software nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

DISCLAIMER OF WARRANTY

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.