Use a replace script to replace a deployed changes with the desired changes. 

Sometimes database changes (changesets) need to be replaced after deployment. This can occur if a change fails testing in a later stage environment.   

The replace capability allows you to deploy a changeset that is specially marked for replacing prior changes.  During processing, the original changeset gets the attribute ignore=true to prevent it from being deployed further. 

See Cleaning Up Deployed Changesets: cleanup. 

Pairing a Replace Script with a Cleanup Script

You commonly need to deploy a cleanup script to undo the changes of the script you want to replace. 

A cleanup script and a replace script can be packaged in the same packaging run. 

Types of Change Eligible for Replace Scripts

Replace scripts work for different types "non-rerunnable" changes:

• DDL folder or packageMethod=CONVERT
• DDL_DIRECT folder or packageMethod=DDL_DIRECT
• DATA_DML folder or packageMethod=DATA_DML
• SQL_DIRECT folder or packageMethod=DIRECT
• SQL folder or packageMethod=SQLFILE
• Liquibase changelogs - replace the changesets packaged from the original changelog with changesets from the replacement changelog.

Cleanup and/or Replace are NOT recommended for stored logic (code: package, packagebody, procedure, function, trigger, view folders).  Use the provided versioning capability with stored logic instead. 

Replacing Changesets

For a file named myscript.sql, create a replace file that contains the code to replace what was deployed before. Use one of the following forms:

myscript-replace.sql

myscript_replace.sql

The file may use any extension (e.g. .sql) or no extension. 

Multiple Replace Changesets

If you need to replace the contents of a replace script, use another replace script with the same -replace name. You do not need to string together multiple replace statements. Liquibase will handle updating the contents of the -replace.

myscript-replace.sql

myscript-replace-replace.sql

Processing

Deployment Packager processes the -replace files during packaging, as follows:

1. Searches the changelog for matching changesets based on filename. Packager will error if there are no matching changesets in the changelog that were previously packaged with the same filename in the same path relative to the root folder. Changesets must match these attributes:
   • origFilePath
   • origFileName
2. Sets ignore=true attribute on all matching changesets (same orgFilePath and origFileName) that pertain to the most recent / highest version 
3. Produces new changeset(s) and positions them in the changelog.immediately following the most recent changeset(s) 
4. Archives the replace file as appropriate.