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.