PD-5174: rollbackSqlFile

liquibase · Oct 9, 2024 · 4e85e42 · 4e85e42
1 parent fbe6565
commit 4e85e42
Show file tree

Hide file tree

Showing 6 changed files with 74 additions and 33 deletions.
diff --git a/Content/Z_Resources/Snippets/code/command-rollback-custom.flsnp b/Content/Z_Resources/Snippets/code/command-rollback-custom.flsnp
@@ -35,10 +35,7 @@ insert into testTable values ('2','The Second', 'Country2')
 rollback delete from testTable where id='1'
 rollback delete from testTable where id='2'
 */</code></pre>
-                <p>In <MadCap:variable name="General.Liquibase" /> 4.26.0 and later, you can also specify rollback SQL&#160;for a <MadCap:variable name="General.changeset" /> in a separate file using the <code>--rollbackSqlFile</code> statement:</p><pre><code class="language-sql">--changeset liquibase-user:1
-DROP PROCEDURE hello_world;
---rollbackSqlFile:release_1.0/rollback_45895.sql</code></pre>
-                <p>For more information, see <MadCap:xref href="../../../concepts/changelogs/sql-format.html">Example Changelogs: SQL Format</MadCap:xref>.</p>
+                <MadCap:snippetBlock src="../text/liquibase-rollback-rollback-sql-file.flsnp" />
             </div>
             <div id="yaml_example_custom_generic" class="js-tabcontent"><pre xml:space="preserve"><code class="language-yaml" data-lang="yaml">databaseChangeLog:
 - changeSet:

diff --git a/Content/Z_Resources/Snippets/text/changelog-changeset-attributes.flsnp b/Content/Z_Resources/Snippets/text/changelog-changeset-attributes.flsnp
@@ -178,6 +178,11 @@
  Specifies SQL statements or <MadCap:variable name="General.changetypes" /> tags that describe how to rollback the <MadCap:variable name="General.changeset" />.
                     For more information, see <MadCap:xref href="../../../workflows/liquibase-community/using-rollback.htm">[%=General.Liquibase%] Rollback Workflow</MadCap:xref> and <MadCap:xref href="../../../workflows/liquibase-community/automatic-custom-rollbacks.htm">Automatic and Custom Rollbacks</MadCap:xref>.</td>
             </tr>
+            <tr>
+                <td><code>rollbackSqlFile</code>
+                </td>
+                <td><b><MadCap:variable name="General.LBPro" /> 4.26.0+.</b> Formatted SQL&#160;only. Lets you specify a SQL&#160;file to roll back rather than an inline SQL statement. For more information, see <MadCap:xref href="../../../concepts/changelogs/sql-format.html">Example Changelogs: SQL Format</MadCap:xref>.</td>
+            </tr>
             <tr>
                 <td><code>validCheckSum</code>
                 </td>

diff --git a/Content/Z_Resources/Snippets/text/liquibase-rollback-rollback-sql-file.flsnp b/Content/Z_Resources/Snippets/text/liquibase-rollback-rollback-sql-file.flsnp
@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="utf-8"?>
+<html xmlns:MadCap="http://www.madcapsoftware.com/Schemas/MadCap.xsd">
+    <body>
+        <p>In <MadCap:variable name="General.Liquibase" /> 4.26.0 and later, you can use a <code>rollbackSqlFile</code> statement to specify rollback SQL&#160;for a <MadCap:variable name="General.changeset" /> in a separate file:</p><pre><code class="language-sql">--changeset liquibase-user:1
+DROP PROCEDURE hello_world;
+--rollbackSqlFile:release_1.0/rollback_45895.sql</code></pre>
+        <p>In your <code>rollbackSqlFile</code> statement, you can specify parameters to change the behavior of your rollback, such as a unique end delimiter. For more information, see <MadCap:xref href="../../../concepts/changelogs/sql-format.html">Example Changelogs: SQL Format</MadCap:xref>.</p>
+    </body>
+</html>
diff --git a/Content/change-types/sql-file.html b/Content/change-types/sql-file.html
@@ -41,7 +41,8 @@ <h2>Examples</h2>
                 </li>
             </ul>
             <div id="sql_example" class="js-tabcontent">
-                <p>Currently, there is no SQL Example for the <code>sqlFile</code>&#160;<MadCap:variable name="General.changetypes" /> because you can just put SQL directly into a SQL formatted <MadCap:variable name="General.changelog" />.</p>
+                <p>There is no implementation for the <code>sqlFile</code>&#160;<MadCap:variable name="General.changetypes" /> because you can just put SQL directly into a SQL formatted <MadCap:variable name="General.changelog" />.</p>
+                <MadCap:snippetBlock src="../Z_Resources/Snippets/text/liquibase-rollback-rollback-sql-file.flsnp" />
             </div>
             <div id="yaml_example" class="js-tabcontent"><pre xml:space="preserve"><code class="language-yaml">databaseChangeLog:
 -  changeSet:

