1=head1 Name 2 3sqitch-init - Create a new Sqitch project 4 5=head1 Synopsis 6 7 sqitch init <project> 8 sqitch init <project> --uri <uri> 9 10=head1 Description 11 12This command creates an new Sqitch project -- basically a F<sqitch.conf> file, 13a F<sqitch.plan> file, and F<deploy>, F<revert>, and F<verify> subdirectories. 14 15Running sqitch init in an existing project is safe. It will not overwrite 16things that are already there. 17 18=head1 Options 19 20=over 21 22=item C<--uri> 23 24 sqitch init widgets --uri https://github.com/me/wigets 25 26Optional URI to associate with the project. If present, the URI will be 27written to the project plan and used for added uniqueness in hashed object 28IDs. 29 30=item C<--engine> 31 32 sqitch init widgets --engine pg 33 34Specifies the default database engine to use in the project. Supported engines 35include: 36 37=over 38 39=item * C<pg> - L<PostgreSQL|http://postgresql.org/> and L<Postgres-XC|http://sourceforge.net/> 40 41=item * C<sqlite> - L<SQLite|http://sqlite.org/> 42 43=item * C<oracle> - L<Oracle|http://www.oracle.com/us/products/database/> 44 45=item * C<mysql> - L<MySQL|http://dev.mysql.com/> and L<MariaDB|https://mariadb.com/> 46 47=item * C<firebird> - L<Firebird|http://www.firebirdsql.org/> 48 49=item * C<vertica> - L<Vertica|https://my.vertica.com/> 50 51=back 52 53=item C<--top-dir> 54 55 sqitch init widgets --top-dir sql 56 57Specifies the top directory to use for the project. Typically contains the 58deployment plan file and the change script directories. 59 60=item C<--plan-file> 61 62 sqitch init widgets --plan-file my.plan 63 64Specifies the path to the deployment plan file. Defaults to 65C<$top_dir/sqitch.plan>. 66 67=item C<--extension> 68 69 sqitch init widgets --extension ddl 70 71Specifies the file name extension to use for change script file names. 72Defaults to C<sql>. 73 74=item C<--dir> 75 76 sqitch init widgets --dir deploy=dep --dir revert=rev --dir verify=tst 77 78Sets the path to a script directory. May be specified multiple times. 79Supported keys are: 80 81=over 82 83=item * C<deploy> 84 85=item * C<revert> 86 87=item * C<verify> 88 89=item * C<reworked> 90 91=item * C<reworked_deploy> 92 93=item * C<reworked_revert> 94 95=item * C<reworked_verify> 96 97=back 98 99=item C<--target> 100 101 sqitch init widgets --target db:pg:widgets 102 103Specifies the name or L<URI|https://github.com/theory/uri-db/> of the default 104target database. If specified as a name, the default URI for the target will 105be C<db:$engine:>. 106 107=item C<--registry> 108 109 sqitch init widgets --registry meta 110 111Specifies the name of the database object where Sqitch's state and history 112data is stored. Typically a schema name (as in PostgreSQL and Oracle) or a 113database name (as in SQLite and MySQL). Defaults to C<sqitch>. 114 115=item C<--client> 116 117 sqitch init widgets --client /usr/local/pgsql/bin/psql 118 119Specifies the path to the command-line client for the database engine. 120Defaults to a client in the current path named appropriately for the specified 121engine. 122 123=back 124 125=head1 Configuration 126 127The most important thing C<sqitch init> does is create the project plan file, 128F<sqitch.conf>. The options determine what gets written to the file: 129 130=over 131 132=item C<--engine> 133 134Sets the C<core.engine> configuration variable. 135 136=item C<--top-dir> 137 138Sets the C<core.top_dir> configuration variable. 139 140=item C<--plan-file> 141 142Sets the C<core.plan_file> configuration variable. 143 144=item C<--extension> 145 146Sets the C<core.extension> configuration variable. 147 148=item C<--dir> 149 150Sets the following configuration variables: 151 152=over 153 154=item * C<deploy> sets C<core.deploy_dir> 155 156=item * C<revert> sets C<core.revert_dir> 157 158=item * C<verify> sets C<core.verify_dir> 159 160=item * C<reworked> sets C<core.reworked_dir> 161 162=item * C<reworked_deplpoy> sets C<core.reworked_deploy_dir> 163 164=item * C<reworked_deplpoy> sets C<core.reworked_revert_dir> 165 166=item * C<reworked_deplpoy> sets C<core.reworked_verify_dir> 167 168=back 169 170=item C<--target> 171 172Sets the C<engine.$engine.target> configuration variable if C<--engine> is 173also passed and, if it's a target name, C<target.$target.uri> 174 175=item C<--registry> 176 177Sets the C<engine.$engine.registry> configuration variable if C<--engine> is also 178passed. 179 180=item C<--client> 181 182Sets the C<engine.$engine.client> configuration variable if C<--engine> is 183also passed. 184 185=back 186 187As a general rule, you likely won't need any of these options except for 188C<--engine>, since many commands need to know what engine to use, and 189specifying it on the command-line forever after would be annoying. 190 191These variables will only be written if their corresponding options are 192specified. Otherwise, core options get written as comments with user or system 193configuration settings, or, failing any values from those locations, from 194their default values. If no defaults are specified, they will still be 195written, commented out, with a bar C<=> and no value. This allows one to know 196what sorts of things are available to edit. 197 198=head1 Examples 199 200Start a new Sqitch project using the SQLite engine, setting the top directory 201for the project to F<sqlite>: 202 203 sqitch init --engine sqlite --top-dir sqlite 204 205Start a new Sqitch project using the PostgreSQL engine, setting the top 206directory to F<postgres>, script extension to C<ddl>, reworked directory to 207C<reworked> and a version-specific client: 208 209 sqitch init --engine pg \ 210 --top-dir postgres \ 211 --client /opt/pgsql-9.1/bin/psql \ 212 --extension ddl --dir reworked=reworked 213 214=head1 See Also 215 216=over 217 218=item L<sqitch-configuration> 219 220Describes how Sqitch hierarchical engine and target configuration works. 221 222=item L<sqitch-engine> 223 224Command to manage database engine configuration. 225 226=item L<sqitch-target> 227 228Command to manage target database configuration. 229 230=item L<sqitch-config> 231 232Command to manage all Sqitch configuration. 233 234=back 235 236=head1 Sqitch 237 238Part of the L<sqitch> suite. 239