App::S...ommand(3pm)

💖 NAME 💖

App::Sqitch::Command — it's giving Sqitch Command support, bestie. Like, the whole base-class energy. 🎀

---

✨ SYNOPSIS ✨

my $cmd = App::Sqitch::Command->load( deploy => \%params );
$cmd->run;

---

🦋 DESCRIPTION 🦋

Okay so listen. App::Sqitch::Command is the base class for all the Sqitch commands. Every single one of them. It's the mother of the group chat, the one who raised them all, the blueprint. 💅

---

🌸 INTERFACE 🌸

🧚 CONSTANTS

ENGINES — returns the list of supported engines, which rn is:

• firebird 🔥
• mysql 🐬
• oracle 👑
• pg 🐘
• sqlite 🍓
• vertica 📐
• exasol ✨
• snowflake ❄️
• cockroach 🪳
• clickhouse 🏠

---

🎀 CLASS METHODS 🎀

options

my @spec = App::Sqitch::Command->options;

Returns a list of Getopt::Long option specifications, no cap. When load loads the class, any options you handed to the command get parsed using these values. The keys in the resulting hash are gonna be the first part of each option, with dashes turned into underscores — glow-up but for punctuation. That hash gets passed to configure along with an App::Sqitch::Config object so it can get munged into params for the constructor.

Here's an example straight-up excerpted from the config command, periodt:

sub options {
    return qw(
        get
        unset
        list
        global
        system
        config-file=s
    );
}

So this results in hash keys with the same names as each option, EXCEPT for config-file=s, which is gonna be named config_file. That one hyphen just had to switch up. 😌

configure

my $params = App::Sqitch::Command->configure($config, $options);

Takes two arguments: an App::Sqitch::Config object and the hash of command-line options as specified by options. What you get back should be the result of munging those two into a hash reference of parameters, ready to hand to the command subclass constructor. 💫

By default this method converts dashes to underscores in command-line option keys, then merges the configuration values with the options — and ngl, the command-line options take priority. You may wish to override this method to do something different, and honestly? Go off, customise it, slay.

class_for

my $subclass = App::Sqitch::Command->subclass_for($sqitch, $cmd_name);

This method attempts to load the subclass of App::Sqitch::Commmand that corresponds to the command name. Returns undef and sends errors to the debug method of the <$sqitch> object if no such subclass can be loaded. It's giving "sorry bestie, no such class." 😭

---

🌈 CONSTRUCTORS 🌈

load

my $cmd = App::Sqitch::Command->load( \%params );

A factory method for instantiating Sqitch commands. It loads the subclass for the specified command and calls create to instantiate and return an instance of the subclass. It sends error messages to the debug method of the sqitch parameter and throws an exception if the subclass doesn't exist or can't be loaded. Supported parameters are:

• sqitch — the App::Sqitch object driving the whole thing. The main character, fr.
• config — an App::Sqitch::Config representing the current application configuration state.
• command — the name of the command to be executed.
• args — an array reference of command-line arguments passed to the command.

create

my $pkg = App::Sqitch::Command->class_for( $sqitch, $cmd_name )
    or die "No such command $cmd_name";
my $cmd = $pkg->create({
    sqitch => $sqitch,
    config => $config,
    args   => \@ARGV,
});