diff --git a/Content/concepts/changelogs/home.html b/Content/concepts/changelogs/home.html
@@ -32,35 +32,16 @@ <h2>File formats</h2>
 changetype name (
     changetype attributes
 );
---other element</code></pre>
-            </MadCap:dropDownBody>
-        </MadCap:dropDown>
-        <MadCap:dropDown>
-            <MadCap:dropDownHead>
-                <MadCap:dropDownHotspot style="font-size: 1.1em;">XML example</MadCap:dropDownHotspot>
-            </MadCap:dropDownHead>
-            <MadCap:dropDownBody>
-                <p>Read more:&#160;<MadCap:xref href="xml-format.html">Example Changelogs: XML Format</MadCap:xref>.</p><pre xml:space="preserve"><code class="language-xml" data-lang="xml">&lt;?xml version="1.0" encoding="UTF-8"?&gt;  
-<MadCap:snippetText src="../../Z_Resources/Snippets/code/liquibase-xsd-xml-changelog-closed.flsnp" />
-
-    &lt;preCondition&gt;
-        &lt;preConditionName  preConditionAttribute="value"&gt;
-    &lt;/preCondition&gt;
-
-    &lt;changeSet  id="value"  author="value"&gt;
-        &lt;changeTypeName  changeTypeAttribute="value"&gt;
-            &lt;nestedElementName  elementAttribute="value"&gt;
-        &lt;/changeTypeName&gt;
-    &lt;/changeSet&gt;
-&lt;/databaseChangeLog&gt;</code></pre>
+--rollback &lt;SQL statement&gt;
+--rollbackSqlFile path:&lt;filepath&gt;</code></pre>
             </MadCap:dropDownBody>
         </MadCap:dropDown>
         <MadCap:dropDown>
             <MadCap:dropDownHead>
                 <MadCap:dropDownHotspot style="font-size: 1.1em;">YAML example</MadCap:dropDownHotspot>
             </MadCap:dropDownHead>
             <MadCap:dropDownBody>
-                <p>Read more:&#160;<MadCap:xref href="yaml-format.html">Example Changelogs:  YAML Format</MadCap:xref>.</p><pre xml:space="preserve"><code class="language-yaml" data-lang="yaml">databaseChangeLog:
+                <p>Read more: <MadCap:xref href="yaml-format.html">Example Changelogs:  YAML Format</MadCap:xref>.</p><pre xml:space="preserve"><code class="language-yaml" data-lang="yaml">databaseChangeLog:
   -  preCondition:
       -  preConditionName:
           preConditionAttribute:  value
@@ -69,6 +50,12 @@ <h2>File formats</h2>
       id:  value
       author:  value
       changes:
+        -  changeTypeName:
+            changeTypeAttribute:  value
+            nestedElementGroup:
+              -  nestedElementName:
+                  nestedElementAttribute:  value
+      rollback:
         -  changeTypeName:
             changeTypeAttribute:  value
             nestedElementGroup:
@@ -81,7 +68,7 @@ <h2>File formats</h2>
                 <MadCap:dropDownHotspot style="font-size: 1.1em;">JSON example</MadCap:dropDownHotspot>
             </MadCap:dropDownHead>
             <MadCap:dropDownBody>
-                <p>Read more:&#160;<MadCap:xref href="json-format.html">Example Changelogs: JSON Format</MadCap:xref>.</p><pre xml:space="preserve"><code class="language-json">{
+                <p>Read more: <MadCap:xref href="json-format.html">Example Changelogs: JSON Format</MadCap:xref>.</p><pre xml:space="preserve"><code class="language-json">{
     "databaseChangeLog": [
       {
         "preCondition": [
@@ -103,19 +90,59 @@ <h2>File formats</h2>
                 "nestedElementGroup": [
                   {
                     "nestedElementName": {
-                      "NestedElementAttribute": "value"
+                      "nestedElementAttribute": "value"
                     }
                   }
                 ]
               }
             }
+          ],
+          "rollback": [
+            {
+              "changeTypeName": {
+                "changeTypeAttribute": "value",
+                "nestedElementGroup": [
+                  {
+                    "nestedElementName": {
+                      "nestedElementAttribute": "value"
+                    }
+                  }
+                ]
+              }
+            } 
           ]
         }
       }
     ]
 }</code></pre>
             </MadCap:dropDownBody>
         </MadCap:dropDown>
