Skip to content

Commit

Permalink
PD-2968: dbms
Browse files Browse the repository at this point in the history
  • Loading branch information
adrian-velonis1 committed Dec 16, 2024
1 parent cf75a7d commit 2bbb620
Show file tree
Hide file tree
Showing 7 changed files with 142 additions and 5 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,6 @@
<head>
</head>
<body>
<p>Specifies which database type<MadCap:conditionalText MadCap:conditions="parameter-dbms.multi-value">(s)</MadCap:conditionalText> a <MadCap:variable name="General.changeset" /> is to be used for. See valid database type names on <MadCap:xref href="../../../../../start/tutorials/home.html">[%=General.Liquibase%] Database Tutorials</MadCap:xref>. <MadCap:conditionalText MadCap:conditions="parameter-dbms.multi-value">Separate multiple databases with commas. Specify that a <MadCap:variable name="General.changeset" /> is not applicable to a particular database type by prefixing with <code>!</code>.</MadCap:conditionalText> The keywords <code>all</code> and <code>none</code> are also available.</p>
<p>Specifies which database type<MadCap:conditionalText MadCap:conditions="parameter-dbms.multi-value">(s)</MadCap:conditionalText> a <MadCap:variable name="General.changeset" /> is to be used for. See valid database type names on <code><MadCap:xref href="../../../../../concepts/changelogs/attributes/dbms.htm">dbms</MadCap:xref></code>. <MadCap:conditionalText MadCap:conditions="parameter-dbms.multi-value">Separate multiple databases with commas. Specify that a <MadCap:variable name="General.changeset" /> is not applicable to a particular database type by prefixing with <code>!</code>.</MadCap:conditionalText> The keywords <code>all</code> and <code>none</code> are also available.</p>
</body>
</html>
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,7 @@
<td>Optional</td>
</tr>
<tr>
<td><code>dbms</code>
<td><code><MadCap:xref href="../../../concepts/changelogs/attributes/dbms.htm">dbms</MadCap:xref></code>
</td>
<td>
<MadCap:snippetBlock src="../def/attributes/change-types/change-type-dbms.flsnp" />
Expand Down
2 changes: 1 addition & 1 deletion Content/concepts/changelogs/attributes/contexts.html
Original file line number Diff line number Diff line change
Expand Up @@ -130,7 +130,7 @@ <h2 id="multi-dbms-changelogs">Multi-DBMS <MadCap:variable name="General.changel
&lt;column name="id" type="int"/&gt;
&lt;/createTable&gt;
&lt;/changeSet&gt;</code></pre>
<p>Instead, <b>it is a best practice to use the <code>dbms</code> tag to differentiate <MadCap:variable name="General.changeset" />s by database type</b>, and then run <code>liquibase update</code> in your command line. This is a clearer use of contexts and decreases the possibility of errors. You can use <code>context</code> and <code>dbms</code> on the same <MadCap:variable name="General.changeset" />, but only <code>dbms</code> should refer to your database type. For example:</p><pre xml:space="preserve"><code class="language-xml">&lt;changeSet id="1-lawful-good" author="adrian" dbms="postgres"&gt;
<p>Instead, <b>it is a best practice to use the <code><MadCap:xref href="dbms.htm">dbms</MadCap:xref></code> tag to differentiate <MadCap:variable name="General.changeset" />s by database type</b>, and then run <code>liquibase update</code> in your command line. This is a clearer use of contexts and decreases the possibility of errors. You can use <code>context</code> and <code>dbms</code> on the same <MadCap:variable name="General.changeset" />, but only <code>dbms</code> should refer to your database type. For example:</p><pre xml:space="preserve"><code class="language-xml">&lt;changeSet id="1-lawful-good" author="adrian" dbms="postgres"&gt;
&lt;createTable tableName="my_postgres_table"&gt;
&lt;column name="id" type="int"/&gt;
&lt;/createTable&gt;
Expand Down
134 changes: 134 additions & 0 deletions Content/concepts/changelogs/attributes/dbms.htm
Original file line number Diff line number Diff line change
@@ -0,0 +1,134 @@
<?xml version="1.0" encoding="utf-8"?>
<html xmlns:MadCap="http://www.madcapsoftware.com/Schemas/MadCap.xsd" MadCap:searchable="False">
<head><title><MadCap:variable name="Heading.Level1" /></title>
<link rel="canonical" href="https://docs.liquibase.com/concepts/changelogs/attributes/dbms.html" />
<meta name="description" content="The ignore attribute is a string that specifies which database Liquibase should run a changeset on." />
<meta name="viewport" content="width=device-width, initial-scale=1" />
</head>
<body>
<h1><code>dbms</code>
</h1>
<p>The <code class="language-text">dbms</code>&#160;<MadCap:variable name="General.Param/Attribute" /> is a string that specifies which database <MadCap:variable name="General.Liquibase" /> should run a <MadCap:variable name="General.changeset" /> on. <code class="language-text">dbms</code> accepts "short names"&#160;of database management systems. Valid values are:</p>
<ul>
<li><code class="language-text">all</code>:&#160;allow this change to deploy to all supported databases</li>
<li><code class="language-text">none</code>:&#160;allow this change to deploy nowhere</li>
<li><code class="language-text">aerospike</code>:&#160;<a href="https://github.com/liquibase/liquibase-aerospike">Aerospike</a></li>
<li><code class="language-text">asany</code>: <a href="https://contribute.liquibase.com/extensions-integrations/directory/database-tutorials/sap-sql-anywhere/">SAP SQL Anywhere</a></li>
<li><code class="language-text">bigquery</code>:&#160;<a href="../../../start/tutorials/google-bigquery/home.htm">Google BigQuery</a></li>
<li><code class="language-text">cassandra</code>:&#160;<a href="https://contribute.liquibase.com/extensions-integrations/directory/database-tutorials/cassandra/apache-cassandra/">Apache Cassandra</a></li>
<li><code class="language-text">cloudspanner</code>: <a href="https://contribute.liquibase.com/extensions-integrations/directory/database-tutorials/cloud-spanner/">Spanner</a></li>
<li><code class="language-text">cockroachdb</code>: <a href="https://contribute.liquibase.com/extensions-integrations/directory/database-tutorials/cockroachdb/">CockroachDB</a></li>
<li><code class="language-text">cosmosdb</code>:&#160;<a href="https://contribute.liquibase.com/extensions-integrations/directory/database-tutorials/cosmosdb/">Azure Cosmos DB</a></li>
<li><code class="language-text">databricks</code>:&#160;<a href="../../../start/tutorials/databricks/home.htm">Databricks</a></li>
<li><code class="language-text">db2</code>:&#160;<a href="../../../start/tutorials/ibm-db2-luw.htm">IBM&#160;DB2 on LUW</a></li>
<li><code class="language-text">db2i</code>: <a href="https://contribute.liquibase.com/extensions-integrations/directory/database-tutorials/db2-iseries/">IBM&#160;DB2 on i</a></li>
<li><code class="language-text">db2z</code>: <a href="../../../start/tutorials/ibm-db2-zos.htm">IBM DB2 on z/OS</a></li>
<li><code class="language-text">derby</code>:&#160;<a href="https://contribute.liquibase.com/extensions-integrations/directory/database-tutorials/apache-derby/">Apache Derby</a></li>
<li><code class="language-text">dynamodb</code>:&#160;<a href="../../../start/tutorials/amazon-dynamodb-pro/home.htm">Amazon DynamoDB</a></li>
<li><code class="language-text">edb</code>:&#160;<a href="../../../start/tutorials/enterprisedb.htm">EnterpriseDB</a></li>
<li><code class="language-text">firebird</code>: <a href="https://contribute.liquibase.com/extensions-integrations/directory/database-tutorials/firebird/">Firebird</a></li>
<li><code class="language-text">hana</code>:&#160;<a href="https://contribute.liquibase.com/extensions-integrations/directory/database-tutorials/sap-hana/">SAP&#160;HANA</a></li>
<li><code class="language-text">h2</code>: <a href="https://contribute.liquibase.com/extensions-integrations/directory/database-tutorials/h2/">H2 Database&#160;Engine</a></li>
<li><code class="language-text">hsqldb</code>: <a href="https://contribute.liquibase.com/extensions-integrations/directory/database-tutorials/hsqldb/">HyperSQL&#160;Database</a></li>
<li><code class="language-text">informix</code>: <a href="https://contribute.liquibase.com/extensions-integrations/directory/database-tutorials/informix/">Informix</a></li>
<li><code class="language-text">ingres</code>: Ingres Database</li>
<li><code class="language-text">mariadb</code>: <a href="../../../start/tutorials/mariadb.html">MariaDB</a></li>
<li><code class="language-text">maxdb</code>:&#160;<a href="https://contribute.liquibase.com/extensions-integrations/directory/database-tutorials/maxdb/">SAP&#160;MaxDB</a></li>
<li><code class="language-text">mongodb</code>:&#160;<a href="../../../start/tutorials/mongodb-pro/home.htm">MongoDB</a></li>
<li><code class="language-text">mssql</code>:&#160;<a href="../../../start/tutorials/ms-sql-server.html">Microsoft SQL&#160;Server</a></li>
<li><code class="language-text">mysql</code>:&#160;<a href="../../../start/tutorials/mysql.html">MySQL</a></li>
<li><code class="language-text">neo4j</code>:&#160;<a href="https://www.liquibase.com/databases/neo4j-graph-database">Neo4J&#160;Graph Database</a></li>
<li><code class="language-text">oracle</code>:&#160;<a href="../../../start/tutorials/oracle.html">Oracle</a></li>
<li><code class="language-text">postgresql</code>:&#160;<a href="../../../start/tutorials/postgresql/home.html">PostgreSQL</a></li>
<li><code class="language-text">redshift</code>:&#160;<a href="../../../start/tutorials/amazon-redshift.htm">Amazon&#160;Redshift</a></li>
<li><code class="language-text">snowflake</code>: <a href="../../../start/tutorials/snowflake.htm">Snowflake</a></li>
<li><code class="language-text">sqlite</code>:&#160;<a href="https://contribute.liquibase.com/extensions-integrations/directory/database-tutorials/sqlite/">SQLite</a></li>
<li><code class="language-text">sybase</code>: <a href="https://contribute.liquibase.com/extensions-integrations/directory/database-tutorials/sap-adaptive-server-enterprise-sap-ase/">SAP Adaptive Server</a></li>
<li><code class="language-text">teradata</code>:&#160;<a href="https://contribute.liquibase.com/extensions-integrations/directory/database-tutorials/teradata/">Teradata</a></li>
<li><code class="language-text">vertica</code>:&#160;<a href="https://contribute.liquibase.com/extensions-integrations/directory/database-tutorials/vertica/">Vertica</a></li>
<li><code class="language-text">yugabytedb</code>:&#160;<a href="https://contribute.liquibase.com/extensions-integrations/directory/database-tutorials/yugabytedb/">YugabyteDB</a></li>
</ul>
<p>Separate multiple values with commas. Specify that a <MadCap:variable name="General.changeset"></MadCap:variable> is not applicable to a particular database type by prefixing with <code>!</code> The default value is <code class="language-text">all</code>.</p>
<h2>Uses</h2>
<p>If you're deploying a <MadCap:variable name="General.changelog" /> to multiple database management systems (DBMSs), you may want to ensure that a certain <MadCap:variable name="General.changeset" /> is only deployed to one type of database. For example, you might want to deploy some stored logic only to your PostgreSQL&#160;databases because the logic uses a keyword that doesn't exist on your Oracle databases. You can specify </p>
<p class="note" MadCap:autonum="&lt;b&gt;Note: &lt;/b&gt;"><MadCap:variable name="General.Liquibase" /> dynamically uses the database connection URL to determine what database you're currently connected to, not the value of <code class="language-text">dbms</code>.</p>
<h2>Syntax</h2>
<div class="js-tabs">
<ul class="js-tablist" data-hx="h3">
<li class="js-tablist__item"><a href="#sql_example" id="label_sql_example" class="js-tablist__link">SQL example</a>
</li>
<li class="js-tablist__item"><a href="#json_example" id="label_json_example" class="js-tablist__link">JSON example</a>
</li>
<li class="js-tablist__item"><a href="#yaml_example" id="label_yaml_example" class="js-tablist__link">YAML example</a>
</li>
<li class="js-tablist__item"><a href="#xml_example" id="label_xml_example" class="js-tablist__link">XML example</a>
</li>
</ul>
<div id="sql_example" class="js-tabcontent"><pre xml:space="preserve"><code class="language-sql">--liquibase formatted sql

