Use the validateRollback option in deployPackager.properties to specify how to test your rollback scripts.
- none - Do not test rollback scripts.
- withCompare - Test rollback scripts and their effect. During packaging, take a snapshot of the REF database to use for comparing database states to validate the rollback script. If the test fails, packager continues and shows a WARNING message in the log.
- withoutCompare - Test rollback scripts only to see if they run. Does not test their effects. If the test fails, packager exits with an ERROR.
Project-Level Requirement for All SQL Scripts to Have Rollback Scripts
If you specify either of the options to validate rollback scripts, then you must provide -rollback files for all scripts in the project. The requirement starts when you enable the option. You do not need to provide rollback files for SQL scripts that have already been packaged and deployed.
Pre-Validation Checks
Before starting the validation process, packager checks the scripts to determine whether they meet validation requirements.
Rollbacks for Non-rerunnable SQL Scripts
Non-rerunnable scripts are for code that can be run only once. The SQL scripts are archived after packaging.
The packager checks for the following conditions when it is determining how to validate rollback:
- The script produces one changeset. A rollback script is provided. This method is used in some cases where DDL and DML are packaged together.
- The script produces several changesets. A rollback script is provided. This method is typically used for DDL.
Rollbacks for Rerunnable SQL Scripts
Rerunnable scripts are for code that can be run more than once, typically stored logic code (function, procedure, package, packagebody, view). These files are not archived. They are left in place and versioned for each time they are packaged.
Validation consists of checking that a prior version of the deployed changeset exists.
- Version of the SQL script must be greater than 1.
- The previous version must have been deployed.
Dummy Rollback Scripts for Idempotent SQL Scripts
In special cases there are scripts that cannot have a rollback script. To satisfy the project-level requirement for all scripts to have rollback scripts, you can create a blank or comments-only rollback script for them.
Such scripts are called idempotent, which means that they can be run multiple times with the same result.
Examples:
- delete column from table
- if an object exists, delete it and then create it; else create it.
Validation Process with Compare
Packager uses the following high-level process when validating with validateRollback=withCompare.
- Snapshot the REF database for comparison purposes (snapshot #1)
- Deploy changes using SQL scripts provided (not logged in audit database)
- Snapshot the REF database again (snapshot #2)
- Test rollback (not logged in audit database)
- Snapshot the REF database again (snapshot #3)
- Deploy using generated changesets (not logged in audit database)
- Snapshot the REF database one final time (snapshot #4)
- Compare snapshot #1 and snapshot #3 to ensure rollback works properly
- Compare snapshot #2 and snapshot #4 to ensure that script packaging works properly.
Error Conditions for the Validation Process
Based on the validation process, you get messages in the packager report for the following conditions.
| Test Rollback | Test Deploy | Snapshot Differences Detected | Packager Action |
|---|---|---|---|
| Success | Success | No | Continue |
| Success | Success | Yes | Continue |
| Success | Fail | n/a | Exit with error |
| Success | Fail | Yes | Exit with error |
| Fail | n/a | n/a | Exit with error |
Note
If differences between the snapshots are detected but the test rollback and test deploy succeed, packager gives you messages but continues. Check the messages and the scripts to be sure that the differences are acceptable and understood.
Fixing Failed Rollback Scripts
If validation fails for the rollback script, then packaging stops without creating changesets.
Correct the rollback script and try packaging again:
- Correct the rollback script
- Check the changes into source control
- Re-run the packaging job.
Replacing Scripts When Rollback Validation is In Effect
You may need to make changes to a SQL script and its rollback script after they are packaged and deployed.
When you make changes in that scenario, you should replace both the SQL script and its rollback script at the same time.
| Scenario | Validate the rollback? | WARNING |
|---|---|---|
| New SQL script and its new rollback script | YES | None |
| Replace and repackage both SQL script and its rollback script | YES | None |
| Replace a SQL script but not its rollback script | YES, BUT see Warning. | The previous rollback script is pulled forward. Validation (withCompare) may fail if the new SQL script has changes that are not accounted for by the previous rollback script. Validation (withoutCompare) will succeed but the rollback script may not account for new changes. |
| Replace rollback script but not its SQL Script. for a change set that was previously created | NO | Do not attempt this. The rollback cannot be validated. Validation is skipped but the new rollback script is deployed. If the rollback script is incorrect, you do not find out until you run a rollback operation. |
Rollback Files and Developer Workflow Files
Do not use both -rollback files and Developer Workflow files (-cleanup, -replace, -ignore) for the same SQL script. In general, Developer Workflow functionality is intended for SQL scripts that do not have -rollback files.
See /wiki/spaces/DDD/pages/80445460