view release on metacpan or  search on metacpan

lib/App/migrate.pm  view on Meta::CPAN

If handler throws then 'error' handler will be executed.

Default handler will throw (because it doesn't know how to restore your
project).

=item 'VERSION' event

Handler will be executed after each successful migration.

If handler throws then 'error' handler will be executed.

Default handler does nothing.

=item 'error' event

Handler will be executed when one of commands executed while migration
fails or when BACKUP, RESTORE or VERSION handlers throw.

If handler throws then try to restore version-before-migration (without
calling error handler again if it throws too).

Default handler will run $SHELL (to let you manually fix errors) and throw
if you $SHELL exit status != 0 (to let you choose what to do next -
continue migration if you fixed error or interrupt migration to restore
version-before-migration from backup).

=back

=head2 run

    $migrate->run( \@versions );

Will use L</"get_steps"> to get steps for path given in C<@versions> and
execute them in order. Will also call handlers as described in L</"on">.

Before executing each step will set C<$ENV{MIGRATE_PREV_VERSION}> to
current version (which it will migrate from) and
C<$ENV{MIGRATE_NEXT_VERSION}> to version it is trying to migrate to.


=head1 SYNTAX

=head2 Goals

Syntax of this file was designed to accomplish several goals:

=over

=item *

Be able to automatically make sure each 'upgrade' operation has
corresponding 'downgrade' operation (so it won't be forget - but, of
course, it's impossible to automatically check is 'downgrade' operation
will correctly undo effect of 'upgrade' operation).

I<Thus custom file format is needed.>

=item *

Make it easier to manually analyse is 'downgrade' operation looks correct
for corresponding 'upgrade' operation.

I<Thus related 'upgrade' and 'downgrade' operations must go one right
after another.>

=item *

Make it obvious some version can't be downgraded and have to be restored
from backup.

I<Thus RESTORE operation is named in upper case.>

=item *

Given all these requirements try to make it simple and obvious to define
migrate operations, without needs to write downgrade code for typical
cases.

I<Thus it's possible to define macro to turn combination of
upgrade/downgrade operations into one user-defined operation (no worries
here: these macro doesn't support recursion, it isn't possible to redefine
them, and they have lexical scope - from definition to the end of this
file - so they won't really add complexity).>

=back

=head2 Example

    VERSION 0.0.0
    # To upgrade from 0.0.0 to 0.1.0 we need to create new empty file and
    # empty directory.
    upgrade     touch   empty_file
    downgrade   rm      empty_file
    upgrade     mkdir   empty_dir
    downgrade   rmdir   empty_dir
    VERSION 0.1.0
    # To upgrade from 0.1.0 to 0.2.0 we need to drop old database. This
    # change can't be undone, so only way to downgrade from 0.2.0 is to
    # restore 0.1.0 from backup.
    upgrade     rm      useless.db
    RESTORE
    VERSION 0.2.0
    # To upgrade from 0.2.0 to 1.0.0 we need to run several commands,
    # and after downgrading we need to kill some background service.
    before_upgrade
      patch    <0.2.0.patch >/dev/null
      chmod +x some_daemon
    downgrade
      patch -R <0.2.0.patch >/dev/null
    upgrade
      ./some_daemon &
    after_downgrade
      killall -9 some_daemon
    VERSION 1.0.0

    # Let's define some lazy helpers:
    DEFINE2 only_upgrade
    upgrade
    downgrade true