--changeset your.name:1 dbms:postgresql,oracle
create table person (
name varchar(255)
);</code></pre>
</div>
<div id="json_example" class="js-tabcontent"><pre xml:space="preserve"><code class="language-json">{
"databaseChangeLog":[
{
"changeSet": {
"author": "your.name",
"id": "1",
"dbms": "postgresql,oracle",
"changes": [
{
"createTable": {
"tableName": "person",
"columns": [
{
"column": {
"name": "name",
"type": "varchar(255)"
}
}
]
}
}
]
}
}
}</code></pre>
</div>
<div id="yaml_example" class="js-tabcontent"><pre xml:space="preserve"><code class="language-yaml">databaseChangeLog:
- changeSet:
author: your.name
id: 1
dbms: postgresql,oracle
changes:
- createTable:
tableName: person
columns:
- column:
name: name
type: varchar(255)</code></pre>
</div>
<div id="xml_example" class="js-tabcontent"><pre xml:space="preserve"><code class="language-xml"><MadCap:snippetText src="../../../Z_Resources/Snippets/code/liquibase-xsd-xml-changelog-closed.flsnp" />

&lt;changeSet author="your.name" id="1" dbms="postgresql,oracle"&gt;
&lt;createTable tableName="person"&gt;
&lt;column name="name" type="varchar(255)"/&gt;
&lt;/createTable&gt;
&lt;/changeSet&gt;

&lt;/databaseChangeLog&gt;</code></pre>
</div>
</div>
<h2>Related links</h2>
<ul>
<li>
<MadCap:xref href="../preconditions.html">Preconditions</MadCap:xref>
</li>
<li>
<MadCap:xref href="../../../start/tutorials/home.html">[%=General.Liquibase%] Database Tutorials</MadCap:xref>
</li>
</ul>
</body>
</html>
2 changes: 1 addition & 1 deletion Content/concepts/changelogs/attributes/fail-on-error.htm
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ <h1><code>failOnError</code>
<h2>Uses</h2>
<p>Normally, if you run the <MadCap:xref href="../../../commands/update/update.html">update</MadCap:xref> command and <MadCap:variable name="General.Liquibase" /> detects an error in a <MadCap:variable name="General.changeset" />, the migration fails. However, if you set <code>failOnError</code> to <code>false</code> on a <MadCap:variable name="General.changeset" />, <MadCap:variable name="General.Liquibase" /> suppresses all error caching for that <MadCap:variable name="General.changeset" />, so the migration continues as though there were no error.</p>
<p>Some databases contain complex logic or objects added outside of <MadCap:variable name="General.Liquibase" /> that may cause certain <MadCap:variable name="General.changeset" />s to fail. To ensure your migrations succeed, it is a best practice to write one or more <a href="../preconditions.html">preconditions</a> that control the execution of these <MadCap:variable name="General.changeset" />s. However, if the precondition(s) would be very complicated to write, it may be more convenient to set <code>failOnError</code> to <code>false</code> on the affected <MadCap:variable name="General.changeset" />s.</p>
<p>If you have a <MadCap:variable name="General.changeset" /> that only runs successfully with certain databases or environments, it is also possible to set <code>failOnError</code> on it as a "quick fix" to control its execution. However, instead of relying on <code>failOnError</code>, it is a best practice to use the <code>dbms</code> <MadCap:variable name="General.Param/Attribute" /> to control whether a <MadCap:variable name="General.changeset" /> applies to different databases. Similarly, it is a best practice to use <a href="contexts.html">contexts</a> or <a href="labels.html">labels</a> to control <MadCap:variable name="General.changeset" /> execution across multiple environments, such as <code>test</code> versus <code>dev</code>.</p>
<p>If you have a <MadCap:variable name="General.changeset" /> that only runs successfully with certain databases or environments, it is also possible to set <code>failOnError</code> on it as a "quick fix" to control its execution. However, instead of relying on <code>failOnError</code>, it is a best practice to use the <code><MadCap:xref href="dbms.htm">dbms</MadCap:xref></code>&#160;<MadCap:variable name="General.Param/Attribute" /> to control whether a <MadCap:variable name="General.changeset" /> applies to different databases. Similarly, it is a best practice to use <a href="contexts.html">contexts</a> or <a href="labels.html">labels</a> to control <MadCap:variable name="General.changeset" /> execution across multiple environments, such as <code>test</code> versus <code>dev</code>.</p>
<p class="tip" MadCap:autonum="&lt;b&gt;Tip: &lt;/b&gt;">If you use <code>failOnError</code> frequently, consider whether there are any underlying issues with your database architecture that you can address instead.</p>
<h3>Using <code>failOnError</code> with <code>--rollback-on-error</code> (<MadCap:variable name="General.LBPro" />)</h3>
<p>You can use the <code>failOnError</code>&#160;<MadCap:variable name="General.changeset" />&#160;<MadCap:variable name="General.Param/Attribute" /> with the <code>update</code> command argument <code><a href="../../../commands/update/update.html#command">--rollback-on-error</a></code>. The following table displays the outcomes of running <code>update</code> on a <MadCap:variable name="General.changeset" /> that contains an error based on each possible configuration.</p>
Expand Down
2 changes: 1 addition & 1 deletion Content/concepts/changelogs/preconditions.html
Original file line number Diff line number Diff line change
Expand Up @@ -685,7 +685,7 @@ <h3><code>dbms</code>
<td><code>type</code>
</td>
<td>
<p>The type of database expected. Multiple dbms values can be specified using comma-separated values.</p>
<p>The type of database expected. Multiple dbms values can be specified using comma-separated values. For a list of valid values, see <code><MadCap:xref href="attributes/dbms.htm">dbms</MadCap:xref></code>.</p>
</td>
<td><b>Required</b>
</td>
Expand Down
3 changes: 3 additions & 0 deletions Project/TOCs/TOC.fltoc
Original file line number Diff line number Diff line change
Expand Up @@ -399,6 +399,9 @@
<TocEntry
Title="[%=System.LinkedHeader%]"
Link="/Content/concepts/changelogs/attributes/contexts.html"></TocEntry>
<TocEntry
Title="[%=System.LinkedTitle%]"
Link="/Content/concepts/changelogs/attributes/dbms.htm" xmlns:MadCap="http://www.madcapsoftware.com/Schemas/MadCap.xsd" />
<TocEntry
Title="[%=System.LinkedHeader%]"
Link="/Content/concepts/changelogs/attributes/fail-on-error.htm" xmlns:MadCap="http://www.madcapsoftware.com/Schemas/MadCap.xsd" />
Expand Down

0 comments on commit 2bbb620

Please sign in to comment.