/ 
DBIx-Migration-0.16
River stage one • 1 direct dependent • 1 total dependent
/ DBIx::Migration

NAME

DBIx::Migration - Seamless database schema up- and downgrades

SYNOPSIS

use DBIx::Migration ();

my $m = DBIx::Migration->new(
  dsn => 'dbi:SQLite:~/Projects/myapp/db/myapp.db'
);

# Get current migration version from database
my $version = $m->version;

# Set directory before applying migrations
$m->dir( '~/Projects/myapp/db/migrations' );

# Migrate database to version 1
$m->migrate( 1 );

# Migrate database to the latest version
$m->migrate;

-- ~/Projects/myapp/db/migrations/schema_1_up.sql
CREATE TABLE foo (
  id INTEGER PRIMARY KEY,
  bar TEXT
);

-- ~/Projects/myapp/db/migrations/schema_1_down.sql
DROP TABLE foo;

-- ~/Projects/myapp/db/migrations/schema_2_up.sql
CREATE TABLE bar (
  id INTEGER PRIMARY KEY,
  baz TEXT
);

-- ~/Projects/myapp/db/migrations/schema_2_down.sql
DROP TABLE bar;

DESCRIPTION

This class provides seamless database schema up- and downgrades.

Migrations

The implementation of this class is based on migrations. A migration is a .sql script. Although not mandatory the script name begins with a prefix like for example schema_. It follows a version number that is a positive integer. After an _ (underscore) character the script name ends with the migration type that is either up or down. Migrations are stored in a directory and are applied in order to a database. Usually the version number of the first migration is 1. The version numbers of the other migrations have to be ascending without gaps.

Processing

During processing the content of each migration is read with the binmode of :raw into a scalar. The content is split into sections using the default SQL delimiter ; (semicolon). Each section is executed independently. All related sections are encapsulated in a database transaction. If a migration embeds stored logic containing one or more semicolons (a PostgreSQL trigger function for example), the migrate() method incorrectly splits the migration into sections, causing an error. You can set a different delimiter to overcome this problem. Add the dbix_migration_delimiter annotation as an SQL comment to the migration

-- dbix_migration_delimiter: /
...

The annotation has to be specified in the first line. The delimiter has to be a single printable ASCII character, excluding the space character. In the previous example it is the / (slash) character.

Managed schema vs tracking schema

The schema support of this implementation should be considered experimental. For a PostgreSQL database you may set the managed schema (the schema of your single-schema application) using the search_path connect option:

my $m = DBIx::Migration->new(
  dsn => 'dbi:Pg:dbname=test;host=localhost;port=5432;user=postgres;options=--search_path=myschema'
);

The migration object stores the current migration version in a tracking table. Its default unqualified name is dbix_migration. The table belongs by default to the public tracking schema.

METHODS

$self->BUILD( $args )

Validate object.

$self->dir( $dir )

Get/set-once directory that contains migrations.

$self->dsn

Get data source name.

$self->dbh

Get database handle.

$self->migrate( $version )

Migrate database to version. Returns true in case of success; otherwise false. If called without the version argument the latest migration version will be used.

$self->password

Get database password.

$self->tracking_schema

Get schema that the tracking table belongs to.

$self->tracking_table

Get tracking table. If the tracking schema is defined the tracking table name is fully qualified.

$self->username

Get database username.

$self->version

Get migration version from database. Will be undef if no migration has taken place yet. The version is stored in the tracking table.

LOGGING

The logging of this class is based on a static Log::Any logger. Its category is the class name itself. The easiest way to enable logging is to set the LOG_ANY_DEFAULT_ADAPTER environment variable:

LOG_ANY_DEFAULT_ADAPTER=Stderr

SEE ALSO

AUTHOR

Sebastian Riedel, <kraihx@gmail.com>

CONTRIBUTORS

Dan Sully, <dan+github@sully.org>

Marcus Ramberg, <marcus@nordaaker.com>

Steven Jenkin, <sjenkin@venda.com>

Sven Willenbuecher, <sven.willenbuecher@gmx.de>

COPYRIGHT

Copyright 2004-2005 Sebastian Riedel. All rights reserved.

This program is free software, you can redistribute it and/or modify it under the same terms as Perl itself.