Padre::DB::Migrate.3pm

Langue: en

Version: 2010-06-11 (fedora - 01/12/10)

Section: 3 (Bibliothèques de fonctions)

Sommaire

NAME

Padre::DB::Migrate - Extremely light weight SQLite-specific schema migration

SYNOPSIS

   # Build your ORM class using a patch timeline
   # stored in the shared files directory.
   use Padre::DB::Migrate {
       create       => 1,
       file         => 'sqlite.db',
       timeline     => File::Spec->catdir(
           File::ShareDir::module_dir('My::Module'), 'patches',
       ),
       user_version => 8,
   };
 
   # migrate-1.pl - A trivial schema patch
   #!/usr/bin/perl
 
   use strict;
   use DBI ();
 
   # Locate the SQLite database
   my $file = <STDIN>;
   chomp($file);
   unless ( -f $file and -w $file ) {
       die "SQLite file $file does not exist";
   }
 
   # Connect to the SQLite database
   my $dbh = DBI->connect("dbi:SQLite(RaiseError=>1):$file");
   unless ( $dbh ) {
     die "Failed to connect to $file";
   }
 
   $dbh->do( <<'END_SQL' );
   create table foo (
       id integer not null primary key,
       name varchar(32) not null
   )
   END_SQL

DESCRIPTION

THIS CODE IS EXPERIMENTAL AND SUBJECT TO CHANGE WITHOUT NOTICE

YOU HAVE BEEN WARNED!

SQLite is a light weight single file SQL database that provides an excellent platform for embedded storage of structured data.

ORLite is a light weight single class Object-Relational Mapper (ORM) system specifically designed for (and limited to only) work with SQLite.

Padre::DB::Migrate is a light weight single class Database Schema Migration enhancement for ORLite.

It provides a simple implementation of schema versioning within the SQLite database using the built-in "user_version" pragma (which is set to zero by default).

When setting up the ORM class, an additional "timeline" parameter is provided, which should point to a directory containing standalone migration scripts.

These patch scripts are named in the form migrate-$version.pl, where $version is the schema version to migrate to. A typical time line directory will look something like the following.

   migrate-01.pl
   migrate-02.pl
   migrate-03.pl
   migrate-04.pl
   migrate-05.pl
   migrate-06.pl
   migrate-07.pl
   migrate-08.pl
   migrate-09.pl
   migrate-10.pl

Padre::DB::Migrate formulates a migration plan, it will start with the current database "user_version", and then step forwards looking for a migration script that has the version "user_version + 1".

It will continue stepping forwards until it runs out of patches to execute.

If Padre::DB::Migrate is also invoked with a "user_version" parameter (to ensure the schema matches the code correctly) the plan will be checked in advance to ensure that the migration will end at the value specified by the "user_version" parameter.

Because the migration plan can be calculated from any arbitrary starting version, it is possible for any user of an older application version to install the most current version of an application and be upgraded safely.

The recommended location to store the migration time line is a shared files directory, locatable using one of the functions from File::ShareDir.

SUPPORT

Bugs should be reported via the "CPAN" bug tracker at

http://rt.cpan.org/NoAuth/ReportBug.html?Queue=ORLite-Migrate <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=ORLite-Migrate>

For other issues, contact the author.

AUTHOR

Adam Kennedy <adamk@cpan.org> Copyright 2009 - 2010 Adam Kennedy.

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

The full text of the license can be found in the LICENSE file included with this module.