From 2bbb6209ce6528abf5a81ed87b1bac40ad0fc76b Mon Sep 17 00:00:00 2001 From: Adrian Velonis Date: Mon, 16 Dec 2024 16:10:46 -0600 Subject: [PATCH] PD-2968: dbms --- .../change-types/change-type-dbms.flsnp | 2 +- .../text/changelog-changeset-attributes.flsnp | 2 +- .../changelogs/attributes/contexts.html | 2 +- .../concepts/changelogs/attributes/dbms.htm | 134 ++++++++++++++++++ .../changelogs/attributes/fail-on-error.htm | 2 +- .../concepts/changelogs/preconditions.html | 2 +- Project/TOCs/TOC.fltoc | 3 + 7 files changed, 142 insertions(+), 5 deletions(-) create mode 100644 Content/concepts/changelogs/attributes/dbms.htm diff --git a/Content/Z_Resources/Snippets/def/attributes/change-types/change-type-dbms.flsnp b/Content/Z_Resources/Snippets/def/attributes/change-types/change-type-dbms.flsnp index c30e0def0..a46cdef05 100644 --- a/Content/Z_Resources/Snippets/def/attributes/change-types/change-type-dbms.flsnp +++ b/Content/Z_Resources/Snippets/def/attributes/change-types/change-type-dbms.flsnp @@ -3,6 +3,6 @@ -

Specifies which database type(s) a is to be used for. See valid database type names on [%=General.Liquibase%] Database Tutorials. Separate multiple databases with commas. Specify that a is not applicable to a particular database type by prefixing with !. The keywords all and none are also available.

+

Specifies which database type(s) a is to be used for. See valid database type names on dbms. Separate multiple databases with commas. Specify that a is not applicable to a particular database type by prefixing with !. The keywords all and none are also available.

\ No newline at end of file diff --git a/Content/Z_Resources/Snippets/text/changelog-changeset-attributes.flsnp b/Content/Z_Resources/Snippets/text/changelog-changeset-attributes.flsnp index 26ca6399c..ec6e16afe 100644 --- a/Content/Z_Resources/Snippets/text/changelog-changeset-attributes.flsnp +++ b/Content/Z_Resources/Snippets/text/changelog-changeset-attributes.flsnp @@ -49,7 +49,7 @@ Optional - dbms + dbms diff --git a/Content/concepts/changelogs/attributes/contexts.html b/Content/concepts/changelogs/attributes/contexts.html index 5b8c03715..d4b9f3a2b 100644 --- a/Content/concepts/changelogs/attributes/contexts.html +++ b/Content/concepts/changelogs/attributes/contexts.html @@ -130,7 +130,7 @@

Multi-DBMS -

Instead, it is a best practice to use the dbms tag to differentiate s by database type, and then run liquibase update in your command line. This is a clearer use of contexts and decreases the possibility of errors. You can use context and dbms on the same , but only dbms should refer to your database type. For example:

<changeSet  id="1-lawful-good"  author="adrian" dbms="postgres">
+        
Instead, it is a best practice to use the dbms tag to differentiate s by database type, and then run liquibase update in your command line. This is a clearer use of contexts and decreases the possibility of errors. You can use context and dbms on the same , but only dbms should refer to your database type. For example:
<changeSet  id="1-lawful-good"  author="adrian" dbms="postgres">
     <createTable  tableName="my_postgres_table">
         <column  name="id"  type="int"/>
     </createTable>
diff --git a/Content/concepts/changelogs/attributes/dbms.htm b/Content/concepts/changelogs/attributes/dbms.htm
new file mode 100644
index 000000000..5e460529c
--- /dev/null
+++ b/Content/concepts/changelogs/attributes/dbms.htm
@@ -0,0 +1,134 @@
+
+
+    <MadCap:variable name="Heading.Level1" />
+        
+        
+        
+    
+    
+        
dbms
+        

+        
The dbms  is a string that specifies which database  should run a  on. dbms accepts "short names" of database management systems. Valid values are:

+        
+        
Separate multiple values with commas. Specify that a  is not applicable to a particular database type by prefixing with ! The default value is all.

+        
Uses

+        
If you're deploying a  to multiple database management systems (DBMSs), you may want to ensure that a certain  is only deployed to one type of database. For example, you might want to deploy some stored logic only to your PostgreSQL databases because the logic uses a keyword that doesn't exist on your Oracle databases. You can specify 

