Name

       sqitch-rework - Rework a database change

Synopsis

         sqitch  rework [options] [<dependency-options>] name

Description

       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.

Options

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

Examples

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

Configuration Variables

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

Sqitch

       Part of the sqitch suite.

perl v5.38.2                                       2024-02-08                                 sqitch-rework(3pm)