NAME
    ORLite::Migrate - Extremely light weight SQLite-specific schema
    migration

SYNOPSIS
      # Build your ORM class using a patch timeline
      # stored in the shared files directory.
      use ORLite::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
    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.

    ORLite::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 be either a monolithic timeline class, or a
    directory containing standalone migration scripts.

    A "timeline" is a set of revisioned schema changed, to be applied in
    order and representing the evolution of the database schema over time.
    The end of the timeline, representing by the highest revision number,
    represents the "current" anticipated schema for the application.

    Because the patch sequence can be calculated from any arbitrary starting
    version, by keeping the historical set of changes in your application as
    schema patches it is possible for the user of any older application
    version to install the most current version of an application and have
    their database upgraded smoothly and safely.

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

    The timeline for your application can be specified in two different
    forms, with different advantages and disadvantages.

  Timeline Directories
    A Timeline Directory is a directory on the filesystem containing a set
    of Perl scripts named in a consistent pattern.

    These patch scripts are named in the form migrate-$version.pl, where
    $version is the schema version to migrate to. A typical timeline
    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

    ORLite::Migrate formulates a migration plan that starts at the current
    database "user_version" pragma value, executing the migration script
    that has the version "user_version + 1", then executing "user_version +
    2" and so on.

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

    The main advantage of a timeline directory is that each patch is run in
    its own process and interpreter. Hundreds of patches can be produced by
    many different authors, with certainty that the changes described in
    each will be executed as intended.

    The main disadvantage of using a timeline directory is that your
    application must be able to identify the Perl interpreter it is run in
    so that it can execute a sub-process. This may be difficult or
    impossible for cases such as PAR-packaged applications and Perl
    interpreters embedded inside .exe wrappers or larger non-Perl
    applications.

    In general, it is recommended that you use the timeline directory
    approach unless you encounter a situation in which sub-process execution
    (or locating the patch files) is difficult.

  Timeline Classes
    A timeline class places all of the schema patches into a single Perl
    module, with each patch represented as a method name.

    The following is an example of a trivial timeline class.

      package t::lib::MyTimeline;
      
  use strict;
      use base 'ORLite::Migrate::Timeline';
      
  my $UPGRADE1 = <<'END_SQL';
      
  create table foo (
          id integer not null primary key,
          name varchar(32) not null
      );
      
  insert into foo values ( 1, 'foo' )
      
  END_SQL
      
  sub upgrade1 {
          my $self = shift;
          foreach ( split /;\s+/, $UPGRADE1 ) {
              $self->do($_);
          }
          return 1;
      }
      
  sub upgrade2 {
          $_[0]->do("insert into foo values ( 2, 'bar' )");
      }
      
  sub upgrade3 {
          $_[0]->do("insert into foo values ( 3, 'baz' )");
      }
      
  1;

    As with the patch files, the current state of the "user_version" pragma
    will be examined, and each "upgradeN" method will be called to advance
    the schema forwards.

    The main advantage of a timeline class is that you will not need to
    execute sub-processes, and so a timeline class will continue to function
    even in unusual or exotic process contents such as PAR packaging or .exe
    wrappers.

    The main disadvantage of a timeline class is that the entire timeline
    code must be loaded into memory no matter how many patch steps are
    needed (and stay in memory after the migration has completed), and all
    patches share a common interpreter and thus can potentially pollute or
    corrupt each other.

SUPPORT
    Bugs should be reported via the CPAN bug tracker at

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

    For other issues, contact the author.

AUTHOR
    Adam Kennedy <adamk@cpan.org>

COPYRIGHT
    Copyright 2009 - 2012 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.