The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
App-Sqitch-0.70-TRIAL
River stage one • 2 direct dependents • 2 total dependents
43 ++
/ App::Sqitch::Plan

Name

App::Sqitch::Plan - Sqitch Deployment Plan

Synopsis

  my $plan = App::Sqitch::Plan->new( sqitch => $sqitch );
  while (my $change = $plan->next) {
      say "Deploy ", $change->format_name;
  }

Description

App::Sqitch::Plan provides the interface for a Sqitch plan. It parses a plan file and provides an iteration interface for working with the plan.

Interface

Constants

SYNTAX_VERSION

Returns the current version of the Sqitch plan syntax. Used for the %sytax-version pragma.

Constructors

new

  my $plan = App::Sqitch::Plan->new( sqitch => $sqitch );

Instantiates and returns a App::Sqitch::Plan object. Takes a single parameter: an App::Sqitch object.

Accessors

sqitch

  my $sqitch = $cmd->sqitch;

Returns the App::Sqitch object that instantiated the plan.

position

Returns the current position of the iterator. This is an integer that's used as an index into plan. If next() has not been called, or if reset() has been called, the value will be -1, meaning it is outside of the plan. When next returns undef, the value will be the last index in the plan plus 1.

Instance Methods

index_of

  my $index      = $plan->index_of('6c2f28d125aff1deea615f8de774599acf39a7a1');
  my $foo_index  = $plan->index_of('@foo');
  my $bar_index  = $plan->index_of('bar');
  my $bar1_index = $plan->index_of('bar@alpha')
  my $bar2_index = $plan->index_of('bar@HEAD');

Returns the index of the specified change. Returns undef if no such change exists. The argument may be any one of:

  • An ID

      my $index = $plan->index_of('6c2f28d125aff1deea615f8de774599acf39a7a1');

    This is the SHA1 hash of a change or tag. Currently, the full 40-character hexed hash string must be specified.

  • A change name

      my $index = $plan->index_of('users_table');

    The name of a change. Will throw an exception if the named change appears more than once in the list.

  • A tag name

      my $index = $plan->index_of('@beta1');

    The name of a tag, including the leading @.

  • A tag-qualified change name

      my $index = $plan->index_of('users_table@beta1');

    The named change as it was last seen in the list before the specified tag.

get

  my $change = $plan->get('6c2f28d125aff1deea615f8de774599acf39a7a1');
  my $foo  = $plan->index_of('@foo');
  my $bar  = $plan->index_of('bar');
  my $bar1 = $plan->index_of('bar@alpha')
  my $bar2 = $plan->index_of('bar@HEAD');

Returns the change corresponding to the specified ID or name. The argument may be in any of the formats described for index_of().

find

  my $change = $plan->find('6c2f28d125aff1deea615f8de774599acf39a7a1');
  my $foo  = $plan->index_of('@foo');
  my $bar  = $plan->index_of('bar');
  my $bar1 = $plan->index_of('bar@alpha')
  my $bar2 = $plan->index_of('bar@HEAD');

Finds the change corresponding to the specified ID or name. The argument may be in any of the formats described for index_of(). Unlike get(), find() will not throw an error if more than one change exists with the specified name, but will return the first instance.

first_index_of

  my $index = $plan->first_index_of($change_name);
  my $index = $plan->first_index_of($change_name, $change_or_tag_name);

Returns the index of the first instance of the named change in the plan. If a second argument is passed, the index of the first instance of the change after the the index of the second argument will be returned. This is useful for getting the index of a change as it was deployed after a particular tag, for example, to get the first index of the foo change since the @beta tag, do this:

  my $index = $plan->first_index_of('foo', '@beta');

You can also specify the first instance of a change after another change, including such a change at the point of a tag:

  my $index = $plan->first_index_of('foo', 'users_table@beta1');

The second argument must unambiguously refer to a single change in the plan. As such, it should usually be a tag name or tag-qualified change name. Returns undef if the change does not appear in the plan, or if it does not appear after the specified second argument change name.

last_tagged_change

  my $change = $plan->last_tagged_change;

Returns the last tagged change object. Returns undef if no changes have been tagged.

change_at

  my $change = $plan->change_at($index);

Returns the change at the specified index.

seek

  $plan->seek('@foo');
  $plan->seek('bar');

Move the plan position to the specified change. Dies if the change cannot be found in the plan.