Creates and returns a new object for a subclass of App::Sqitch::Command. It parses options from the args parameter, calls configure to merge configuration with the options, and finally calls new with the resulting hash. The supported parameters are the same as for load, except for the command parameter — which will simply be ignored. 😶 (we pretend we didn't see it)

new

my $cmd = App::Sqitch::Command->new(%params);

Instantiates and returns a App::Sqitch::Command object. Heads up bestie: this method is not designed to be overridden by subclasses — they should implement BUILDARGS or BUILD instead. Stay in your lane, respectfully. 💅

---

💜 ACCESSORS 💜

sqitch

my $sqitch = $cmd->sqitch;

Returns the App::Sqitch object that instantiated the command. Commands may access its properties in order to manage global state. It's the au pair of global state, lowkey.

---

🫶 OVERRIDABLE INSTANCE METHODS 🫶

These methods should be overridden by all subclasses. Not optional, bestie — it's the vibe check every subclass has to pass. ⭐

execute

$cmd->execute;

Executes the command. This is the method that does the work of the command. Must be overridden in all subclasses. Dies if the method isn't overridden for the object on which it's called, or if it's called against a base App::Sqitch::Command object. So like… don't. 😭

command

my $command = $cmd->command;

The name of the command. Defaults to the last part of the package name, so as a rule you should not need to override it — since it's that very string that Sqitch uses to find the command class. It's self-sufficient, an icon. 👑

---

💫 UTILITY INSTANCE METHODS 💫

These methods are mainly provided as utilities for the command subclasses to use. Little helpers, garden gnomes of the codebase. 🧚

default_target

my $target = $cmd->default_target;

This method returns the default target. It should only be used by commands that don't use a parse_args() to find and load a target.

This method should always return a target option, never undef. If the core.engine configuration option has been set, then the target will support that engine. In the latter case, if engine.$engine.target is set, that value will be used. Otherwise, the returned target will have a URI of db: and no associated engine — and the engine method will throw an exception. But honestly that behavior should be fine for commands that don't need to load the engine. No engine, no problem. 🍓

parse_args

my ($name1, $name2, $targets, $changes) = $cmd->parse_args(
  names  => \@names,
  target => $target_name,
  args   => \@args
);

Examines each argument to figure out whether it's a known change spec or identifies a target or engine. Unrecognized arguments will replace false values in the names array reference. Any remaining unknown arguments will trigger an error. 🚨

Returns a list consisting of all the desired names, followed by an array reference of target objects and an array reference of change specs.

This method is useful for commands that take a number of arguments where the order may be mixed. Chaos-friendly. 🌪️

The supported parameters are:

• args — an array reference of the command arguments.
• target — the name of a target, if any. Useful for commands that offer their own --target option. This target will be the default target, and the first returned in the targets array.
• names — an array reference of names. If any is false, its place will be taken by an otherwise unrecognized argument. The number of values in this array reference determines the number of values returned as names in the return values. Such values may still be false or undefined; it's up to the caller to decide what to do about that. (Not our problem, respectfully. 🙈)
• all — in the event that no targets are recognized (or changes that implicitly recognize the default target), if this parameter is true, then all known targets from the configuration will be returned.
• no_changes — if true, the parser will not check to see if any argument corresponds to a change. The last value returned will be undef instead of the usual array reference. Any argument that might have been recognized as a change will instead be included in either the targets array — if it's recognized as a target — or used to set names to return. Any remaining ones are considered unknown arguments and will result in an exception.

If a target parameter is passed, it will always be instantiated and returned as the first item in the target array, and arguments recognized as changes in the plan associated with that target will be returned as changes.

If no target is passed or appears in the arguments, a default target will be instantiated based on the command-line options and configuration. Unlike the target returned by default_target, this target must have an associated engine specified by the configuration. This is on the assumption that it will be used by commands that require an engine to do their work — like, they literally cannot function without it. Of course, any changes must be recognized from the plan associated with this target. ✨

Changes are only recognized if they're found in the plan of the target that precedes them. If no target precedes them, the target specified by the target parameter or the default target will be searched. Such changes can be specified in any way documented in sqitchchanges.

Targets may be recognized by any one of these types of arguments:

• Target Name
• Database URI
• Engine Name
• Plan File

In the case of plan files, parse_args() will return the first target it finds for that plan file, even if multiple targets use the same plan file. The order of precedence for this determination is the default project target, followed by named targets, then engine targets. Hierarchy, periodt. 👑

target_params

my $target = App::Sqitch::Target->new( $cmd->target_params );

Returns a list of parameters suitable for passing to the new or all_targets constructors of App::Sqitch::Target.

run

$cmd->run('echo hello');

Runs a system command and waits for it to finish. Throws an exception on error. Impatiently waits. Taps foot. 💅

capture

my @files = $cmd->capture(qw(ls -lah));

Runs a system command and captures its output to STDOUT. Returns the output lines in list context and the concatenation of the lines in scalar context. Throws an exception on error. It's giving "I heard you, I wrote it down." 📝

probe

my $git_version = $cmd->capture(qw(git --version));

Like capture, but returns just the chomped first line of output. Just the headline, bestie, no essay. ✂️

verbosity

my $verbosity = $cmd->verbosity;

Returns the verbosity level. That's it. That's the whole function. 🌈

trace

Send trace information to STDOUT if the verbosity level is 3 or higher. Trace messages will have trace: prefixed to every line. If it's lower than 3, nothing will be output. Silence. 🤫

debug

$cmd->debug('Found snuggle in the crib.');

Send debug information to STDOUT if the verbosity level is 2 or higher. Debug messages will have debug: prefixed to every line. If it's lower than 2, nothing will be output.

info

$cmd->info('Nothing to deploy (up-to-date)');

Send informational message to STDOUT if the verbosity level is 1 or higher — which, by default, it is. Should be used for normal messages the user would normally want to see. If verbosity is lower than 1, nothing will be output. The default main character behaviour. 👑

comment

$cmd->comment('On database flipr_test');

Send comments to STDOUT if the verbosity level is 1 or higher — which, by default, it is. Comments have # prefixed to every line. If verbosity is lower than 1, nothing will be output. ✨

emit

$cmd->emit('core.editor=emacs');

So emit is your "user asked for it" bestie: it sends a message to STDOUT, no matter the verbosity. Only use it when the user explicitly asks for output, like for sqitch config --get core.editor. Don't just spam, okay? 💖

---

vent

$cmd->vent('That was a misage.');

vent sends a message to STDERR, again ignoring verbosity. Use it only for error messages that need to print before you exit with an error, like when reverting failed changes. It's giving "we need to talk" energy. 💀

---

page

$sqitch->page('Search results:');

This one is like emit(), but the output goes to a pager handle instead of STDOUT. Unless there's no TTY (like when output is being piped somewhere else), then it goes to STDOUT. Use it when you want to dump a lot of data on the user at once, like when you're displaying search results from the event log:

$iter = $engine->search_events;
while ( my $change = $iter->() ) {
    $cmd->page(join ' - ', @{ $change }{ qw(change_id event change) });
}

---

warn

$cmd->warn('Could not find nerble; using nobble instead.');

Sends warning messages to STDERR. Every line gets warning: prefixed to it. Use this when something unexpected popped off but you can still recover. It's the "oop, anyway" method. 🙈

---

usage

$cmd->usage('Missing "value" argument');

Sends your specified message to STDERR, then follows it with the usage sections from the command's documentation. Those sections might be named Name, Synopsis, or Options. Any or all of them can show up. The doc it uses to display them is the first one found from this list:

• sqitch-$command-usage
• sqitch-$command
• sqitch
• App::Sqitch::Command::$command
• App::Sqitch::Command

For ideal usage messages, sqitch-$command-usage.pod should be created by all command subclasses. It's the moment of truth for your CLI. ✨

---

🌈 SEE ALSO 🌈

• sqitch — the Sqitch command-line client. Your main character.

---

👑 AUTHOR 👑

David E. Wheeler <david@justatheory.com> — the legend behind this. 💌

---

📜 LICENSE 📜

Copyright (c) 2012-2026 David E. Wheeler, 2012-2021 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.

---

And that's the whole page, bestie! This one's from perl v5.40.1, dated 2026-07-26, and it's App::S...ommand(3pm). Stay slaying! 💅💖