+        
 dynamically uses the database connection URL to determine what database you're currently connected to, not the value of dbms.

+        
Syntax

+        

+            
+            
--liquibase formatted sql
+
+--changeset your.name:1 dbms:postgresql,oracle
+create table person (
+    name varchar(255)
+);

+            

+            
{
+"databaseChangeLog":[
+  {
+  "changeSet": {
+    "author": "your.name",
+    "id": "1",
+    "dbms": "postgresql,oracle",
+    "changes": [
+      {
+      "createTable": {
+        "tableName": "person",
+        "columns": [
+        {
+        "column": {
+          "name": "name",
+          "type": "varchar(255)"
+                }
+              }
+            ]
+          }
+        }
+      ]
+    }
+  }
+}

+            

+            
databaseChangeLog:
+    -  changeSet:
+        author: your.name
+        id: 1
+        dbms: postgresql,oracle
+        changes:
+        -  createTable:
+            tableName: person
+            columns:
+            -  column:
+                name: name
+                type: varchar(255)

+            

+            

+
+    <changeSet author="your.name" id="1" dbms="postgresql,oracle">
+        <createTable tableName="person">
+            <column name="name" type="varchar(255)"/>
+        </createTable>
+    </changeSet>
+
+</databaseChangeLog>

+            

+        

+        
Related links

+        
    
+            
  • 
+                Preconditions
+            
    • 
+            
  • 
+                [%=General.Liquibase%] Database Tutorials
+            
    • 
+        

+    
+
\ No newline at end of file
diff --git a/Content/concepts/changelogs/attributes/fail-on-error.htm b/Content/concepts/changelogs/attributes/fail-on-error.htm
index 5bd57f68e..b7ae19a01 100644
--- a/Content/concepts/changelogs/attributes/fail-on-error.htm
+++ b/Content/concepts/changelogs/attributes/fail-on-error.htm
@@ -12,7 +12,7 @@ 
failOnError
         
Uses

         
Normally, if you run the update command and  detects an error in a , the migration fails. However, if you set failOnError to false on a ,  suppresses all error caching for that , so the migration continues as though there were no error.

         
Some databases contain complex logic or objects added outside of  that may cause certain s to fail. To ensure your migrations succeed, it is a best practice to write one or more preconditions that control the execution of these s. However,  if the precondition(s) would be very complicated to write, it may be more convenient to set failOnError to false on the affected s.

-        
If you have a  that only runs successfully with certain databases or environments, it is also possible to set failOnError on it as a "quick fix" to control its execution. However, instead of relying on failOnError, it is a best practice to use the dbms  to control whether a  applies to different databases. Similarly, it is a best practice to use contexts or labels to control  execution across multiple environments, such as test versus dev.

+        
If you have a  that only runs successfully with certain databases or environments, it is also possible to set failOnError on it as a "quick fix" to control its execution. However, instead of relying on failOnError, it is a best practice to use the dbms  to control whether a  applies to different databases. Similarly, it is a best practice to use contexts or labels to control  execution across multiple environments, such as test versus dev.

         
If you use failOnError frequently, consider whether there are any underlying issues with your database architecture that you can address instead.

         
Using failOnError with --rollback-on-error ()

         
You can use the failOnError   with the update command argument --rollback-on-error. The following table displays the outcomes of running update on a  that contains an error based on each possible configuration.

diff --git a/Content/concepts/changelogs/preconditions.html b/Content/concepts/changelogs/preconditions.html
index b22449d4b..7ea843edc 100644
--- a/Content/concepts/changelogs/preconditions.html
+++ b/Content/concepts/changelogs/preconditions.html
@@ -685,7 +685,7 @@ 
dbms
                     type
                     
                     
-                        
The type of database expected. Multiple dbms values can be specified using comma-separated values.

+                        
The type of database expected. Multiple dbms values can be specified using comma-separated values. For a list of valid values, see dbms.

                     
                     Required
                     
diff --git a/Project/TOCs/TOC.fltoc b/Project/TOCs/TOC.fltoc
index e847d3b22..d371871fd 100644
--- a/Project/TOCs/TOC.fltoc
+++ b/Project/TOCs/TOC.fltoc
@@ -399,6 +399,9 @@
         
+