.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "sqitch-target 3pm"
.TH sqitch-target 3pm "2022-10-15" "perl v5.34.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "Name"
.IX Header "Name"
sqitch-target \- Manage target database configuration
.SH "Synopsis"
.IX Header "Synopsis"
.Vb 7
\&  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> [...]
.Ve
.SH "Description"
.IX Header "Description"
Manage the set of databases (\*(L"targets\*(R") you deploy to. Each target may have a
number of properties:
.ie n .IP """uri""" 4
.el .IP "\f(CWuri\fR" 4
.IX Item "uri"
The database connection \s-1URI\s0 for the target. Required. Its format is:
.Sp
.Vb 2
\&  db:engine:[dbname]
\&  db:engine:[//[user[:password]@][host][:port]/][dbname][?params][#fragment]
.Ve
.Sp
Some examples:
.RS 4
.ie n .IP """db:sqlite:widgets.db""" 4
.el .IP "\f(CWdb:sqlite:widgets.db\fR" 4
.IX Item "db:sqlite:widgets.db"
.PD 0
.ie n .IP """db:pg://dba@example.net/blanket""" 4
.el .IP "\f(CWdb:pg://dba@example.net/blanket\fR" 4
.IX Item "db:pg://dba@example.net/blanket"
.ie n .IP """db:mysql://db.example.com/""" 4
.el .IP "\f(CWdb:mysql://db.example.com/\fR" 4
.IX Item "db:mysql://db.example.com/"
.ie n .IP """db:firebird://localhost//tmp/test.fdb""" 4
.el .IP "\f(CWdb:firebird://localhost//tmp/test.fdb\fR" 4
.IX Item "db:firebird://localhost//tmp/test.fdb"
.RE
.RS 4
.PD
.Sp
See the \s-1DB URI\s0 Draft <https://github.com/libwww-perl/uri-db> for details.
.RE
.ie n .IP """registry""" 4
.el .IP "\f(CWregistry\fR" 4
.IX Item "registry"
The name of the registry schema or database. The default is \f(CW\*(C`sqitch\*(C'\fR.
.ie n .IP """client""" 4
.el .IP "\f(CWclient\fR" 4
.IX Item "client"
The command-line client to use. If not specified, each engine looks in the \s-1OS\s0
Path for an appropriate client.
.ie n .IP """top_dir""" 4
.el .IP "\f(CWtop_dir\fR" 4
.IX Item "top_dir"
The path to the top directory for the target. This directory generally
contains the plan file and subdirectories for deploy, revert, and verify
scripts, as well as reworked instances of those scripts. The default is \fI.\fR,
the current directory.
.ie n .IP """plan_file""" 4
.el .IP "\f(CWplan_file\fR" 4
.IX Item "plan_file"
The plan file to use for this target. The default is \f(CW\*(C`$top_dir/sqitch.plan\*(C'\fR.
.ie n .IP """deploy_dir""" 4
.el .IP "\f(CWdeploy_dir\fR" 4
.IX Item "deploy_dir"
The path to the deploy directory for the target. This directory contains all
of the deploy scripts referenced by changes in the \f(CW\*(C`plan_file\*(C'\fR. The default
is \f(CW\*(C`$top_dir/deploy\*(C'\fR.
.ie n .IP """revert_dir""" 4
.el .IP "\f(CWrevert_dir\fR" 4
.IX Item "revert_dir"
The path to the revert directory for the target. This directory contains all
of the revert scripts referenced by changes in the \f(CW\*(C`plan_file\*(C'\fR. The default
is \f(CW\*(C`$top_dir/revert\*(C'\fR.
.ie n .IP """verify_dir""" 4
.el .IP "\f(CWverify_dir\fR" 4
.IX Item "verify_dir"
The path to the verify directory for the target. This directory contains all
of the verify scripts referenced by changes in the \f(CW\*(C`plan_file\*(C'\fR. The default
is \f(CW\*(C`$top_dir/verify\*(C'\fR.
.ie n .IP """reworked_dir""" 4
.el .IP "\f(CWreworked_dir\fR" 4
.IX Item "reworked_dir"
The path to the reworked directory for the target. This directory contains all
subdirectories for all reworked scripts referenced by changes in the
\&\f(CW\*(C`plan_file\*(C'\fR. The default is \f(CW$top_dir\fR.
.ie n .IP """reworked_deploy_dir""" 4
.el .IP "\f(CWreworked_deploy_dir\fR" 4
.IX Item "reworked_deploy_dir"
The path to the reworked deploy directory for the target. This directory
contains all of the reworked deploy scripts referenced by changes in the
\&\f(CW\*(C`plan_file\*(C'\fR. The default is \f(CW\*(C`$reworked_dir/deploy\*(C'\fR.
.ie n .IP """reworked_revert_dir""" 4
.el .IP "\f(CWreworked_revert_dir\fR" 4
.IX Item "reworked_revert_dir"
The path to the reworked revert directory for the target. This directory
contains all of the reworked revert scripts referenced by changes in the
\&\f(CW\*(C`plan_file\*(C'\fR. The default is \f(CW\*(C`$reworked_dir/revert\*(C'\fR.
.ie n .IP """reworked_verify_dir""" 4
.el .IP "\f(CWreworked_verify_dir\fR" 4
.IX Item "reworked_verify_dir"
The path to the reworked verify directory for the target. This directory
contains all of the reworked verify scripts referenced by changes in the
\&\f(CW\*(C`plan_file\*(C'\fR. The default is \f(CW\*(C`$reworked_dir/verify\*(C'\fR.
.ie n .IP """extension""" 4
.el .IP "\f(CWextension\fR" 4
.IX Item "extension"
The file name extension to append to change names to create script file names.
The default is \f(CW\*(C`sql\*(C'\fR.
.PP
Each of these overrides the corresponding engine-specific configuration
managed by engine.
.SH "Options"
.IX Header "Options"
.IP "List Option" 4
.IX Item "List Option"
.RS 4
.PD 0
.ie n .IP """\-v""" 4
.el .IP "\f(CW\-v\fR" 4
.IX Item "-v"
.ie n .IP """\-\-verbose""" 4
.el .IP "\f(CW\-\-verbose\fR" 4
.IX Item "--verbose"
.PD
.Vb 1
\&  sqitch target \-\-verbose
.Ve
.Sp
Be more verbose when listing targets.
.RE
.RS 4
.RE
.IP "Add and Alter Options" 4
.IX Item "Add and Alter Options"
.RS 4
.PD 0
.ie n .IP """\-\-uri""" 4
.el .IP "\f(CW\-\-uri\fR" 4
.IX Item "--uri"
.PD
.Vb 1
\&  sqitch target add devwidgets \-\-uri db:pg:widgets
.Ve
.Sp
Specifies the \s-1URI\s0 <https://github.com/libwww-perl/uri-db/> of the target database.
.ie n .IP """\-\-top\-dir""" 4
.el .IP "\f(CW\-\-top\-dir\fR" 4
.IX Item "--top-dir"
.Vb 1
\&  sqitch target add devwidgets \-\-top\-dir sql
.Ve
.Sp
Specifies the top directory to use for the target. Typically contains the
deployment plan file and the change script directories.
.ie n .IP """\-\-plan\-file""" 4
.el .IP "\f(CW\-\-plan\-file\fR" 4
.IX Item "--plan-file"
.PD 0
.ie n .IP """\-f""" 4
.el .IP "\f(CW\-f\fR" 4
.IX Item "-f"
.PD
.Vb 1
\&  sqitch target add devwidgets \-\-plan\-file my.plan
.Ve
.Sp
Specifies the path to the deployment plan file. Defaults to
\&\f(CW\*(C`$top_dir/sqitch.plan\*(C'\fR.
.ie n .IP """\-\-extension""" 4
.el .IP "\f(CW\-\-extension\fR" 4
.IX Item "--extension"
.Vb 1
\&  sqitch target add devwidgets \-\-extension ddl
.Ve
.Sp
Specifies the file name extension to use for change script file names.
Defaults to \f(CW\*(C`sql\*(C'\fR.
.ie n .IP """\-\-dir""" 4
.el .IP "\f(CW\-\-dir\fR" 4
.IX Item "--dir"
.Vb 1
\&  sqitch target add devwidgets \-\-dir deploy=dep \-\-dir revert=rev \-\-dir verify=tst
.Ve
.Sp
Sets the path to a script directory. May be specified multiple times.
Supported keys are:
.RS 4
.IP "\(bu" 4
\&\f(CW\*(C`deploy\*(C'\fR
.IP "\(bu" 4
\&\f(CW\*(C`revert\*(C'\fR
.IP "\(bu" 4
\&\f(CW\*(C`verify\*(C'\fR
.IP "\(bu" 4
\&\f(CW\*(C`reworked\*(C'\fR
.IP "\(bu" 4
\&\f(CW\*(C`reworked_deploy\*(C'\fR
.IP "\(bu" 4
\&\f(CW\*(C`reworked_revert\*(C'\fR
.IP "\(bu" 4
\&\f(CW\*(C`reworked_verify\*(C'\fR
.RE
.RS 4
.RE
.ie n .IP """\-\-registry""" 4
.el .IP "\f(CW\-\-registry\fR" 4
.IX Item "--registry"
.Vb 1
\&  sqitch target add devwidgets \-\-registry meta
.Ve
.Sp
Specifies the name of the database object where Sqitch's state and history
data is stored. Typically a schema name (as in PostgreSQL and Oracle) or a
database name (as in SQLite and MySQL). Defaults to \f(CW\*(C`sqitch\*(C'\fR.
.ie n .IP """\-\-client""" 4
.el .IP "\f(CW\-\-client\fR" 4
.IX Item "--client"
.Vb 1
\&  sqitch target add devwidgets \-\-client /usr/local/pgsql/bin/psql
.Ve
.Sp
Specifies the path to the command-line client for the target. Defaults to a
client in the current path named appropriately for the engine specified by the
\&\s-1URI.\s0
.ie n .IP """\-s""" 4
.el .IP "\f(CW\-s\fR" 4
.IX Item "-s"
.PD 0
.ie n .IP """\-\-set""" 4
.el .IP "\f(CW\-\-set\fR" 4
.IX Item "--set"
.PD
Set a variable name and value for use by the database engine client, if it
supports variables. The format must be \f(CW\*(C`name=value\*(C'\fR, e.g.,
\&\f(CW\*(C`\-\-set defuser=\*(AqHomer Simpson\*(Aq\*(C'\fR.
.RE
.RS 4
.RE
.SH "Actions"
.IX Header "Actions"
With no arguments, shows a list of existing targets. Several actions are
available to perform operations on the targets.
.ie n .SS """add"""
.el .SS "\f(CWadd\fP"
.IX Subsection "add"
Add a target named \f(CW\*(C`<name>\*(C'\fR for the database at \f(CW\*(C`<uri>\*(C'\fR. The
\&\f(CW\*(C`\-\-set\*(C'\fR option specifies target-specific properties. A new plan file and new
script script directories will be created if they don't already exist.
.ie n .SS """alter"""
.el .SS "\f(CWalter\fP"
.IX Subsection "alter"
Alter target named \f(CW\*(C`<name>\*(C'\fR. The \f(CW\*(C`\-\-set\*(C'\fR option specifies
engine-specific properties to set. New script script directories will be
created if they don't already exist.
.ie n .SS """remove"", ""rm"""
.el .SS "\f(CWremove\fP, \f(CWrm\fP"
.IX Subsection "remove, rm"
Remove the target named \f(CW\*(C`<name>\*(C'\fR. The plan file and script directories
will not be affected.
.ie n .SS """rename"""
.el .SS "\f(CWrename\fP"
.IX Subsection "rename"
Rename the target named \f(CW\*(C`<old>\*(C'\fR to \f(CW\*(C`<new>\*(C'\fR.
.ie n .SS """show"""
.el .SS "\f(CWshow\fP"
.IX Subsection "show"
Gives some information about the target \f(CW\*(C`<name>\*(C'\fR, including the
associated properties. Specify multiple target names to see information for
each.
.SH "Configuration Variables"
.IX Header "Configuration Variables"
The targets are stored in the configuration file, but the command itself
currently relies on no configuration variables.
.SH "Sqitch"
.IX Header "Sqitch"
Part of the sqitch suite.