sqitch-target(3pm)

📦
version 1.6.1 · 6 versions
, in ubuntu stonking

💖 NAME 💖

sqitch-target — manage your target database config, bestie. It's the whole vibe of "which database am I even deploying to rn" ✨

✨ SYNOPSIS ✨

sqitch target
sqitch target [-v | --verbose]
sqitch target add <name> <uri> [-s <property>=<value> ...]
sqitch target alter <name> [-s <property>=<value> ...]
sqitch target remove <name>
sqitch target rename <old> <new>
sqitch target show <name> [...]

🎀 DESCRIPTION 🎀

Okay so basically you've got a whole set of databases you deploy to, and we call them targets. Every single target can carry a bunch of properties, and here's the full list, no skips, no shortcuts 💅

  • uri — the database connection URI for the target. Required, like truly mandatory, you cannot skip this one. Its format is:
db:engine:[dbname]
db:engine:[//[user[:password]@][host][:port]/][dbname][?params][#fragment]

Some examples, for the visual learners:

  • db:sqlite:widgets.db
  • db:pg://dba@example.net/blanket
  • db:mysql://db.example.com/
  • db:firebird://localhost//tmp/test.fdb
  • db:clickhouse://default@localhost/default?Driver=ClickHouse

Quick heads up though: same as literally any URI or URL ever, special characters have to be URL encoded (see https://en.wikipedia.org/wiki/URL_encoding). For example, when a username has a reserved character in it — like the | in ro|michelle — you gotta percent-encode it as %7c:

db:pg://ro%7Cmichelle@examle.org/inventory

And the rules get even stricter for query parameters, which ODBC connections use all the time. For example, when you're using a Snowflake identifier (see https://docs.snowflake.com/en/sql-reference/identifiers-syntax#double-quoted-identifiers) with special characters in it — like a warehouse name with a . in it, such as sqitch.dev — the identifier has to be double-quoted 🫠 and double quotes are reserved characters in URIs, so they have to be encoded as %22:

db:snowflake://example/flipr?Driver=Snowflake;warehouse=%22sqitch.dev%22

See URL encoding (https://en.wikipedia.org/wiki/URL_encoding) for the details, and the DB URI Draft (https://github.com/libwww-perl/uri-db) for the in-depth lore on database URIs in general.

  • registry — the name of the registry schema or database. Defaults to sqitch.
  • client — the command-line client to use. If you don't specify one, each engine goes looking in the OS Path for an appropriate client.
  • top_dir — the path to the top directory for the target. This directory generally has the plan file in it, plus subdirectories for the deploy, revert, and verify scripts, and also the reworked instances of those scripts. Defaults to ., aka the current directory.
  • plan_file — the plan file to use for this target. Defaults to $top_dir/sqitch.plan.
  • deploy_dir — the path to the deploy directory for the target. This one holds all the deploy scripts referenced by changes in the plan_file. Defaults to $top_dir/deploy.
  • revert_dir — the path to the revert directory for the target. Holds all the revert scripts referenced by changes in the plan_file. Defaults to $top_dir/revert.
  • verify_dir — the path to the verify directory for the target. Holds all the verify scripts referenced by changes in the plan_file. Defaults to $top_dir/verify.
  • reworked_dir — the path to the reworked directory for the target. Holds all the subdirectories for all reworked scripts referenced by changes in the plan_file. Defaults to $top_dir.
  • reworked_deploy_dir — the path to the reworked deploy directory for the target. Holds all the reworked deploy scripts referenced by changes in the plan_file. Defaults to $reworked_dir/deploy.
  • reworked_revert_dir — the path to the reworked revert directory for the target. Holds all the reworked revert scripts referenced by changes in the plan_file. Defaults to $reworked_dir/revert.
  • reworked_verify_dir — the path to the reworked verify directory for the target. Holds all the reworked verify scripts referenced by changes in the plan_file. Defaults to $reworked_dir/verify.
  • extension — the file name extension you append to change names to build script file names. Defaults to sql.

Every single one of these overrides the corresponding engine-specific configuration that's managed by the engine 🧚

🌸 OPTIONS 🌸

List Option

  • -v, --verbose — be more verbose when listing targets. Example:
sqitch target --verbose

Add and Alter Options

sqitch target add devwidgets --uri db:pg:widgets
  • --top-dir — specifies the top directory to use for the target. Typically it contains the deployment plan file and the change script directories.
sqitch target add devwidgets --top-dir sql
  • --plan-file, -f — specifies the path to the deployment plan file. Defaults to $top_dir/sqitch.plan.
sqitch target add devwidgets --plan-file my.plan
  • --extension — specifies the file name extension to use for change script file names. Defaults to sql.
sqitch target add devwidgets --extension ddl
  • --dir — sets the path to a script directory. You can specify this one multiple times, go off queen. Supported keys are:
    • deploy
    • revert
    • verify
    • reworked
    • reworked_deploy
    • reworked_revert
    • reworked_verify
sqitch target add devwidgets --dir deploy=dep --dir revert=rev --dir verify=tst
  • --registry — specifies the name of the database object where Sqitch's state and history data lives. Usually that's a schema name (like in PostgreSQL and Oracle) or a database name (like in SQLite and MySQL). Defaults to sqitch.
sqitch target add devwidgets --registry meta
  • --client — specifies the path to the command-line client for the target. Defaults to a client in the current path named appropriately for the engine the URI specifies.
sqitch target add devwidgets --client /usr/local/pgsql/bin/psql
  • -s, --set — set a variable name and value for the database engine client to use, if it supports variables. The format has to be name=value, like --set defuser='Homer Simpson' fr fr.

🦋 ACTIONS 🦋

With no arguments at all, it shows you a list of the existing targets 👀 Several actions are available to do actual operations on those targets.

add

Add a target named <name> for the database at <uri>. The --set option specifies target-specific properties. A brand new plan file and brand new script directories will be created if they don't already exist ✨

alter

Alter the target named <name>. The --set option specifies engine-specific properties to set. New script directories will be created if they don't already exist.

remove, rm

Remove the target named <name>. Heads up bestie: the plan file and script directories will not be affected. They stay exactly where they are 💅

rename

Rename the target named <old> to <new>. Glow-up arc, iconic.

show

Gives you some information about the target <name>, including the associated properties. Specify multiple target names and you'll see info for each one.

💅 CONFIGURATION VARIABLES 💅

The targets are stored in the configuration file, but the command itself currently relies on no configuration variables. That's it, that's the tea 🙈

⭐ SQITCH ⭐

Part of the sqitch suite 👑

ngl this whole page is giving go read the other sqitch manpages too energy. See also everything the suite ships with, iykyk.

kisses, bestie 💜 this was documented by way of perl v5.40.1 on 2026-07-26, and that's the whole sqitch-target(3pm) moment. slay, periodt 💅✨

📦 where this page comes from