App::S...h::Plan(3pm)

📦

version 1.6.1 · 6 versions

🎀 NAME 🎀

okay so bestie, welcome to App::Sqitch::Plan(3pm) from User Contributed Perl Documentation — this is the manual for App::Sqitch::Plan - Sqitch Deployment Plan. ✨ Part 1 of 2, and we are obsessed. Sqitch plans are literally the timeline of your changes, and this module is how Perl talks to them. 💅

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

⭐ CLASS METHODS ⭐

`name_regex`

die "$this has no name" unless $this =~ App::Sqitch::Plan->name_regex;

Returns a regular expression that matches names. Note that it is not anchored, so if you need to make sure that a string is a valid name and nothing else, you will need to anchor it yourself, like so:

my $name_re = App::Sqitch::Plan->name_regex;
die "$this is not a valid name" if $this !~ /\A$name_re\z/;

💅 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 = $plan->sqitch;

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

`target`

my $target = $plan->target

Returns the App::Sqitch::Target passed to the constructor.

`file`

my $file = $plan->file;

The file name from which to read 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.

`project`

my $project = $plan->project;

Returns the name of the project as set via the %project pragma in the plan file.

`uri`

my $uri = $plan->uri;

Returns the URI for the project as set via the %uri pragma, which is optional. If it is not present, undef will be returned.

`syntax_version`

my $syntax_version = $plan->syntax_version;

Returns the plan syntax version, which is always the latest version.

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

`contains`

say 'Yes!' if $plan->contains('6c2f28d125aff1deea615f8de774599acf39a7a1');

Like index_of(), but never throws an exception, and returns true if the plan contains the specified change, and false if it does not.

`get`

