view release on metacpan or  search on metacpan

README  view on Meta::CPAN

    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 "$@"
    
        # ... and use it:
        only_upgrade
          echo "Just upgraded to $MIGRATE_NEXT_VERSION"
    
        VERSION 1.0.1
    
        # another lazy macro (must be defined above in same file)
        mkdir dir1 dir2
    
        VERSION 1.1.0

 Specification

    Recommended name for file with upgrade/downgrade operations is either
    migrate or <version>.migrate.

    Each line in migrate file must be one of these:

      * line start with symbol "#"

      For comments. Line is ignored.

      * line start with any non-space symbol, except "#"

      Contain one or more elements separated by one or more space symbols:
      operation name (case-sensitive), zero or more params (any param may
      be quoted, params which contain one of 5 symbols "\\\"\t\r\n" must be
      quoted).

      Quoted params must be surrounded by double-quote symbol, and any of
      mentioned above 5 symbols must be escaped like shown above.

      * line start with two spaces

      Zero or more such lines after line with operation name form one more,
      multiline, extra param for that operation (first two spaces will be
      removed from start of each line before providing this param to
      operation).

      Not all operations may have such multiline param.