sqitch-init(3pm)

📦
version 1.6.1 · 6 versions
, in ubuntu stonking

✨ NAME ✨

sqitch-init — the lil command that spins up a brand new Sqitch project, bestie 💖

🎀 SYNOPSIS 🎀

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

🦋 DESCRIPTION 🦋

Okay so this command creates a brand new Sqitch project, and honestly it's giving starter-pack energy: you get a sqitch.conf file, a sqitch.plan file, and the deploy, revert, and verify subdirectories. That's the whole vibe. 🌸

And here's the iconic part: running sqitch init in an existing project is safe. It literally will not overwrite things that are already there. No cap. Your stuff stays your stuff. 💅

💜 OPTIONS 💜

  • --uri — optional URI you can associate with the project, like:
sqitch init widgets --uri https://github.com/me/wigets

If you pass it, the URI gets written to the project plan and it's used for added uniqueness in hashed object IDs. It also prevents the deployment of another project with the same name but a different URI. So yeah, it's a whole identity check situation. 🔥

  • --engine — specifies the default database engine to use in the project:
sqitch init widgets --engine pg

Supported engines, bestie, and there are so many:

  • --top-dir — specifies the top directory to use for the project. Typically it contains the deployment plan file and the change script directories:
sqitch init widgets --top-dir sql
  • --plan-file, -f — specifies the path to the deployment plan file. Defaults to $top_dir/sqitch.plan:
sqitch init widgets --plan-file my.plan
  • --extension — specifies the file name extension to use for change script file names. Defaults to sql:
sqitch init widgets --extension ddl
  • --dir — sets the path to a script directory. May be specified multiple times. Supported keys are:
sqitch init widgets --dir deploy=dep --dir revert=rev --dir verify=tst
  • deploy
  • revert
  • verify
  • reworked
  • reworked_deploy
  • reworked_revert
  • reworked_verify
sqitch init widgets --target db:pg:widgets
  • --registry — 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:
sqitch init widgets --registry meta
  • --client — 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:
sqitch init widgets --client /usr/local/pgsql/bin/psql

🌈 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, and here's the full rundown, no skips:

  • --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. Fr fr, you do not want to be typing that every single time. 😭

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. Iconic, honestly — it's like a little menu of possibilities. 🍓

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

okay that's the whole page bestie, you ate that 💅✨ this was sqitch-init(3pm), pulled from perl v5.40.1, dated 2026-07-26 — go make a project, you've got this 🎀🦋

📦 where this page comes from