reset

   $plan->reset;

Resets iteration. Same as $plan->position(-1), but better.

next

  while (my $change = $plan->next) {
      say "Deploy ", $change->format_name;
  }

Returns the next change in the plan. Returns undef if there are no more changes.

last

  my $change = $plan->last;

Returns the last change in the plan. Does not change the current position.

current

   my $change = $plan->current;

Returns the same change as was last returned by next(). Returns undef if next() has not been called or if the plan has been reset.

peek

   my $change = $plan->peek;

Returns the next change in the plan without incrementing the iterator. Returns undef if there are no more changes beyond the current change.

changes

  my @changes = $plan->changes;

Returns all of the changes in the plan. This constitutes the entire plan.

tags

  my @tags = $plan->tags;

Returns all of the tags in the plan.

count

  my $count = $plan->count;

Returns the number of changes in the plan.

lines

  my @lines = $plan->lines;

Returns all of the lines in the plan. This includes all the changes, tags, pragmas, and blank lines.

do

  $plan->do(sub { say $_[0]->name; return $_[0]; });
  $plan->do(sub { say $_->name;    return $_;    });

Pass a code reference to this method to execute it for each change in the plan. Each change will be stored in $_ before executing the code reference, and will also be passed as the sole argument. If next() has been called prior to the call to do(), then only the remaining changes in the iterator will passed to the code reference. Iteration terminates when the code reference returns false, so be sure to have it return a true value if you want it to iterate over every change.

write_to

  $plan->write_to($file);

Write the plan to the named file, including. comments and white space from the original plan file.

open_script

  my $file_handle = $plan->open_script( $change->deploy_file );

Opens the script file passed to it and returns a file handle for reading. The script file must be encoded in UTF-8.

load

  my $plan_data = $plan->load;

Loads the plan data. Called internally, not meant to be called directly, as it parses the plan file and deploy scripts every time it's called. If you want the all of the changes, call changes() instead.

sort_changes

  @changes = $plan->sort_changes(@changes);
  @changes = $plan->sort_changes( { '@foo' => 1, 'bar' => 1 }, @changes );

Sorts a list of changes in dependency order and returns them. If the first argument is a hash reference, its keys should be previously-seen change and tag names that can be assumed to be satisfied requirements for the succeeding changes.

add_tag

  $plan->add_tag('whee');

Adds a tag to the plan. Exits with a fatal error if the tag already exists in the plan.

add

  $plan->add( 'whatevs' );
  $plan->add( 'widgets', [qw(foo bar)], [qw(dr_evil)] );

Adds a change to the plan. The second argument specifies a list of required changes. The third argument specifies a list of conflicting changes. Exits with a fatal error if the change already exists, or if the any of the dependencies are unknown.

rework

  $plan->rework( 'whatevs' );
  $plan->rework( 'widgets', [qw(foo bar)], [qw(dr_evil)] );

Reworks an existing change. Said change must already exist in the plan and be tagged or have a tag following it or an exception will be thrown. The previous occurrence of the change will have the suffix of the most recent tag added to it, and a new tag instance will be added to the list.

Plan File

A plan file describes the deployment changes to be run against a database, and is typically maintained using the add and rework commands. Its contents must be plain text encoded as UTF-8. Each line of a plan file may be one of four things:

  • A blank line. May include any amount of white space, which will be ignored.

  • A Pragma

    Begins with a %, followed by a pragma name, optionally followed by = and a value. Currently, the only pragma recognized by Sqitch is syntax-version.

  • A change.

    A named change change. A change consists of an optional + or - character followed by one or more non-whitespace characters, of which the first and last characters must not be punctuation characters. A change may then also contain a space-delimited list of dependencies, which are the names of other changes or tags prefixed with a colon (:) for required changes or with an exclamation point (!) for conflicting changes.

    Changes with a leading - are slated to be reverted, while changes with no character or a leading + are to be deployed.

  • A tag.

    A named deployment tag, generally corresponding to a release name. Begins with a @, followed by one or more non-whitespace characters. The first and last characters must not be punctuation characters.

  • A comment.

    Begins with a # and goes to the end of the line. Preceding white space is ignored. May appear on a line after a pragma, change, or tag.

Here's an example of a plan file with a single deploy change and tag:

 %syntax-version=1.0.0
 +users_table
 @alpha

