/ 
App-Sqitch-v1.4.1
River stage one • 3 direct dependents • 3 total dependents
/ sqitch-init

Name

sqitch-init - Create a new Sqitch project

Synopsis

sqitch init <project>
sqitch init <project> --uri <uri>

Description

This command creates an new Sqitch project -- basically a sqitch.conf file, a sqitch.plan file, and deploy, revert, and verify subdirectories.

Running sqitch init in an existing project is safe. It will not overwrite things that are already there.

Options

--uri
sqitch init widgets --uri https://github.com/me/wigets

Optional URI to associate with the project. If present, the URI will be written to the project plan and used for added uniqueness in hashed object IDs, as well as to prevent the deployment of another project with the same name but different URI.

--engine
sqitch init widgets --engine pg

Specifies the default database engine to use in the project. Supported engines include:

--top-dir
sqitch init widgets --top-dir sql

Specifies the top directory to use for the project. Typically contains the deployment plan file and the change script directories.

--plan-file
-f
sqitch init widgets --plan-file my.plan

Specifies the path to the deployment plan file. Defaults to $top_dir/sqitch.plan.

--extension
sqitch init widgets --extension ddl

Specifies the file name extension to use for change script file names. Defaults to sql.

--dir
sqitch init widgets --dir deploy=dep --dir revert=rev --dir verify=tst

Sets the path to a script directory. May be specified multiple times. Supported keys are:

  • deploy

  • revert

  • verify

  • reworked

  • reworked_deploy

  • reworked_revert

  • reworked_verify

--target
sqitch init widgets --target db:pg:widgets

Specifies the name or URI of the default target database. If specified as a name, the default URI for the target will be db:$engine:.

--registry
sqitch init widgets --registry meta

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 sqitch.

--client
sqitch init widgets --client /usr/local/pgsql/bin/psql

Specifies the path to the command-line client for the database engine. Defaults to a client in the current path named appropriately for the specified engine.

Configuration

The most important thing sqitch init does is create the project plan file, sqitch.conf. The options determine what gets written to the file:

--engine

Sets the core.engine configuration variable.

--top-dir

Sets the core.top_dir configuration variable.

--plan-file
-f

Sets the core.plan_file configuration variable.

--extension

Sets the core.extension configuration variable.

--dir

Sets the following configuration variables:

  • deploy sets core.deploy_dir

  • revert sets core.revert_dir

  • verify sets core.verify_dir

  • reworked sets core.reworked_dir

  • reworked_deploy sets core.reworked_deploy_dir

  • reworked_deploy sets core.reworked_revert_dir

  • reworked_deploy sets core.reworked_verify_dir

--target

Sets the engine.$engine.target configuration variable if --engine is also passed and, if it's a target name, target.$target.uri

--registry

Sets the engine.$engine.registry configuration variable if --engine is also passed.

--client

Sets the engine.$engine.client configuration variable if --engine is also passed.

-s
--set

Set a variable name and value for use by the database engine client, if it supports variables. The format must be name=value, e.g., --set defuser='Homer Simpson'. Variables are set in core.variables.

As a general rule, you likely won't need any of these options except for --engine, since many commands need to know what engine to use, and specifying it on the command-line forever after would be annoying.

These variables will only be written if their corresponding options are specified. Otherwise, core options get written as comments with user or system configuration settings, or, failing any values from those locations, from their default values. If no defaults are specified, they will still be written, commented out, with a bar = and no value. This allows one to know what sorts of things are available to edit.

Examples

Start a new Sqitch project named "quack" using the SQLite engine, setting the top directory for the project to sqlite:

sqitch init --engine sqlite --top-dir sqlite quack

Start a new Sqitch project named "bey" using the PostgreSQL engine, setting the top directory to postgres, script extension to ddl, reworked directory to reworked and a version-specific client:

sqitch init --engine  pg \
            --top-dir postgres \
            --client  /opt/pgsql-9.1/bin/psql \
            --extension ddl --dir reworked=reworked \
            bey

See Also

sqitch-configuration

Describes how Sqitch hierarchical engine and target configuration works.

sqitch-engine

Command to manage database engine configuration.

sqitch-target

Command to manage target database configuration.

sqitch-config

Command to manage all Sqitch configuration.

Sqitch

Part of the sqitch suite.