How To: Abandon changes

Many times, you would need to abandon changes in lower environments and prevent them from deploying into higher environments. For example, a script got packaged which drops a column. This will result in loss of data in PROD database. Such a change is not desirable to be released to PROD. In such a case, you would use Datical label to abandon such a change.

• Since you will be using labels, such as "release/1.0.0" to assign changes to a release, you can use a label such as "abandoned" to indicate changes that are abandoned. When changes are deployed as part of a release, you would deploy using a label such as "release/1.0.0 AND !abandoned" (notice the !) so that none of the abandoned changes make it to a release.
  • Remove Abandoned Changes: It should be noted that this will require you to fix your lower environments and modify (or remove) changes in order to keep your environments consistent.
    • You can do this by packaging and deploying the fix script on the environments where the original changes were deployed.
  • Use Abandoned Changes Later: If the change needs no further modification and it is a candidate for a future release, then that change can sit in the lower environments until such time that it is slotted for a particular release at which point you will need to remove these labels: "abandoned" label and earlier release label ("release/1.0.0"). And apply the correct release label (e.g. "release/2.0.0").
    • Here is a simple example of how a label could be applied to changes that are getting abandoned:

Steps described below allow you to fix your database environments while still leveraging your automation framework. 

It is undesirable to make manual changes to your database environments that are managed by automation.

Step-by-step guide

For the purpose of the document, we will assume that the Datical project has the following pipeline and that our faulty script "temp_table.sql" has been deployed up through the QA environment. We now need to abandon this script so that it no longer deploys to STAGE and PROD environments. We also need to bring a "fix" script to fix changes that were made to REF1, DEV and QA environments.

1. Instruct Datical to abandon the script "temp_table.sql". This will require adding the label "abandoned" to all changesets that generate from this script. You can perform this task in automation, however, the user will need to provide the script name as a parameter. In your automation system (Jenkins, Bamboo, UrbanCode Build, etc.), create a new job which will perform following operations:
   1. Checkout Datical project from your source control (Git, TFS, SVN)
   2. Run "hammer addLabels" command. This command takes two arguments:
      1. lookupChangesets - This is the script name which you want to abandon, e.g., "temp_table.sql". This will be the user provided argument.
      2. labels - This is the abandon label you want to give to your changesets, e.g., "abandoned"
         1. Once you agree on what naming convention to use to abandon changes, this argument can be programmatic (e.g., "release/1.0.0-abandoned") or hard-coded (e.g., "abandoned").
   3. Commit and push Datical project back into source control
   4. Here is the complete sample script with some additional code for before and after status:
      1. Perform SCM operation so that you can check-in your changes back into SCM ("git branch --set-upstream-to ...")
      2. "hammer findChangeSets" used to show the label status on a set of changesets before and after applying the "addLabels" command (note: use of REM and environment variables "%<variableName>%" is specific to Windows):

      3. Perform SCM operation to commit and push the code and provide a relevant commit message ("git commit ..." and "git push ...")

         Abandon Changes Windows Expand source

         echo -------------------------------
         set PATH=%PATH%;C:\apps\Datical\repl
         
         git clone http://user@bitbucket.datical.net/scm/bbu/ddb.git
         cd ddb
         
         git branch --set-upstream-to=origin/master master 
         git status
         
         hammer findChangeSets --lookupChangesets="%lookupChangesets%"
         hammer addLabels --lookupChangesets="%lookupChangesets%" --labels="%labels%"
         hammer findChangeSets --lookupChangesets="%lookupChangesets%,%labels%"
         
         REM add steps to commit Datical project into Git.
         echo commit new changes back into Bitbucket
         git add -A
         git commit -m "Automations:AbandonScript-%lookupChangesets% - build number=%BUILD_NUMBER%"
         git push -u origin master
         echo -------------------------------

         Abandon Changes Linux Expand source

         echo "-------------------------------"
         export PATH=$PATH%:\opt\DaticalDB\repl
         
         git clone http://user@bitbucket.datical.net/scm/bbu/ddb.git
         cd ddb
         
         git branch --set-upstream-to=origin/master master 
         git status
         
         hammer findChangeSets --lookupChangesets="%lookupChangesets"
         hammer addLabels --lookupChangesets="$lookupChangesets" --labels="$labels"
         hammer findChangeSets --lookupChangesets="${lookupChangesets},${labels}"
         
         # add steps to commit Datical project into Git.
         echo "commit new changes back into Bitbucket"
         git add -A
         git commit -m "Automations:AbandonScript-$lookupChangesets - build number=${BUILD_NUMBER}"
         git push -u origin master
         echo "-------------------------------"

      4. Here is how your automation job would report your abandoned changesets:

         1. Notice that one changeset was identified with lookupChangets="temp_table.sql". Later, the same changeset was identified when lookupChangesets="temp_table.sql,abandoned"

            a

            hammer findChangeSets --lookupChangesets="temp_table.sql"
            
            _______________________
            | Change Set ID| Author|
            |======================|
            | Temp_Table   | amalik|
            
            hammer addLabels --lookupChangesets="temp_table.sql" --labels="abandoned"
            
            Updating labels for change set Temp_Table
            hammer findChangeSets --lookupChangesets="temp_table.sql,abandoned"
            
            _______________________
            | Change Set ID| Author|
            |======================|
            | Temp_Table   | amalik|

      5. Here is how the abandoned changeset looks in the Datical GUI:

         1. 
   5. Now that the "abandoned" label has been added, make sure to create a new artifact version.
      1. When you use your deployment automation tool you will use your newly created versioned artifact to deploy database changes.
   6. Make sure that you alway deploy using "!abandoned" label (notice the "!") with your deploy automation tool. Here is a sample deploy command you would use:
      1. hammer deploy STAGE --labels "release/1.0.0 AND !abandoned"
      2. hammer deploy PROD --labels "release/1.0.0 AND !abandoned"