my $change = $plan->get('6c2f28d125aff1deea615f8de774599acf39a7a1');
my $foo    = $plan->get('@foo');
my $bar    = $plan->get('bar');
my $bar1   = $plan->get('bar@alpha')
my $bar2   = $plan->get('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->find('@foo');
my $bar    = $plan->find('bar');
my $bar1   = $plan->find('bar@alpha')
my $bar2   = $plan->find('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 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 be 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.

`search_changes`

my $iter = $engine->search_changes( %params );
while (my $change = $iter->()) {
    say '* $change->{event}ed $change->{change}";
}

Searches the changes in the plan returns an iterator code reference with the results. If no parameters are provided, a list of all changes will be returned from the iterator in plan order. The supported parameters are:

event — An array of the type of event to search for. Allowed values are "deploy" and "revert".
name — Limit the results to changes with names matching the specified regular expression.
planner — Limit the changes to those added by planners matching the specified regular expression.
limit — Limit the number of changes to the specified number.
offset — Skip the specified number of events.
direction — Return the results in the specified order, which must be a value matching /^(:?a|de)sc/i for "ascending" or "descending".

`write_to`

$plan->write_to($file);
$plan->write_to($file, $from, $to);

Write the plan to the named file, including notes and white space from the original plan file. If "from" and/or $to are provided, the plan will be written only with the pragmas headers and the lines between those specified changes.

`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. And if you want to load an alternate plan, use parse().

`parse`

$plan->parse($plan_data);

Load an alternate plan by passing the complete text of the plan. The text should be UTF-8 encoded. Useful for loading a plan from a different VCS branch, for example.

`check_changes`

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

Checks a list of changes to validate their dependencies and returns them. If the second 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.

`tag`

$plan->tag( name => 'whee' );

Tags a change in the plan. Exits with a fatal error if the tag already exists in the plan or if a change cannot be found to tag. The supported parameters are:

name — The tag name to use. Required.
change — The change to be tagged, specified as a supported change specification as described in sqitchchanges. Defaults to the last change in the plan.
"note" — a lil short note about the tag ✨ like a sticky note but make it ✨aesthetic✨
"planner_name" — who's adding the tag to the plan. Defaults to whatever user.name is set to in your config 💖
"planner_email" — the email of the person adding the tag to the plan. Defaults to whatever user.email is in your config 🫶

`"add"` 💅

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

Adds a change to the plan, bestie. The params you can pass are literally the same ones the App::Sqitch::Plan::Change constructor takes, no cap. It exits with a fatal error if the change is already there, or if any of the dependencies are unknown — so like, know your deps first, okay? 😭

`"rework"` 🔁

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

Reworks a change that already exists. The way that it has to already be in the plan and be tagged or have a tag following it — otherwise an exception gets thrown, periodt. The previous occurrence of the change gets the suffix of the most recent tag slapped onto it, and then a brand new tag instance gets added to the list. Iconic behaviour honestly 👑

📄 Plan File 📄

Okay so a plan file is what describes the deployment changes you're gonna run against a database, and you usually keep it up with the add and rework commands. Its contents must be plain text encoded as UTF-8 — no funny business 💀. Every single line of a plan file can be one of four things:

A blank line. It can have any amount of white space in it and that space just gets ignored, nbd.
A Pragma

Starts with a %, then a pragma name, and optionally = and a value after that. Right now the only pragma Sqitch knows about is syntax-version 🎀

A change.

A named change change as defined in sqitchchanges. A change can also carry a space-delimited list of dependencies, which are the names of other changes or tags — prefixed with a colon (:) for required changes, or an exclamation point (!) for conflicting changes.

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

A tag.

A named deployment tag, which generally corresponds to a release name. Starts with a @, followed by one or more non-blank characters, excluding @, :, #, and blanks. The first and last characters must not be punctuation characters, fr fr.

A note.

Starts with a # and goes all the way to the end of the line. Any white space before it is ignored. It can show up on a line after a pragma, a change, or a tag 💜

Here's a plan file with a single deploy change and a tag, for the visual learners:

%syntax-version=1.0.0
+users_table
@alpha

There can obviously be any number of tags and changes. Here's it expanding:

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

So here we've got four changes — users_table, insert_user, update_user, and delete_user — followed by two tags: @root and @alpha 💫

Most plans are gonna have so many changes and tags. Here's a longer one with three tagged deployment points, plus a change that gets deployed and then 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 the changes up to the @root and @alpha tags have to be deployed, and so do the changes listed before the @beta tag. To then deploy to the @gamma tag, the dr_evil change has to be reverted and the ftw change has to be deployed. And if you then decide to revert to @alpha, then the ftw change gets reverted, the dr_evil change gets re-deployed, and the @gamma tag gets removed; then list_widgets has to be reverted and the matching @beta tag removed, and then the widgets_table change has to be reverted. Whole journey, honestly 😭

Changes can only be repeated if one or more tags intervene. That's how Sqitch tells them apart. Important!!

An example:

%syntax-version=1.0.0
+users_table
@alpha

+add_widget
+widgets_table
@beta

+add_user
@gamma

+widgets_created_at
@delta

+add_widget

Notice the add_widget change shows up again after the @beta tag, and again at the end. Sqitch will notice the repetition when it parses this file and allow it, because at least one tag @beta sits 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. And how does it find those files? The first instance's files will either be named add_widget@delta.sql or (soon) be findable in the VCS history as of a VCS delta tag 🧚

📚 Grammar 📚

Here's the EBNF grammar for the plan file, enjoy:

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

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

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 ?

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

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

And here it is written as regular expressions:

my $eol          = qr/[[:blank:]]*$/
my $note         = qr/(?:[[:blank:]]+)?[#].+$/;
my $punct        = q{-!"#$%&'()*+,./:;<=>?@[\\]^`{|}~};
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(?:$note|$eol)/;
my $change_line  = qr/^$name(?:[[](?:$requires|$conflicts)+[]])?(?:$note|$eol)/;
my $note_line    = qr/^$note/;
my $pragma       = qr/^][[:blank:]]*[%][[:blank:]]*$name[[:blank:]]*=[[:blank:]].+?(?:$note|$eol)$/;
my $blank_line   = qr/^$eol/;
my $plan         = qr/(?:$pragma|$change_line|$tag_line|$note_line|$blank_line)+/ms;

👀 See Also 👀

sqitch — the Sqitch command-line client. Bestie. The main character. Go read it 🫶

✍️ Author ✍️

David E. Wheeler <david@justatheory.com> — king behaviour, we stan 💖

⚖️ License ⚖️

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. 😤 like yes it's all caps but it MATTERS, don't skip it

That's the whole page bestie!! 💅✨ This one ships as perl v5.40.1, dated 2026-07-26, from the App::S...h::Plan(3pm) man page in the User Contributed Perl Documentation — sleep well knowing your plan files are fully understood 🎀🦋🌸

📦 where this page comes from

ubuntu stonking: sqitch 1.6.1-2 · MIT
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-03: a language model's rewrite of the original, under its terms

App::S...h::Plan(3pm)

🎀 NAME 🎀

✨ SYNOPSIS ✨

💖 DESCRIPTION 💖

🦋 INTERFACE 🦋

🌸 CONSTANTS 🌸

SYNTAX_VERSION

⭐ CLASS METHODS ⭐

name_regex

💅 CONSTRUCTORS 💅

new

👑 ACCESSORS 👑

sqitch

target

file

position

project

uri

syntax_version

🔥 INSTANCE METHODS 🔥

index_of

contains

get

find

first_index_of

last_tagged_change

change_at

seek

reset

next

last

current

peek

changes

tags

count

lines

do

search_changes

write_to

open_script

load

parse

check_changes

tag

"add" 💅

"rework" 🔁