+        <MadCap:dropDown>
+            <MadCap:dropDownHead>
+                <MadCap:dropDownHotspot style="font-size: 1.1em;">XML example</MadCap:dropDownHotspot>
+            </MadCap:dropDownHead>
+            <MadCap:dropDownBody>
+                <p>Read more: <MadCap:xref href="xml-format.html">Example Changelogs: XML Format</MadCap:xref>.</p><pre xml:space="preserve"><code class="language-xml" data-lang="xml">&lt;?xml version="1.0" encoding="UTF-8"?&gt;  
+<MadCap:snippetText src="../../Z_Resources/Snippets/code/liquibase-xsd-xml-changelog-closed.flsnp" />
+
+    &lt;preCondition&gt;
+        &lt;preConditionName  preConditionAttribute="value"&gt;
+    &lt;/preCondition&gt;
+
+    &lt;changeSet  id="value"  author="value"&gt;
+        &lt;changeTypeName  changeTypeAttribute="value"&gt;
+            &lt;nestedElementName  elementAttribute="value"&gt;
+        &lt;/changeTypeName&gt;
+
+        &lt;rollback&gt;
+            &lt;changeTypeName  changeTypeAttribute="value"&gt;
+                &lt;nestedElementName  elementAttribute="value"&gt;
+            &lt;/changeTypeName&gt;
+        &lt;/rollback&gt;
+    &lt;/changeSet&gt;
+&lt;/databaseChangeLog&gt;</code></pre>
+            </MadCap:dropDownBody>
+        </MadCap:dropDown>
         <p>For additional formats, see <MadCap:xref href="other-formats.html">Example Changelogs: Other Formats</MadCap:xref>.</p>
         <h2 id="available-attributes">Runtime logic</h2>
         <p>When you run a database update, the <MadCap:variable name="General.Liquibase" /> migrator detects the <MadCap:variable name="General.changelog" /> file type from the file extension and then parses the <MadCap:variable name="General.changelog" /> header. <MadCap:variable name="General.Liquibase" /> checks any global preconditions specified. If any of the global preconditions fail, <MadCap:variable name="General.Liquibase" /> exits with an error message explaining what failed. Preconditions can be typically used for both documenting and enforcing expectations or assumptions. For example, you can specify the DBMS to be run against the <MadCap:variable name="General.changelog" /> or the user you should log in to run changes.</p>

diff --git a/Content/concepts/changelogs/sql-format.html b/Content/concepts/changelogs/sql-format.html
@@ -149,14 +149,16 @@ <h2 id="preconditions">Preconditions</h2>
         <p>Preconditions can be specified for each <MadCap:variable name="General.changeset" />. Currently, only the SQL check precondition is supported.</p><pre><code class="language-sql">--preconditions onFail:HALT onError:HALT
 --precondition-sql-check expectedResult:0 SELECT COUNT(*) FROM my_table</code></pre>
         <h2 id="rollback-actions">Rollback actions</h2>
-        <p><MadCap:variable name="General.changeset" />s may include statements to be applied when rolling back the <MadCap:variable name="General.changeset" />. Rollback statements have the following format:</p><pre><code class="language-sql">--changeset liquibase-user:1
+        <h3>Specify SQL&#160;with <code>rollback</code></h3>
+        <p>Your <MadCap:variable name="General.changeset" />s may include statements to be applied when rolling back the <MadCap:variable name="General.changeset" />. Rollback statements have the following format:</p><pre><code class="language-sql">--changeset liquibase-user:1
 DROP PROCEDURE hello_world;
 --rollback SQL STATEMENT</code></pre>
-        <h4>SQL file</h4>
-        <p>In <MadCap:variable name="General.Liquibase" /> 4.26.0 and later, you can also specify a SQL file to execute in a rollback. This requires a <a href="../../liquibase-pro/license-key.htm"><MadCap:variable name="General.LBPro" /> license key</a>. For example:</p><pre><code class="language-sql">--changeset liquibase-user:1
+        <h3>Specify a SQL&#160;file with <code>rollbackSqlFile</code></h3>
+        <p>In <MadCap:variable name="General.Liquibase" /> 4.26.0 and later, you can use a <code>rollbackSqlFile</code> statement to specify a SQL file to execute in a rollback. A <code>rollbackSqlFile</code> statement in a formatted SQL&#160;<MadCap:variable name="General.changelog" /> behaves the same way as a <code>rollback</code> statement, except that <code>rollbackSqlFile</code> points to a file instead of inline SQL. <code>rollbackSqlFile</code> requires a <a href="../../liquibase-pro/license-key.htm"><MadCap:variable name="General.LBPro" /> license key</a>. For example:</p><pre><code class="language-sql">--changeset liquibase-user:1
 DROP PROCEDURE hello_world;
 --rollbackSqlFile path:release_1.0/rollback_45895.sql</code></pre>
-        <p>This is equivalent to using the <code><MadCap:xref href="../../change-types/sql-file.html">sqlFile</MadCap:xref></code>&#160;<MadCap:variable name="General.changetypes" /> in an XML, YAML, or JSON <MadCap:variable name="General.changelog" />. In your <code>rollbackSqlFile</code> statement, you can specify the following parameters to change the behavior of your rollback:</p>
+        <p>Specifying <code>rollbackSqlFile</code> in a formatted SQL&#160;<MadCap:variable name="General.changelog" /> is equivalent to using the <code><MadCap:xref href="../../change-types/sql-file.html">sqlFile</MadCap:xref></code>&#160;<MadCap:variable name="General.changetypes" /> in an XML, YAML, or JSON <MadCap:variable name="General.changelog" /> to roll back a statement.</p>
+        <p>In your <code>rollbackSqlFile</code> statement, you can specify the following parameters to change the behavior of your rollback:</p>
         <table>
             <thead>
                 <tr>