For Liquibase Enterprise users, continue with these steps

1. Setup a directory structure in order to bring a "fix" script to fix changes made by the abandoned script.
   

   1. Each directory (data_dml, ddl, ddl_direct, function, package, packagebody, procedure, view, sql, and sql_direct) will have subdirectories indicating how far in the pipeline do deploy changes. See the table below:

      "sql_code"	"data_dml" "ddl" "function" "package" "packagebody" "procedure" "sql_direct"	All the way to PROD	"REF1-only"	"until-DEV"	"until-QA"	"until-STAGE"
      Top-level directory for sql repository:	Each directory contains identical set of subdirectories - each referring to how far the scripts in those subdirectories will be deployed.	Any script that does not get checked into one of the subdirectories (REF1-only, until-DEV, etc.) will be eligible to be deployed in all database environments in the Datical pipeline, including PROD. In the screenshot below, the script "create AAA_TESTA4.sql" will be deployed to all environments. The resulting changesets will automatically pickup all labels and other flags described in the adjacent metadata.properties file.	metadata.properties file in REF1-only subdirectory contains context flag as: contexts=REF1	metadata.properties file in until-DEV subdirectory contains context flag as: contexts=REF1,DEV	metadata.properties file in until-QA subdirectory contains context flag as: contexts=REF1,DEV,QA	metadata.properties file in until-STAGE subdirectory contains context flag as: contexts=REF1,DEV,QA,STAGE

   2. Download this zip file which has this directory structure predefined, along with metadata.properties files in each subdirectory.
2. Bring your fix script. Use the sql repository's directory structure (as described above) to identify which environments will receive the "fix" script.
   
   1. For example, if the abandoned DDL script got deployed until the QA environment, then commit the fix script into the "ddl" > "until-QA" subdirectory. 
3. Datical's Deployment Packager will pick up the fix script from this directory and realize the list of contexts described in adjacent metadata.properties file, i.e. contexts=REF1,DEV,QA. Therefore, changesets resulting from the fix script will be eligible to deploy in those three environments only. 

Related articles

• Page:
  How To: Remove abandonded changes from Liquibase Enterprise and lower environments
• Page:
  How To: Negate changes
• Page:
  How To: Abandon a Single Changeset from a Script
• Page:
  How To: Leverage the "metadata.properties" file
• Page:
  How To: Unabandon changes