PD-4610: --defaults-file global parameter

liquibase · Sep 26, 2024 · beb34fb · beb34fb
1 parent 62c35e2
commit beb34fb
Show file tree

Hide file tree

Showing 7 changed files with 38 additions and 9 deletions.
diff --git a/Content/Z_Resources/Snippets/text/parameter-syntax.flsnp b/Content/Z_Resources/Snippets/text/parameter-syntax.flsnp
@@ -16,8 +16,7 @@
             </thead>
             <tbody>
                 <tr>
-                    <td><a href="../../../concepts/connections/creating-config-properties.html"><MadCap:variable name="General.Liquibase" /> properties file</a>
-                    </td>
+                    <td><a href="../../../concepts/connections/creating-config-properties.html"><MadCap:variable name="General.Liquibase" /> properties file</a> (defaults file)</td>
                     <td><pre xml:space="preserve"><code class="language-text">liquibase.<MadCap:variable name="parameters-global-command.case-camel" />: <MadCap:variable name="parameters-global-command.value-type" /></code></pre>
                     </td>
                 </tr>

diff --git a/Content/concepts/connections/creating-config-properties.html b/Content/concepts/connections/creating-config-properties.html
@@ -15,7 +15,7 @@ <h2 id="creating-the-file">Creating a <code><MadCap:variable name="General.liqui
         <p><MadCap:variable name="General.Liquibase" /> comes <b>preinstalled</b> with example <code><MadCap:variable name="General.liquiPropFile"></MadCap:variable></code> files in the <code>$LIQUIBASE_HOME/examples/&lt;sql|xml|yaml|json&gt;</code> directories.</p>
         <p>You can easily create a new <MadCap:variable name="General.Liquibase" /> project containing a <code><MadCap:variable name="General.liquiPropFile" /></code> file by running the <MadCap:xref href="../../commands/init/project.htm">init project</MadCap:xref> command.</p>
         <p>You can also manually create a new text file in your project <MadCap:variable name="General.Liquibase" /> directory and name it <code><MadCap:variable name="General.liquiPropFile" /></code>.</p>
-        <p class="note" MadCap:autonum="&lt;b&gt;Note: &lt;/b&gt;">The file can be named something other than <code><MadCap:variable name="General.liquiPropFile" /></code> and reside in a different directory by using the <code>--defaults-file</code> attribute every time you run a <MadCap:variable name="General.Liquibase" /> command.
+        <p class="note" MadCap:autonum="&lt;b&gt;Note: &lt;/b&gt;">The file can be named something other than <code><MadCap:variable name="General.liquiPropFile" /></code> and reside in a different directory by using the <code>--<MadCap:xref href="../../parameters/defaults-file.htm">defaults-file</MadCap:xref></code> parameter every time you run a <MadCap:variable name="General.Liquibase" /> command.
 For more information, see <MadCap:xref href="../../parameters/working-with-command-parameters.htm">Working with Command Parameters</MadCap:xref>.</p>
         <h2 id="liquibaseproperties-file-example">Example properties file</h2>
         <p>The following example <code><MadCap:variable name="General.liquiPropFile" /></code> file works for an Oracle database:</p><pre xml:space="preserve"><code class="language-text" data-lang="text">changelogFile: ../path/to/file/dbchangelog.xml

diff --git a/Content/parameters/defaults-file.htm b/Content/parameters/defaults-file.htm
@@ -0,0 +1,27 @@
+<?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/parameters/defaults-file.html" />
+        <meta name="description" content="Reference information and use cases for the defaults-file parameter. The defaults-file global parameter is a case-sensitive string that specifies the filepath Liquibase uses for the file containing configuration properties to apply." />
+        <meta name="viewport" content="width=device-width, initial-scale=1" />
+    </head>
+    <body>
+        <h1><code>defaults-file</code>
+        </h1>
+        <p>The <code class="language-text">--defaults-file</code> global parameter is a case-sensitive string that specifies the filepath <MadCap:variable name="General.Liquibase" /> uses for the file containing configuration properties to apply. By default, the value of this parameter is <code class="language-text">liquibase.properties</code>.</p>
+        <h2>Uses</h2>
+        <p>If you want to use the default <code class="language-text">liquibase.properties</code> file to store your configurations, you don't have to specify this parameter.</p>
+        <p>However, you may want to have multiple defaults files containing different sets of properties or your organization may have a custom naming pattern for configuration files. In these cases, you can use <code class="language-text">--defaults-file</code> to set a custom name for the file containing your <MadCap:variable name="General.Liquibase" /> properties. You can also use the parameter to specify  a remote file location for your <MadCap:variable name="General.Liquibase" /> properties in <a href="../liquibase-pro/remote-files/s3.htm">Amazon S3</a>.</p>
+        <p>For more information on the parameters you need to specify to run <MadCap:variable name="General.Liquibase" /> commands, see <MadCap:xref href="../concepts/connections/creating-config-properties.html">Create and Configure a [%=General.liquiPropFile%] File</MadCap:xref>.</p>
+        <MadCap:snippetBlock src="../Z_Resources/Snippets/text/parameter-syntax.flsnp" MadCap:snippetVariables="parameters-global-command.case-camel:defaultsFile,;parameters-global-command.command-name:update,;parameters-global-command.case-envar:DEFAULTS_FILE,;parameters-global-command.case-kebab:defaults-file,;parameters-global-command.value-type:&lt;string&gt;," />
+        <h2>Related links</h2>
+        <ul>
+            <li>
+                <MadCap:xref href="../concepts/connections/creating-config-properties.html">Create and Configure a [%=General.liquiPropFile%] File</MadCap:xref>
+            </li>
+            <li>
+                <MadCap:xref href="../start/tutorials/home.html">[%=General.Liquibase%] Database Tutorials</MadCap:xref>
+            </li>
+        </ul>
+    </body>
+</html>
diff --git a/Content/parameters/home.htm b/Content/parameters/home.htm
@@ -188,7 +188,7 @@ <h3>General</h3>
 LIQUIBASE_DEFAULTS_FILE</code></pre>
                     </td>
                     <td>String</td>
