view release on metacpan or  search on metacpan

README  view on Meta::CPAN

      NOTE: If you'll use handler which doesn't really create and keep
      backups for all versions then it will be impossible to do RESTORE
      operation.

    'RESTORE' event

      Handler will be executed when project should be restored from backup:
      when downgrading between versions which contain RESTORE operation or
      when migration fails.

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

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

    'VERSION' event

      Handler will be executed after each successful migration.

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

      Default handler does nothing.

    '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).

 run

        $migrate->run( \@versions );

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

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

SYNTAX

 Goals

    Syntax of this file was designed to accomplish several goals:

      * 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).

      Thus custom file format is needed.

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

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

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

      Thus RESTORE operation is named in upper case.

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

      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).

 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
    
        DEFINE2 mkdir
        upgrade
          mkdir "$@"
        downgrade
          rm -rf "$@"