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