-                    <td>Specifies the file with default <MadCap:variable name="General.Liquibase" /> properties. <b>Default: <code><MadCap:variable name="General.liquiPropFile"></MadCap:variable></code></b>.</td>
+                    <td>Specifies the file with default <MadCap:variable name="General.Liquibase" /> properties. <b>Default: <code><MadCap:variable name="General.liquiPropFile" /></code></b>. See <MadCap:xref href="defaults-file.htm">defaults-file</MadCap:xref>.</td>
                 </tr>
                 <tr>
                     <td><pre xml:space="preserve"><code class="language-text">--diff-column-order

diff --git a/Content/parameters/working-with-command-parameters.htm b/Content/parameters/working-with-command-parameters.htm
@@ -11,8 +11,8 @@ <h1 class="Print">Working with Command Parameters</h1>
         <h2>Locations</h2>
         <p>Command parameters are specified as either of the following types:</p>
         <ul>
-            <li><b>Global parameters</b> provide a way to change an overall default behavior.  Specified <i>before</i> the command,  global parameters are neither part of nor specific to a particular command. Examples include <code>log-level</code> and <code>catalog-name</code>.</li>
-            <li><b>Command parameters</b> specify command settings and are sometimes required for a particular command. Examples of command settings include <code>changelog-file</code>, <code>password</code>, <code>username</code>, and <code>reference-url</code>. Specify command parameters <i>after</i> the command.</li>
+            <li><b>Global parameters</b> provide a way to change an overall default behavior.  Specified <i>before</i> the command,  global parameters are neither part of nor specific to a particular command. Examples include <code>--log-level</code> and <code>--catalog-name</code>.</li>
+            <li><b>Command parameters</b> specify command settings and are sometimes required for a particular command. Examples of command settings include <code>--changelog-file</code>, <code>--password</code>, <code>--username</code>, and <code>--reference-url</code>. Specify command parameters <i>after</i> the command.</li>
         </ul>
         <p>The following example shows the appropriate positioning of global and command parameters with respect to the command.</p><pre xml:space="preserve"><code class="language-text">liquibase &lt;global parameters&gt; &lt;command&gt; &lt;command parameters&gt;</code></pre>
         <!--<p><MadCap:variable name="General.Liquibase" /> parses additional arguments as command arguments but does not support the <i>positional argument</i> style in which unnamed arguments follow the command. For example, <MadCap:variable name="General.Liquibase" /> supports <code>git pull - -remote=origin</code> but not <code>git pull origin</code>.</p>-->
@@ -42,7 +42,7 @@ <h2>Configuration hierarchy</h2>
                 <MadCap:dropDownHotspot><MadCap:variable name="General.Liquibase" /> properties file</MadCap:dropDownHotspot>
             </MadCap:dropDownHead>
             <MadCap:dropDownBody>
-                <p>To avoid specifying options repeatedly on the command line, create a <MadCap:variable name="General.Liquibase" /> properties file that contains default values. By default, <MadCap:variable name="General.Liquibase" /> searches the current working directory for a file named <code><MadCap:variable name="General.liquiPropFile" /></code>, but you can specify an alternate location with the <code>--defaults-file</code> parameter.</p>
+                <p>To avoid specifying options repeatedly on the command line, create a <MadCap:variable name="General.Liquibase" /> properties file that contains default values. By default, <MadCap:variable name="General.Liquibase" /> searches the current working directory for a file named <code><MadCap:variable name="General.liquiPropFile" /></code>, but you can specify an alternate location with the <code>--<MadCap:xref href="defaults-file.htm">defaults-file</MadCap:xref></code> parameter.</p>
                 <p>For more information, see <MadCap:xref href="../concepts/connections/creating-config-properties.html">Create and Configure a [%=General.liquiPropFile%] File</MadCap:xref>.</p>
             </MadCap:dropDownBody>
         </MadCap:dropDown>

