sqitch-rework - Rework a database change
sqitch rework [options] [<dependency-options>] name
This command allows for the reworking of an existing database
change. It is best used only under the following circumstances:
- There are production deployments, so that you cannot revert to before the
change, modify it, and then re-deploy. Just reverting, modifying, and
re-deploying is the thing to do while developing the database, but once it
has been released and deployed to production, you must not change previous
change scripts.
- The modifications will be idempotent
<https://en.wikipedia.org/wiki/Idempotence>. In other words, either
the earlier instance of the change or the new, reworked instance can be
run any number of times, and the outcome of each will be the same. They
must not break each other in case one needs to deploy and revert
changes.
- A tag must have been applied to the plan since the previous instance of
the change. This is required so that Sqitch can disambiguate the two
instances of the change. It's a good idea to always tag a release anyway.
If you haven't, see sqitch-tag.
If all of these hold, then feel free to rework an existing
change.
In effect, reworking a change is similar to adding one. However,
rather than writing new files for the change, the
"rework" command copies the files for the
existing change. The new files are named with the tag that comes between the
changes, and serves as the file for the original change. This leaves you
free to edit the existing files.
By default, the "rework" command
will rework the change in the default plan and the scripts to any top
directories for that plan, as defined by the core configuration and
command-line options. This works well for projects in which there is a
single plan with separate top directories for each engine, for example. Pass
the "--all" option to have it iterate over
all known plans and top directories (as specified for engines and targets)
and rework the change to them all. Of course, the a change by that name must
exist in all the plans of the reworking will fail.
To specify which plans to in which to rework the change, pass the
target, engine, or plan file names to tag as arguments. Use
"--change" to disambiguate the and change
name from the other parameters if necessary (or preferable). See
"Examples" for examples.
- "-c"
- "--change"
- "--change-name"
- The name of the change to rework. The name can be specified with or
without this option, but the option can be useful for disambiguating the
change name from other arguments.
- "-r"
- "--requires"
- Name of a change that is required by the new change. May be specified
multiple times. See sqitchchanges for the various ways in which changes
can be specified.
- "-x"
- "--conflicts"
- Name of a change that conflicts with the new change. May be specified
multiple times. See sqitchchanges for the various ways in which changes
can be specified.
- "-a"
- "--all"
- Rework the change in all plans in the project. Cannot be mixed with
target, engine, or plan file name arguments; doing so will result in an
error. Useful for multi-plan projects in which changes should be kept in
sync. Overrides the value of the
"add.all" configuration; use
"--no-all" to override a true
"add.all" configuration.
- "-n"
- "--note"
- A brief note describing the purpose of the reworking. The note will be
attached to the change as a comment. Multiple invocations will be
concatenated together as separate paragraphs.
For you Git folks out there,
"-m" also works.
- "-e"
- "--edit"
- "--open-editor"
- Open the generated change scripts in an editor.
- "--no-edit"
- "--no-open-editor"
- Do not open the change scripts in an editor. Useful when
"rework.open_editor" is true.
- "--plan-file"
- "-f"
- Path to the deployment plan file. Overrides target, engine, and core
configuration values. Defaults to
$top_dir/sqitch.plan.
Rework a change in a project and be prompted for a note.
sqitch rework widgets
Rework a change and specify the note.
sqitch rework sprockets --note 'Reworks the sprockets view.'
Rework a change that requires the
"users" change from earlier in the
plan.
sqitch rework contacts --requires users -n 'Reworks the contacts view.'
Rework a change that requires multiple changes, including the
change named "extract" from a completely
different Sqitch project named
"utilities":
sqitch rework coffee -r users -r utilities:extract -n 'Mmmmm...coffee!'
Rework a change only to the plan used by the
"vertica" engine in a project:
sqitch rework --change logs vertica -n 'Reworks the logs view in Vertica.'
Rework a change in two plans in a project, and generate the
scripts only for those plans:
sqitch rework -a coolfunctions sqlite.plan pg.plan -n 'Reworks functions.'
- "rework.all"
- Rework the change to all the plans in the project. Useful for multi-plan
projects in which changes should be kept in sync. May be overridden by
"--all",
"--no-all", or target, engine, and plan
file name arguments.
- "rework.open_editor"
- Boolean indicating if the rework command should spawn an editor after
generating change scripts. When true, equivalent to passing
"--edit". Defaults off.
Part of the sqitch suite.