There may, of course, be any number of tags and changes. Here's an expansion:

 %syntax-version=1.0.0
 +users_table
 +insert_user
 +update_user
 +delete_user
 @root
 @alpha

Here we have four changes -- "users_table", "insert_user", "update_user", and "delete_user" -- followed by two tags: "@root" and "@alpha".

Most plans will have many changes and tags. Here's a longer example with three tagged deployment points, as well as a change that is deployed and later reverted:

 %syntax-version=1.0.0
 +users_table
 +insert_user
 +update_user
 +delete_user
 +dr_evil
 @root
 @alpha

 +widgets_table
 +list_widgets
 @beta

 -dr_evil
 +ftw
 @gamma

Using this plan, to deploy to the "beta" tag, all of the changes up to the "@root" and "@alpha" tags must be deployed, as must changes listed before the "@beta" tag. To then deploy to the "@gamma" tag, the "dr_evil" change must be reverted and the "ftw" change must be deployed. If you then choose to revert to "@alpha", then the "ftw" change will be reverted, the "dr_evil" change re-deployed, and the "@gamma" tag removed; then "list_widgets" must be reverted and the associated "@beta" tag removed, then the "widgets_table" change must be reverted.

Changes can only be repeated if one or more tags intervene. This allows Sqitch to distinguish between them. An example:

 %syntax-version=1.0.0
 +users_table
 @alpha

 +add_widget
 +widgets_table
 @beta

 +add_user
 @gamma

 +widgets_created_at
 @delta

 +add_widget

Note that the "add_widget" change is repeated after the "@beta" tag, and at the end. Sqitch will notice the repetition when it parses this file, and allow it, because at least one tag "@beta" appears between the instances of "add_widget". When deploying, Sqitch will fetch the instance of the deploy script as of the "@delta" tag and apply it as the first change, and then, when it gets to the last change, retrieve the current instance of the deploy script. How does it find such files? The first instances files will either be named add_widget@delta.sql or (soon) findable in the VCS history as of a VCS "delta" tag.

Grammar

Here is the EBNF Grammar for the plan file:

  plan-file    = { <pragma> | <change-line> | <tag-line> | <comment-line> | <blank-line> }* ;

  blank-line   = [ <blanks> ] <eol>;
  comment-line = <comment> ;
  change-line    = <name> [ { <requires> | <conflicts} } ] ( <eol> | <comment> ) ;
  tag-line     = <tag> ( <eol> | <comment> ) ;
  pragma       = "%" [ <blanks> ] <name> [ <blanks> ] = [ <blanks> ] <value> ( <eol> | <comment> ) ;

  tag          = "@" <name> ;
  requires     = ":" <name> ;
  conflicts    = "!" <name> ;
  name         = <non-punct> [ [ ? non-blank and not "@" or "#" characters ? ] <non-punct> ] ;
  non-punct    = ? non-punctuation, non-blank character ? ;
  value        = ? non-EOL or "#" characters ?

  comment      = [ <blanks> ] "#" [ <string> ] <EOL> ;
  eol          = [ <blanks> ] <EOL> ;

  blanks       = ? blank characters ? ;
  string       = ? non-EOL characters ? ;

And written as regular expressions:

  my $eol          = qr/[[:blank:]]*$/
  my $comment      = qr/(?:[[:blank:]]+)?[#].+$/;
  my $name         = qr/[^[:punct:][:blank:]](?:(?:[^[:space:]@]+)?[^[:punct:][:blank:]])?/;
  my $tag          = qr/[@]$name/;
  my $requires     = qr/[:]$name/;
  my conflicts     = qr/[!]$name/;
  my $tag_line     = qr/^$tag(?:$comment|$eol)/;
  my $change_line    = qr/^$name(?:$requires|$conflicts)*(?:$comment|$eol)/;
  my $comment_line = qr/^$comment/;
  my $pragma    = qr/^][[:blank:]]*[%][[:blank:]]*$name[[:blank:]]*=[[:blank:]].+?(?:$comment|$eol)$/;
  my $blank_line   = qr/^$eol/;
  my $plan         = qr/(?:$pragma|$change_line|$tag_line|$comment_line|$blank_line)+/ms;

See Also

sqitch

The Sqitch command-line client.

Author

David E. Wheeler <david@justatheory.com>

License

Copyright (c) 2012 iovation Inc.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.