diff --git a/Content/workflows/liquibase-community/using-liquibase-and-docker.htm b/Content/workflows/liquibase-community/using-liquibase-and-docker.htm
@@ -112,7 +112,7 @@ <h3>Example</h3>
 --changelog-file=com/example/changelogs/root.changelog.xml</code></pre>
         <p>To generate a new <MadCap:variable name="General.changelog" /> file at this location, run:</p><pre xml:space="preserve"><code class="language-text">docker run --rm -v c:\projects\my-project\src\main\resources:/liquibase/changelog liquibase generate-changelog --changelog-file=changelog/com/example/changelogs/root.changelog.xml</code></pre>
         <h2>Configuration files</h2>
-        <p>If you use a <MadCap:variable name="General.Liquibase" /> properties file (defaults file) like <code><MadCap:variable name="General.liquiPropFile" /></code> to specify <MadCap:variable name="General.Param/Attribute" />s instead of passing them on the command line, include it in your <MadCap:variable name="General.changelog" /> volume mount and reference it when running commands.</p>
+        <p>If you use a <a href="../../concepts/connections/creating-config-properties.html"><MadCap:variable name="General.Liquibase" /> properties file</a> (defaults file) like <code><MadCap:variable name="General.liquiPropFile" /></code> to specify <MadCap:variable name="General.Param/Attribute" />s instead of passing them on the command line, include it in your <MadCap:variable name="General.changelog" /> volume mount and reference it when running commands.</p>
         <p>When you specify a custom <MadCap:variable name="General.Liquibase" /> properties file, ensure you include <code>searchPath=/liquibase/changelog</code> so that <MadCap:variable name="General.Liquibase" /> can continue looking for your <MadCap:variable name="General.changelog" /> files there.</p>
         <h3>Example</h3>
         <p>If you have a local <code>c:\projects\my-project\src\main\resources\liquibase.properties</code> file, where <code><MadCap:variable name="General.liquiPropFile" /></code> represents the <MadCap:variable name="General.Liquibase" /> properties file, run the following command:</p><pre xml:space="preserve"><code class="language-text">docker run --rm -v c:\projects\my-project\src\main\resources:/liquibase/changelog liquibase
@@ -150,7 +150,7 @@ <h3>Properties file</h3>
 username: &lt;USERNAME&gt;
 password: &lt;PASSWORD&gt;
 licenseKey=&lt;PASTE LB PRO LICENSE KEY HERE&gt;</code></pre>
-        <p>Use the <code>--defaults-file</code> argument to evoke the <code>liquibase.docker.properties</code> file when running commands in the CLI:</p><pre xml:space="preserve"><code class="language-text">docker run --rm -v &lt;PATH TO CHANGELOG DIR&gt;:/liquibase/changelog liquibase/--defaults-file=/liquibase/changelog/liquibase.docker.properties update</code></pre>
+        <p>Use the <code>--<MadCap:xref href="../../parameters/defaults-file.htm">defaults-file</MadCap:xref></code> parameter to invoke the <code>liquibase.docker.properties</code> file when running commands in the CLI:</p><pre xml:space="preserve"><code class="language-text">docker run --rm -v &lt;PATH TO CHANGELOG DIR&gt;:/liquibase/changelog liquibase/--defaults-file=/liquibase/changelog/liquibase.docker.properties update</code></pre>
         <h3>Using <MadCap:variable name="General.Liquibase" /> and PostgreSQL with Docker</h3>
         <p>When you start a PostgreSQL database using <code>docker run postgres</code>, the command looks at the local system to see if the PostgreSQL Docker container already exists. If the container doesn’t exist, the command will refer to Docker Hub and download it.</p>
         <p>To run PostgreSQL and <MadCap:variable name="General.Liquibase" />, your <MadCap:variable name="General.Liquibase" /> <MadCap:variable name="General.changelog" /> needs to be accessible to the Docker container. Mount the directory that includes the <MadCap:variable name="General.changelog" /> file with the <code>-v</code> option:</p><pre xml:space="preserve"><code class="language-text">docker run -v /home/changelog:/liquibase/changelog liquibase 

diff --git a/Project/TOCs/TOC.fltoc b/Project/TOCs/TOC.fltoc
@@ -825,6 +825,9 @@
     <TocEntry
       Title="[%=System.LinkedTitle%]"
       Link="/Content/parameters/ddl-lock-timeout.htm" xmlns:MadCap="http://www.madcapsoftware.com/Schemas/MadCap.xsd" />
+    <TocEntry
+      Title="[%=System.LinkedTitle%]"
+      Link="/Content/parameters/defaults-file.htm" xmlns:MadCap="http://www.madcapsoftware.com/Schemas/MadCap.xsd" />
     <TocEntry
       Title="[%=System.LinkedHeader%]"
       Link="/Content/parameters/diff-column-order.htm"></TocEntry>