NAME

DBIx::Migration::Directories::Base - Schema-independant migration operations

SYNOPSIS

my $object = DBIx::Migration::Directories::Base->new(
  $dbh => $some_database_handle
);

my $schemas = $object->schemas;

if(my $schema = $schemas->{'Foo-Schema'}) {
   print "Foo-Schema is installed at version #$schema->{version}.\n";
}

DESCRIPTION

DBIx::Migration::Directories::Base is the base class to DBIx::Migration::Directories.

The methods in this class do not care if you are currently operating on a schema, or if you have a valid schema directory to work with.

The main reason to create DBIx::Migration::Directories::Base object on it's own is to obtain general information about migrations, such as currently installed schemas and their version history.

METHODS

Constructor

new(%args)

Creates a new DBIx::Migration::Directories::Base object. %args is a hash of properties to set on the object; the following properties are used by DBIx::Migration::Directories::Base:

dbh

Required. The DBIx::Transaction database handle to use for queries. This handle should already be connected to the database that you wish to manage.

driver

The name of the DBD driver we are using. You normally don't want to specify this option; DBIx::Migration::Directories::Base will automatically pull the driver name out of the database handle you pass along.

schema

The schema we wish to operate on. This option is only ever used by the schema_version_log method, and only if you do not send that method a schema argument.

High-Level Methods

schemas

Queries the migration schema, and returns a hash reference containing all of the schemas currently registered in this database. The keys in this hash are the schemas' names, and the values are hash references, containing the contents of that schema's row in the database as key/value pairs:

name

The schema's name, again.

version

The current version of this schema.

schema_version_log($schema)

Queries the migration schema, and returns an array reference containing the specified schema's version history. If a schema is not specified, defaults to the "schema" property if it has been set, otherwise an exception is raised.

Each entry in the array reference returned is a hash reference, containing the contents of that schema's log rows in the database as key/value pairs:

id

A unique integer identifier for this log entry.

schema_name

Schema this log entry refers to.

event_time

Time this migration action took place.

old_version

Schema version before this migration action took place.

new_version

Schema version after this migration took place.

Low-Level Methods

table_exists($table)

Queries the database and returns 1 if the named table exists, 0 otherwise.

direction($from, $to)

Given two version numbers, determine whether this is an upgrade or a downgrade. All this does is:

$to <=> $from

versions($string)

Given the name of a directory, determine what versions it is migrating from and to. Returns an array of two numbers: the "from" version and the "two" version.

If this directory has two version numbers in it, you'll get those two (normalized) version numbers back. If this directory only has one version number in it, you'll get 0 as the "from" version, and the (normalized) version number in the directory name as the "to" version.

run_sql(@sql)

Begin a transaction, and run all of the SQL statements specified in @sql. If any of them fail, roll the transaction back and return 0. If they all succeed, commit the transaction and return 1.

read_file($path)

Reads a file on the filesystem and returns it's contents as a scalar. Raises an exception if the file could not be read. Exciting, huh?

version_as_number($version)

Normalize a version number. Currently, this is just equivalent to:

return $version + 0

But in future releases it may do fancier stuff, like dealing with "double-dot" version numbers or the like.

sql_insert_migration_schema_version($schema, $version)

Returns an SQL query used to add a new schema to the database. This is called by "version_update_sql".

sql_update_migration_schema_version($schema, $version)

Returns an SQL query used to change the version number we have on record for a schema. This is called by "version_update_sql".

sql_insert_migration_schema_log($schema, $from, $to)

Returns an SQL query used to add a new schema log record to the database indicating a migration between schema versions. This is called by "version_update_sql".

sql_table_exists($table)

Returns a string containing an SQL query that is garunteed to only return rows if the named table exists. Base.pm's implementation queries the SQL standard INFORMATION_SCHEMA table.

AUTHOR

Tyler "Crackerjack" MacDonald <japh@crackerjack.net>

LICENSE

Copyright 2006 Tyler "Crackerjack" MacDonald <japh@crackerjack.net>

This is free software; You may distribute it under the same terms as perl itself.

SEE ALSO

DBIx::Migration::Directories