<?xml version="1.0" encoding="utf-8"?>
<rss version="2.0" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/">
    <channel>
        <title>Atlas Blog</title>
        <link>https://atlasgo.io/faq</link>
        <description>Atlas Blog</description>
        <lastBuildDate>Fri, 20 Nov 2026 20:08:41 GMT</lastBuildDate>
        <docs>https://validator.w3.org/feed/docs/rss2.html</docs>
        <generator>https://github.com/jpmonette/feed</generator>
        <language>en</language>
        <item>
            <title><![CDATA[Installing Atlas on Windows and Setting up PATH]]></title>
            <link>https://atlasgo.io/faq/atlas-on-windows</link>
            <guid>https://atlasgo.io/faq/atlas-on-windows</guid>
            <pubDate>Fri, 20 Nov 2026 20:08:41 GMT</pubDate>
            <description><![CDATA[Learn how to install Atlas CLI on Windows and configure the PATH environment variable to use it from anywhere.]]></description>
            <content:encoded><![CDATA[<h3 class="anchor anchorTargetStickyNavbar_SAay" id="question">Question<a href="https://atlasgo.io/faq/atlas-on-windows#question" class="hash-link" aria-label="Direct link to Question" title="Direct link to Question" translate="no">​</a></h3>
<p>How do I install Atlas on Windows and set up the PATH environment variable so I can run <code>atlas</code> from any directory?</p>
<h3 class="anchor anchorTargetStickyNavbar_SAay" id="answer">Answer<a href="https://atlasgo.io/faq/atlas-on-windows#answer" class="hash-link" aria-label="Direct link to Answer" title="Direct link to Answer" translate="no">​</a></h3>
<p>Installing Atlas on Windows involves two main steps: downloading the binary and adding it to your system's PATH environment variable.</p>
<h4 class="anchor anchorTargetStickyNavbar_SAay" id="step-1-download-atlas-binary">Step 1: Download Atlas Binary<a href="https://atlasgo.io/faq/atlas-on-windows#step-1-download-atlas-binary" class="hash-link" aria-label="Direct link to Step 1: Download Atlas Binary" title="Direct link to Step 1: Download Atlas Binary" translate="no">​</a></h4>
<ol>
<li class="">
<p>Download the latest Atlas binary for Windows from the <a href="https://atlasbinaries.com/atlas/atlas-windows-amd64-latest.exe" target="_blank" rel="noopener noreferrer" class="">official release page</a>.</p>
</li>
<li class="">
<p>Choose a permanent location for the Atlas binary. We recommend creating a dedicated directory such as:</p>
<ul>
<li class=""><code>C:\Program Files\Atlas\</code> (requires admin privileges)</li>
<li class=""><code>C:\atlas\</code> (simpler, no admin needed)</li>
<li class=""><code>%USERPROFILE%\atlas\</code> (user-specific installation)</li>
</ul>
</li>
<li class="">
<p>Move or save the downloaded <code>atlas-windows-amd64-latest.exe</code> file to your chosen directory.</p>
</li>
<li class="">
<p>Rename the file to <code>atlas.exe</code> for convenience (optional but recommended).</p>
</li>
</ol>
<h4 class="anchor anchorTargetStickyNavbar_SAay" id="step-2-add-atlas-to-path">Step 2: Add Atlas to PATH<a href="https://atlasgo.io/faq/atlas-on-windows#step-2-add-atlas-to-path" class="hash-link" aria-label="Direct link to Step 2: Add Atlas to PATH" title="Direct link to Step 2: Add Atlas to PATH" translate="no">​</a></h4>
<p>You can add Atlas to your PATH using either the GUI or PowerShell/Command Prompt.</p>
<p><strong>Method 1: Using Windows GUI</strong></p>
<ol>
<li class="">
<p>Open <strong>System Properties</strong>:</p>
<ul>
<li class="">Press <code>Win + R</code>, type <code>sysdm.cpl</code>, and press Enter</li>
<li class="">Or right-click <strong>This PC</strong> → <strong>Properties</strong> → <strong>Advanced system settings</strong></li>
</ul>
</li>
<li class="">
<p>Click <strong>Environment Variables</strong> at the bottom of the System Properties window.</p>
</li>
<li class="">
<p>In the <strong>User variables</strong> section (for current user only) or <strong>System variables</strong> section (for all users), find and select the <strong>Path</strong> variable.</p>
</li>
<li class="">
<p>Click <strong>Edit</strong>.</p>
</li>
<li class="">
<p>Click <strong>New</strong> and add the directory path where you saved <code>atlas.exe</code> (e.g., <code>C:\atlas</code>).</p>
</li>
<li class="">
<p>Click <strong>OK</strong> on all windows to save the changes.</p>
</li>
<li class="">
<p><strong>Important</strong>: Close and reopen any open Command Prompt or PowerShell windows for the changes to take effect.</p>
</li>
</ol>
<p><strong>Method 2: Using PowerShell</strong></p>
<p>For the current user only:</p>
<div class="language-powershell codeBlockContainer_ZGJx theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockContent_kX1v"><pre tabindex="0" class="prism-code language-powershell codeBlock_TAPP thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_AdAo"><span class="token-line" style="color:#bfc7d5"><span class="token comment" style="color:rgb(105, 112, 152);font-style:italic"># Add to user PATH</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token variable" style="color:rgb(191, 199, 213)">$atlasPath</span><span class="token plain"> = </span><span class="token string" style="color:rgb(195, 232, 141)">"C:\atlas"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token variable" style="color:rgb(191, 199, 213)">$currentPath</span><span class="token plain"> = </span><span class="token namespace" style="color:rgb(178, 204, 214)">[Environment]</span><span class="token plain">::GetEnvironmentVariable</span><span class="token punctuation" style="color:rgb(199, 146, 234)">(</span><span class="token string" style="color:rgb(195, 232, 141)">"Path"</span><span class="token punctuation" style="color:rgb(199, 146, 234)">,</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"User"</span><span class="token punctuation" style="color:rgb(199, 146, 234)">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token namespace" style="color:rgb(178, 204, 214)">[Environment]</span><span class="token plain">::SetEnvironmentVariable</span><span class="token punctuation" style="color:rgb(199, 146, 234)">(</span><span class="token string" style="color:rgb(195, 232, 141)">"Path"</span><span class="token punctuation" style="color:rgb(199, 146, 234)">,</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"</span><span class="token string variable" style="color:rgb(191, 199, 213)">$currentPath</span><span class="token string" style="color:rgb(195, 232, 141)">;</span><span class="token string variable" style="color:rgb(191, 199, 213)">$atlasPath</span><span class="token string" style="color:rgb(195, 232, 141)">"</span><span class="token punctuation" style="color:rgb(199, 146, 234)">,</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"User"</span><span class="token punctuation" style="color:rgb(199, 146, 234)">)</span><br></span></code></pre></div></div>
<p>For all users (requires running PowerShell as Administrator):</p>
<div class="language-powershell codeBlockContainer_ZGJx theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockContent_kX1v"><pre tabindex="0" class="prism-code language-powershell codeBlock_TAPP thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_AdAo"><span class="token-line" style="color:#bfc7d5"><span class="token comment" style="color:rgb(105, 112, 152);font-style:italic"># Add to system PATH (run as Administrator)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token variable" style="color:rgb(191, 199, 213)">$atlasPath</span><span class="token plain"> = </span><span class="token string" style="color:rgb(195, 232, 141)">"C:\atlas"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token variable" style="color:rgb(191, 199, 213)">$currentPath</span><span class="token plain"> = </span><span class="token namespace" style="color:rgb(178, 204, 214)">[Environment]</span><span class="token plain">::GetEnvironmentVariable</span><span class="token punctuation" style="color:rgb(199, 146, 234)">(</span><span class="token string" style="color:rgb(195, 232, 141)">"Path"</span><span class="token punctuation" style="color:rgb(199, 146, 234)">,</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"Machine"</span><span class="token punctuation" style="color:rgb(199, 146, 234)">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token namespace" style="color:rgb(178, 204, 214)">[Environment]</span><span class="token plain">::SetEnvironmentVariable</span><span class="token punctuation" style="color:rgb(199, 146, 234)">(</span><span class="token string" style="color:rgb(195, 232, 141)">"Path"</span><span class="token punctuation" style="color:rgb(199, 146, 234)">,</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"</span><span class="token string variable" style="color:rgb(191, 199, 213)">$currentPath</span><span class="token string" style="color:rgb(195, 232, 141)">;</span><span class="token string variable" style="color:rgb(191, 199, 213)">$atlasPath</span><span class="token string" style="color:rgb(195, 232, 141)">"</span><span class="token punctuation" style="color:rgb(199, 146, 234)">,</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"Machine"</span><span class="token punctuation" style="color:rgb(199, 146, 234)">)</span><br></span></code></pre></div></div>
<p><strong>Method 3: Using Command Prompt</strong></p>
<p>For the current user only:</p>
<div class="language-cmd codeBlockContainer_ZGJx theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockContent_kX1v"><pre tabindex="0" class="prism-code language-cmd codeBlock_TAPP thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_AdAo"><span class="token-line" style="color:#bfc7d5"><span class="token plain">setx PATH "%PATH%;C:\atlas"</span><br></span></code></pre></div></div>
<p>Note: The <code>setx</code> command permanently adds the directory to the user's PATH. You need to close and reopen Command Prompt for changes to take effect.</p>
<h4 class="anchor anchorTargetStickyNavbar_SAay" id="step-3-verify-installation">Step 3: Verify Installation<a href="https://atlasgo.io/faq/atlas-on-windows#step-3-verify-installation" class="hash-link" aria-label="Direct link to Step 3: Verify Installation" title="Direct link to Step 3: Verify Installation" translate="no">​</a></h4>
<p>After adding Atlas to your PATH, verify the installation:</p>
<ol>
<li class="">
<p>Open a <strong>new</strong> Command Prompt or PowerShell window.</p>
</li>
<li class="">
<p>Run the following command:</p>
</li>
</ol>
<div class="language-bash codeBlockContainer_ZGJx theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockContent_kX1v"><pre tabindex="0" class="prism-code language-bash codeBlock_TAPP thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_AdAo"><span class="token-line" style="color:#bfc7d5"><span class="token plain">atlas version</span><br></span></code></pre></div></div>
<p>If the installation was successful, you should see the Atlas version information displayed.</p>
<p>If you get an error like <code>'atlas' is not recognized as an internal or external command</code>, double-check that:</p>
<ul>
<li class="">The directory containing <code>atlas.exe</code> is correctly added to your PATH</li>
<li class="">You've closed and reopened your terminal window</li>
<li class="">The <code>atlas.exe</code> file exists in the specified directory</li>
</ul>
<h4 class="anchor anchorTargetStickyNavbar_SAay" id="troubleshooting">Troubleshooting<a href="https://atlasgo.io/faq/atlas-on-windows#troubleshooting" class="hash-link" aria-label="Direct link to Troubleshooting" title="Direct link to Troubleshooting" translate="no">​</a></h4>
<p><strong>PATH changes not taking effect</strong></p>
<p>If you've added the directory to PATH but the <code>atlas</code> command still isn't recognized:</p>
<ul>
<li class="">Make sure you've closed and reopened all Command Prompt or PowerShell windows</li>
<li class="">Try logging out and logging back in to Windows</li>
<li class="">Verify the PATH was updated by running <code>echo %PATH%</code> (Command Prompt) or <code>$env:Path</code> (PowerShell)</li>
</ul>
<p><strong>Permission issues</strong></p>
<p>If you encounter permission errors when downloading or moving files:</p>
<ul>
<li class="">Choose a directory where you have write permissions (e.g., <code>%USERPROFILE%\atlas\</code>)</li>
<li class="">Or run Command Prompt or PowerShell as Administrator</li>
</ul>
<p><strong>Multiple Atlas versions</strong></p>
<p>If you have multiple versions of Atlas or installed it in multiple locations, Windows will use the first one it finds in the PATH. To check which one is being used:</p>
<div class="language-bash codeBlockContainer_ZGJx theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockContent_kX1v"><pre tabindex="0" class="prism-code language-bash codeBlock_TAPP thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_AdAo"><span class="token-line" style="color:#bfc7d5"><span class="token plain">where atlas</span><br></span></code></pre></div></div>
<p>This command shows all locations where <code>atlas.exe</code> is found in your PATH.</p>
<p>Have additional questions or feedback? Feel free to reach out on our <a href="https://discord.gg/zZ6sWVg6NT" target="_blank" rel="noopener noreferrer" class="">Discord server</a>.</p>]]></content:encoded>
            <category>installation</category>
            <category>windows</category>
            <category>path</category>
            <category>environment variable</category>
        </item>
        <item>
            <title><![CDATA[Do I need Atlas Cloud to use Atlas?]]></title>
            <link>https://atlasgo.io/faq/atlas-without-cloud</link>
            <guid>https://atlasgo.io/faq/atlas-without-cloud</guid>
            <pubDate>Fri, 20 Nov 2026 20:08:41 GMT</pubDate>
            <description><![CDATA[Atlas runs on your machines and in your CI. Atlas Cloud verifies your license and the Atlas Pro features it entitles you to, offline licenses are supported, and the Atlas Registry and other Cloud features are optional.]]></description>
            <content:encoded><![CDATA[<h3 class="anchor anchorTargetStickyNavbar_SAay" id="question">Question<a href="https://atlasgo.io/faq/atlas-without-cloud#question" class="hash-link" aria-label="Direct link to Question" title="Direct link to Question" translate="no">​</a></h3>
<p>Do I need Atlas Cloud to use Atlas? We develop locally, run our own CI, and deploy to our own databases.</p>
<h3 class="anchor anchorTargetStickyNavbar_SAay" id="answer">Answer<a href="https://atlasgo.io/faq/atlas-without-cloud#answer" class="hash-link" aria-label="Direct link to Answer" title="Direct link to Answer" translate="no">​</a></h3>
<p>No. The Atlas CLI runs on your machines and in your CI, and connects to your databases from there. Atlas
Cloud does not access your repositories or databases. By default, it verifies your license and the Atlas
Pro features it entitles you to. The CLI also sends telemetry and error reports, which exclude your data,
database passwords, and schema, see <a class="" href="https://atlasgo.io/cli/data-privacy">data privacy</a>. Offline licenses are supported
too, see <a href="https://atlasgo.io/faq/atlas-without-cloud#working-offline" class="">working offline</a> below.</p>
<ul>
<li class="">License verification: run <code>atlas login</code> on your machine to use <a class="" href="https://atlasgo.io/features#pro">Atlas Pro</a> features,
and log CI jobs in with a <a class="" href="https://atlasgo.io/cloud/bots">bot token</a>. The features that don't need Pro are listed in
<a class="" href="https://atlasgo.io/features">feature availability</a>, and run without logging in.</li>
<li class="">Optional features: the <a class="" href="https://atlasgo.io/cloud/features/registry">Atlas Registry</a>, the system of record for your
schemas, migrations, and <a class="" href="https://atlasgo.io/cloud/deployment">deployments</a>, and the rest of Atlas Cloud:
<a class="" href="https://atlasgo.io/monitoring">schema monitoring</a>, <a class="" href="https://atlasgo.io/cloud/features/schema-docs">schema docs</a>, the
<a class="" href="https://atlasgo.io/cloud/features/lineage-graph">column-level lineage graph</a>, and the
<a class="" href="https://atlasgo.io/cloud/features/security-graph">security graph</a>. Without the registry, package the migration
directory or saved plans in any artifact your pipeline builds, such as a
<a class="" href="https://atlasgo.io/guides/deploying/image">container image</a>, and Atlas runs them from there.</li>
</ul>
<h3 class="anchor anchorTargetStickyNavbar_SAay" id="working-offline">Working offline<a href="https://atlasgo.io/faq/atlas-without-cloud#working-offline" class="hash-link" aria-label="Direct link to Working offline" title="Direct link to Working offline" translate="no">​</a></h3>
<ul>
<li class="">Atlas user licenses work offline by default.</li>
<li class="">In CI, <code>atlas login --token --grant-only</code> caches a grant file, so jobs keep using Atlas Pro features
for some time without connectivity to Atlas Cloud. See <a class="" href="https://atlasgo.io/cloud/bots#offline-access">offline access</a>.</li>
<li class="">For pipelines that never reach Atlas Cloud, the Enterprise tier offers a custom offline license. See
<a class="" href="https://atlasgo.io/trust#offline-operation">offline operation</a>.</li>
</ul>]]></content:encoded>
            <category>atlas cloud</category>
            <category>offline</category>
            <category>privacy</category>
            <category>ci</category>
            <category>local development</category>
        </item>
        <item>
            <title><![CDATA[Changing the Editor for the --edit Flag]]></title>
            <link>https://atlasgo.io/faq/change-editor</link>
            <guid>https://atlasgo.io/faq/change-editor</guid>
            <pubDate>Fri, 20 Nov 2026 20:08:41 GMT</pubDate>
            <description><![CDATA[Learn how to change which editor opens when using the --edit flag with atlas migrate new.]]></description>
            <content:encoded><![CDATA[<h3 class="anchor anchorTargetStickyNavbar_SAay" id="question">Question<a href="https://atlasgo.io/faq/change-editor#question" class="hash-link" aria-label="Direct link to Question" title="Direct link to Question" translate="no">​</a></h3>
<p>Is there a way to change which editor opens when I use the <code>--edit</code> flag while creating a migration?</p>
<h3 class="anchor anchorTargetStickyNavbar_SAay" id="answer">Answer<a href="https://atlasgo.io/faq/change-editor#answer" class="hash-link" aria-label="Direct link to Answer" title="Direct link to Answer" translate="no">​</a></h3>
<p>Yes. You can control which editor opens by setting the <code>EDITOR</code> environment variable.</p>
<p>When you run <code>atlas migrate new</code> with the <code>--edit</code> flag, Atlas checks the <code>EDITOR</code> environment variable
to determine which text editor to launch. If <code>EDITOR</code> is not set, Atlas will use a default editor based
on your operating system.</p>
<h3 class="anchor anchorTargetStickyNavbar_SAay" id="examples">Examples<a href="https://atlasgo.io/faq/change-editor#examples" class="hash-link" aria-label="Direct link to Examples" title="Direct link to Examples" translate="no">​</a></h3>
<p>To change the editor for a single command, you can set the <code>EDITOR</code> variable inline:</p>
<div class="language-bash codeBlockContainer_ZGJx theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockContent_kX1v"><pre tabindex="0" class="prism-code language-bash codeBlock_TAPP thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_AdAo"><span class="token-line" style="color:#bfc7d5"><span class="token comment" style="color:rgb(105, 112, 152);font-style:italic"># Use vim</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token assign-left variable" style="color:rgb(191, 199, 213)">EDITOR</span><span class="token operator" style="color:rgb(137, 221, 255)">=</span><span class="token plain">vim atlas migrate new add_users_table </span><span class="token parameter variable" style="color:rgb(191, 199, 213)">--edit</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token comment" style="color:rgb(105, 112, 152);font-style:italic"># Use nano</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token assign-left variable" style="color:rgb(191, 199, 213)">EDITOR</span><span class="token operator" style="color:rgb(137, 221, 255)">=</span><span class="token plain">nano atlas migrate new add_users_table </span><span class="token parameter variable" style="color:rgb(191, 199, 213)">--edit</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token comment" style="color:rgb(105, 112, 152);font-style:italic"># Use VS Code (wait for the editor to close before continuing)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token assign-left variable" style="color:rgb(191, 199, 213)">EDITOR</span><span class="token operator" style="color:rgb(137, 221, 255)">=</span><span class="token string" style="color:rgb(195, 232, 141)">"code --wait"</span><span class="token plain"> atlas migrate new add_users_table </span><span class="token parameter variable" style="color:rgb(191, 199, 213)">--edit</span><br></span></code></pre></div></div>
<p>Have additional questions or feedback? Feel free to reach out on our <a href="https://discord.gg/zZ6sWVg6NT" target="_blank" rel="noopener noreferrer" class="">Discord server</a>.</p>]]></content:encoded>
            <category>editor</category>
            <category>migrate new</category>
        </item>
        <item>
            <title><![CDATA[Checksum Mismatch between Different Environments]]></title>
            <link>https://atlasgo.io/faq/checksum-mismatch</link>
            <guid>https://atlasgo.io/faq/checksum-mismatch</guid>
            <pubDate>Fri, 20 Nov 2026 20:08:41 GMT</pubDate>
            <description><![CDATA[Resolve Atlas migrate “checksum mismatch” errors between macOS and Linux CI by normalizing line endings (LF/CRLF) using .gitattributes and Git settings.]]></description>
            <content:encoded><![CDATA[<h3 class="anchor anchorTargetStickyNavbar_SAay" id="question">Question<a href="https://atlasgo.io/faq/checksum-mismatch#question" class="hash-link" aria-label="Direct link to Question" title="Direct link to Question" translate="no">​</a></h3>
<p>When using Atlas on my <code>macOS</code>, I can run <code>atlas migrate apply</code> without any issues, and it applies the migrations successfully.
But when running in CI on <code>linux</code>, I get the following error: <code>Error: checksum mismatch</code></p>
<h3 class="anchor anchorTargetStickyNavbar_SAay" id="answer">Answer<a href="https://atlasgo.io/faq/checksum-mismatch#answer" class="hash-link" aria-label="Direct link to Answer" title="Direct link to Answer" translate="no">​</a></h3>
<p>This issue is likely due to differences in line endings between operating systems. <code>macOS</code> uses <code>LF</code> (Line Feed) for line endings,
while <code>Windows</code> uses <code>CRLF</code> (Carriage Return + Line Feed). When you run Atlas commands in a Docker container,
it may be using a different line ending format than what your migrations were created with.</p>
<p>To resolve this issue, you can try the following steps:</p>
<ol>
<li class="">Add a <code>.gitattributes</code> file to your repository with the following content:</li>
</ol>
<div class="language-bash codeBlockContainer_ZGJx theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockContent_kX1v"><pre tabindex="0" class="prism-code language-bash codeBlock_TAPP thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_AdAo"><span class="token-line" style="color:#bfc7d5"><span class="token comment" style="color:rgb(105, 112, 152);font-style:italic"># Ensure all text files use LF line endings</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">* </span><span class="token assign-left variable" style="color:rgb(191, 199, 213)">text</span><span class="token operator" style="color:rgb(137, 221, 255)">=</span><span class="token plain">auto </span><span class="token assign-left variable" style="color:rgb(191, 199, 213)">eol</span><span class="token operator" style="color:rgb(137, 221, 255)">=</span><span class="token plain">lf</span><br></span></code></pre></div></div>
<ol start="2">
<li class="">Commit the <code>.gitattributes</code> file to your repository.</li>
<li class="">If you have existing migration files that were created with different line endings, you may need to normalize them.
You can do this by running the following command in your repository:</li>
</ol>
<div class="language-bash codeBlockContainer_ZGJx theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockContent_kX1v"><pre tabindex="0" class="prism-code language-bash codeBlock_TAPP thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_AdAo"><span class="token-line" style="color:#bfc7d5"><span class="token comment" style="color:rgb(105, 112, 152);font-style:italic"># Remove all files from the index (but keep them on disk)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token function" style="color:rgb(130, 170, 255)">git</span><span class="token plain"> </span><span class="token function" style="color:rgb(130, 170, 255)">rm</span><span class="token plain"> </span><span class="token parameter variable" style="color:rgb(191, 199, 213)">--cached</span><span class="token plain"> </span><span class="token parameter variable" style="color:rgb(191, 199, 213)">-r</span><span class="token plain"> </span><span class="token builtin class-name" style="color:rgb(255, 203, 107)">.</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token comment" style="color:rgb(105, 112, 152);font-style:italic"># Re-checkout the files from the repository</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token function" style="color:rgb(130, 170, 255)">git</span><span class="token plain"> reset </span><span class="token parameter variable" style="color:rgb(191, 199, 213)">--hard</span><br></span></code></pre></div></div>]]></content:encoded>
            <category>faq</category>
            <category>ci</category>
            <category>checksum</category>
            <category>migrations</category>
        </item>
        <item>
            <title><![CDATA[Why Atlas reports GRANT or REVOKE for the postgres user on Cloud SQL]]></title>
            <link>https://atlasgo.io/faq/cloud-sql-postgres-grants</link>
            <guid>https://atlasgo.io/faq/cloud-sql-postgres-grants</guid>
            <pubDate>Fri, 20 Nov 2026 20:08:41 GMT</pubDate>
            <description><![CDATA[Why atlas schema inspect lists grants to the postgres user on Cloud SQL and schema diff plans a REVOKE per object with a local dev database, and how to exclude the managed admin user and its grants.]]></description>
            <content:encoded><![CDATA[<p>Why does <code>atlas schema inspect</code> against Cloud SQL list <code>GRANT ... TO "postgres"</code> on every object, and why does <code>schema diff</code> or <code>migrate diff</code> with a local dev database plan a <code>REVOKE</code> from <code>postgres</code> per object?</p>
<h3 class="anchor anchorTargetStickyNavbar_SAay" id="answer">Answer<a href="https://atlasgo.io/faq/cloud-sql-postgres-grants#answer" class="hash-link" aria-label="Direct link to Answer" title="Direct link to Answer" translate="no">​</a></h3>
<p>Exclude the managed admin role and its grants in the environment that targets Cloud SQL:</p>
<div class="language-hcl codeBlockContainer_ZGJx theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockTitle_L5qy">atlas.hcl</div><div class="codeBlockContent_kX1v"><pre tabindex="0" class="prism-code language-hcl codeBlock_TAPP thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_AdAo"><span class="token-line" style="color:#bfc7d5"><span class="token plain">env </span><span class="token string" style="color:rgb(195, 232, 141)">"staging"</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token property">url</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">=</span><span class="token plain"> getenv(</span><span class="token string" style="color:rgb(195, 232, 141)">"DATABASE_URL"</span><span class="token plain">)</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token property">dev</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">=</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"docker://postgres/16/dev"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token property">exclude</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">=</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">[</span><span class="token plain"></span><br></span><span class="token-line theme-code-block-highlighted-line" style="color:#bfc7d5"><span class="token plain">    </span><span class="token string" style="color:rgb(195, 232, 141)">"postgres[type=role|user]"</span><span class="token plain">,</span><br></span><span class="token-line theme-code-block-highlighted-line" style="color:#bfc7d5"><span class="token plain">    </span><span class="token string" style="color:rgb(195, 232, 141)">"postgres[type=role|user].permission"</span><span class="token plain">,</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token punctuation" style="color:rgb(199, 146, 234)">]</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token punctuation" style="color:rgb(199, 146, 234)">}</span><br></span></code></pre></div></div>
<p>The first pattern removes only the role object, since many projects exclude roles but still manage grants to them. The second removes the grants.</p>
<h3 class="anchor anchorTargetStickyNavbar_SAay" id="why-it-happens">Why it happens<a href="https://atlasgo.io/faq/cloud-sql-postgres-grants#why-it-happens" class="hash-link" aria-label="Direct link to Why it happens" title="Direct link to Why it happens" translate="no">​</a></h3>
<p>On Cloud SQL for PostgreSQL, the bootstrap superuser is Google's <code>cloudsqladmin</code>. The <code>postgres</code> user is created afterwards as an ordinary role: not a superuser, a member of <code>cloudsqlsuperuser</code> for <code>CREATEROLE</code> and <code>CREATEDB</code>, <strong>with an OID above the system range</strong>. On a local container, <code>postgres</code> is the bootstrap superuser.</p>
<p>Atlas skips the superuser's implicit grants on a local dev database, but on Cloud SQL <code>postgres</code> is a regular role, so its grants show up in inspection and in every diff.</p>
<h3 class="anchor anchorTargetStickyNavbar_SAay" id="managing-grants-to-the-admin-user">Managing grants to the admin user<a href="https://atlasgo.io/faq/cloud-sql-postgres-grants#managing-grants-to-the-admin-user" class="hash-link" aria-label="Direct link to Managing grants to the admin user" title="Direct link to Managing grants to the admin user" translate="no">​</a></h3>
<p>Grants to <code>postgres</code> cannot be planned through a local dev database, because PostgreSQL makes them implicit for a superuser. To manage them, use a dev database where <code>postgres</code> is an ordinary role, such as a second Cloud SQL instance.</p>
<h3 class="anchor anchorTargetStickyNavbar_SAay" id="other-managed-services">Other managed services<a href="https://atlasgo.io/faq/cloud-sql-postgres-grants#other-managed-services" class="hash-link" aria-label="Direct link to Other managed services" title="Direct link to Other managed services" translate="no">​</a></h3>
<p>Any managed service whose admin user is not a real superuser behaves the same: the master user on Amazon RDS and Aurora, a member of <code>rds_superuser</code>, the admin on Azure Database for PostgreSQL Flexible Server, a member of <code>azure_pg_admin</code>, and the admin on AlloyDB, a member of <code>alloydbsuperuser</code>. Use the same two patterns with that name.</p>
<h3 class="anchor anchorTargetStickyNavbar_SAay" id="related">Related<a href="https://atlasgo.io/faq/cloud-sql-postgres-grants#related" class="hash-link" aria-label="Direct link to Related" title="Direct link to Related" translate="no">​</a></h3>
<ul>
<li class=""><a class="" href="https://atlasgo.io/guides/postgres/security-declarative#managed-admin-users-such-as-postgres-on-cloud-sql">PostgreSQL Security as Code (Declarative)</a></li>
<li class=""><a class="" href="https://atlasgo.io/guides/postgres/security-versioned#managed-admin-users-such-as-postgres-on-cloud-sql">PostgreSQL Security as Code (Versioned)</a></li>
</ul>]]></content:encoded>
            <category>faq</category>
            <category>postgres</category>
            <category>cloud sql</category>
            <category>rds</category>
            <category>permissions</category>
            <category>roles</category>
            <category>exclude</category>
        </item>
        <item>
            <title><![CDATA[Detect Migrations Drift in CI]]></title>
            <link>https://atlasgo.io/faq/desired-state-drift</link>
            <guid>https://atlasgo.io/faq/desired-state-drift</guid>
            <pubDate>Fri, 20 Nov 2026 20:08:41 GMT</pubDate>
            <description><![CDATA[How to detect schema drift in CI and ensure the migration directory is up to date with the desired schema state -]]></description>
            <content:encoded><![CDATA[<p>How to detect schema drift in CI and ensure the migration directory is up to date with the desired schema state -
ORM, HCL, SQL, or any other schema definition?</p>
<h3 class="anchor anchorTargetStickyNavbar_SAay" id="answer">Answer<a href="https://atlasgo.io/faq/desired-state-drift#answer" class="hash-link" aria-label="Direct link to Answer" title="Direct link to Answer" translate="no">​</a></h3>
<p>One option is to run <code>atlas migrate diff --env=&lt;ENV-NAME&gt;</code>, and then check that no files were generated by
this command: <code>status=$(git status --porcelain)</code>.</p>
<p>If an engineer forgot to run <code>atlas migrate diff</code> the schema state will not match the state of your migration
directory and new migration file will be created. If the two states match, no new migration file will be generated.</p>
<p>Another option is to use <code>schema diff</code> (with a custom <code>--format</code>) to detect changes and fail if there are any:</p>
<div class="language-bash codeBlockContainer_ZGJx theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockContent_kX1v"><pre tabindex="0" class="prism-code language-bash codeBlock_TAPP thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_AdAo"><span class="token-line" style="color:#bfc7d5"><span class="token plain">atlas schema </span><span class="token function" style="color:rgb(130, 170, 255)">diff</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">\</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token parameter variable" style="color:rgb(191, 199, 213)">--from</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"file://migrations"</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">\</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token parameter variable" style="color:rgb(191, 199, 213)">--to</span><span class="token plain"> env://orm </span><span class="token punctuation" style="color:rgb(199, 146, 234)">\</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token parameter variable" style="color:rgb(191, 199, 213)">--env</span><span class="token plain"> </span><span class="token builtin class-name" style="color:rgb(255, 203, 107)">local</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">\</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token parameter variable" style="color:rgb(191, 199, 213)">--format</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">'{{ if .Changes }}fail{{ end }}'</span><span class="token plain"> </span><span class="token operator" style="color:rgb(137, 221, 255)">|</span><span class="token plain"> </span><span class="token function" style="color:rgb(130, 170, 255)">grep</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">'.'</span><span class="token plain"> </span><span class="token operator" style="color:rgb(137, 221, 255)">&amp;&amp;</span><span class="token plain"> </span><span class="token builtin class-name" style="color:rgb(255, 203, 107)">exit</span><span class="token plain"> </span><span class="token number" style="color:rgb(247, 140, 108)">1</span><br></span></code></pre></div></div>
<p>(Alternatively, convert it to: <code>if [ -n "$output" ]; then .. fi</code>).</p>
<p>See more details, see <a class="" href="https://atlasgo.io/declarative/diff#compare-external-schemas">schema diff documentation</a>.</p>]]></content:encoded>
            <category>faq</category>
            <category>versioned migrations</category>
            <category>migrations drift</category>
            <category>schema drift</category>
            <category>ci</category>
            <category>external schemas</category>
        </item>
        <item>
            <title><![CDATA[Can I store migration files in S3? (CLI and Terraform examples)]]></title>
            <link>https://atlasgo.io/faq/s3-dirs</link>
            <guid>https://atlasgo.io/faq/s3-dirs</guid>
            <pubDate>Fri, 20 Nov 2026 20:08:41 GMT</pubDate>
            <description><![CDATA[With Atlas, we advocate for treating migration directories as deployment artifacts resulting from a structured]]></description>
            <content:encoded><![CDATA[<p>With Atlas, we advocate for treating migration directories as deployment artifacts resulting from a structured
build process. The preferred approach is to push migration directories to the
<a class="" href="https://atlasgo.io/cloud/features/registry">Atlas Schema Registry</a>. In addition to its role as a migration directory storage, the Schema
Registry provides a tight integration with the Atlas CLI and the Atlas Cloud UI, allowing you to deploy migrations,
visualize schemas over time, review deployment logs and errors, and more.</p>
<p>However, some users prefer to store their migration directories in S3, typically due to internal policies or requirements.</p>
<!-- -->
<h3 class="anchor anchorTargetStickyNavbar_SAay" id="how-to-deploy-migrations-from-s3-">How to deploy migrations from S3 <span class="badge login badge--info" style="font-size:12px"><a style="color:white;text-decoration:none" href="https://atlasgo.io/features#pro">Atlas Pro</a></span><a href="https://atlasgo.io/faq/s3-dirs#how-to-deploy-migrations-from-s3-" class="hash-link" aria-label="Direct link to how-to-deploy-migrations-from-s3-" title="Direct link to how-to-deploy-migrations-from-s3-" translate="no">​</a></h3>
<div class="theme-admonition theme-admonition-info admonition_IZjC alert alert--info"><div class="admonitionHeading_uVvU"><span class="admonitionIcon_HiR3"><svg viewBox="0 0 14 16"><path fill-rule="evenodd" d="M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"></path></svg></span>info</div><div class="admonitionContent_bl22"><p>The <code>blob_dir</code> data source is available to Atlas Pro users only.</p></div></div>
<p>To deploy migrations from S3, use the <code>blob_dir</code> data source in your <code>atlas.hcl</code> file:</p>
<div class="language-hcl codeBlockContainer_ZGJx theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockTitle_L5qy">atlas.hcl</div><div class="codeBlockContent_kX1v"><pre tabindex="0" class="prism-code language-hcl codeBlock_TAPP thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_AdAo"><span class="token-line" style="color:#bfc7d5"><span class="token keyword" style="font-style:italic">data </span><span class="token keyword type variable" style="font-style:italic;color:rgb(191, 199, 213)">"blob_dir"</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"migrations"</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token property">url</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">=</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"s3://my-s3-bucket/path/to/migrations?profile=aws-profile"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token punctuation" style="color:rgb(199, 146, 234)">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">env </span><span class="token string" style="color:rgb(195, 232, 141)">"dev"</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token property">url</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">=</span><span class="token plain"> var.url</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token keyword" style="font-style:italic">migration</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">    </span><span class="token property">dir</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">=</span><span class="token plain"> data.blob_dir.migrations.url</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token punctuation" style="color:rgb(199, 146, 234)">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token punctuation" style="color:rgb(199, 146, 234)">}</span><br></span></code></pre></div></div>
<p>You can tell the <code>profile</code> query parameter to use a specific AWS profile through your local AWS credentials file, or
set the credentials using environment variables <code>AWS_ACCESS_KEY_ID</code> and <code>AWS_SECRET_ACCESS_KEY</code>.</p>
<h3 class="anchor anchorTargetStickyNavbar_SAay" id="how-to-deploy-from-blob_dir-in-terraform">How to deploy from <code>blob_dir</code> in Terraform?<a href="https://atlasgo.io/faq/s3-dirs#how-to-deploy-from-blob_dir-in-terraform" class="hash-link" aria-label="Direct link to how-to-deploy-from-blob_dir-in-terraform" title="Direct link to how-to-deploy-from-blob_dir-in-terraform" translate="no">​</a></h3>
<p>To deploy migrations from S3 using the Atlas Terraform provider, use the <code>atlas_migration</code> resource in combination
with a custom configuration block.</p>
<div class="language-hcl codeBlockContainer_ZGJx theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockTitle_L5qy">main.tf</div><div class="codeBlockContent_kX1v"><pre tabindex="0" class="prism-code language-hcl codeBlock_TAPP thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_AdAo"><span class="token-line" style="color:#bfc7d5"><span class="token keyword" style="font-style:italic">terraform</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token keyword" style="font-style:italic">required_providers</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">    </span><span class="token property">atlas</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">=</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">      </span><span class="token property">version</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">=</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"0.9.8"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">      </span><span class="token property">source</span><span class="token plain">  </span><span class="token punctuation" style="color:rgb(199, 146, 234)">=</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"ariga/atlas"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">    </span><span class="token punctuation" style="color:rgb(199, 146, 234)">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token punctuation" style="color:rgb(199, 146, 234)">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token punctuation" style="color:rgb(199, 146, 234)">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token keyword" style="font-style:italic">locals</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token property">config</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">=</span><span class="token plain"> </span><span class="token heredoc string" style="color:rgb(195, 232, 141)">&lt;&lt;HCL</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token heredoc string" style="color:rgb(195, 232, 141)">variable "url" {</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token heredoc string" style="color:rgb(195, 232, 141)">  type = string</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token heredoc string" style="color:rgb(195, 232, 141)">  default = getenv("DB_URL")</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token heredoc string" style="color:rgb(195, 232, 141)">}</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token heredoc string" style="display:inline-block;color:rgb(195, 232, 141)"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token heredoc string" style="color:rgb(195, 232, 141)">variable "s3_bucket" {</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token heredoc string" style="color:rgb(195, 232, 141)">  type = string</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token heredoc string" style="color:rgb(195, 232, 141)">}</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token heredoc string" style="display:inline-block;color:rgb(195, 232, 141)"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token heredoc string" style="color:rgb(195, 232, 141)">data "blob_dir" "migrations" {</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token heredoc string" style="color:rgb(195, 232, 141)">  url = var.s3_bucket</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token heredoc string" style="color:rgb(195, 232, 141)">}</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token heredoc string" style="display:inline-block;color:rgb(195, 232, 141)"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token heredoc string" style="color:rgb(195, 232, 141)">env {</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token heredoc string" style="color:rgb(195, 232, 141)">  name = atlas.env</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token heredoc string" style="color:rgb(195, 232, 141)">  url  = var.url</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token heredoc string" style="color:rgb(195, 232, 141)">  dev  = "docker://postgres/15/dev?search_path=public"</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token heredoc string" style="color:rgb(195, 232, 141)">  migration {</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token heredoc string" style="color:rgb(195, 232, 141)">    dir = data.blob_dir.migrations.url</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token heredoc string" style="color:rgb(195, 232, 141)">  }</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token heredoc string" style="color:rgb(195, 232, 141)">}</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token heredoc string" style="color:rgb(195, 232, 141)">HCL</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token property">vars</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">=</span><span class="token plain"> jsonencode(</span><span class="token punctuation" style="color:rgb(199, 146, 234)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">    </span><span class="token property">s3_bucket</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">=</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"s3://my-s3-bucket/migrations?profile=tf-dev"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token punctuation" style="color:rgb(199, 146, 234)">}</span><span class="token plain">)</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token punctuation" style="color:rgb(199, 146, 234)">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token keyword" style="font-style:italic">data </span><span class="token keyword type variable" style="font-style:italic;color:rgb(191, 199, 213)">"atlas_migration"</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"hello"</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token property">config</span><span class="token plain">    </span><span class="token punctuation" style="color:rgb(199, 146, 234)">=</span><span class="token plain"> local.config</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token property">variables</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">=</span><span class="token plain"> local.vars</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token property">env_name</span><span class="token plain">  </span><span class="token punctuation" style="color:rgb(199, 146, 234)">=</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"foo"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token punctuation" style="color:rgb(199, 146, 234)">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token keyword" style="font-style:italic">resource </span><span class="token keyword type variable" style="font-style:italic;color:rgb(191, 199, 213)">"atlas_migration"</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"testdb"</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token property">version</span><span class="token plain">   </span><span class="token punctuation" style="color:rgb(199, 146, 234)">=</span><span class="token plain"> data.atlas_migration.hello.latest</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token property">config</span><span class="token plain">    </span><span class="token punctuation" style="color:rgb(199, 146, 234)">=</span><span class="token plain"> local.config</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token property">variables</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">=</span><span class="token plain"> local.vars</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token property">env_name</span><span class="token plain">  </span><span class="token punctuation" style="color:rgb(199, 146, 234)">=</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"foo"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token punctuation" style="color:rgb(199, 146, 234)">}</span><br></span></code></pre></div></div>
<p>Assuming we have a local Postgres database running:</p>
<div class="language-shell codeBlockContainer_ZGJx theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockContent_kX1v"><pre tabindex="0" class="prism-code language-shell codeBlock_TAPP thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_AdAo"><span class="token-line" style="color:#bfc7d5"><span class="token function" style="color:rgb(130, 170, 255)">docker</span><span class="token plain"> run </span><span class="token parameter variable" style="color:rgb(191, 199, 213)">--name</span><span class="token plain"> some-postgres </span><span class="token parameter variable" style="color:rgb(191, 199, 213)">-p</span><span class="token plain"> </span><span class="token number" style="color:rgb(247, 140, 108)">5432</span><span class="token plain">:5432 </span><span class="token parameter variable" style="color:rgb(191, 199, 213)">-e</span><span class="token plain"> </span><span class="token assign-left variable" style="color:rgb(191, 199, 213)">POSTGRES_PASSWORD</span><span class="token operator" style="color:rgb(137, 221, 255)">=</span><span class="token plain">mysecretpassword </span><span class="token parameter variable" style="color:rgb(191, 199, 213)">-d</span><span class="token plain"> postgres</span><br></span></code></pre></div></div>
<p>Set the environment variable <code>DB_URL</code> to connect to the database:</p>
<div class="language-shell codeBlockContainer_ZGJx theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockContent_kX1v"><pre tabindex="0" class="prism-code language-shell codeBlock_TAPP thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_AdAo"><span class="token-line" style="color:#bfc7d5"><span class="token builtin class-name" style="color:rgb(255, 203, 107)">export</span><span class="token plain"> </span><span class="token assign-left variable" style="color:rgb(191, 199, 213)">DB_URL</span><span class="token operator" style="color:rgb(137, 221, 255)">=</span><span class="token string" style="color:rgb(195, 232, 141)">'export DB_URL='</span><span class="token plain">postgresql://postgres:mysecretpassword@localhost:5432?search_path</span><span class="token operator" style="color:rgb(137, 221, 255)">=</span><span class="token plain">public</span><span class="token operator" style="color:rgb(137, 221, 255)">&amp;</span><span class="token assign-left variable" style="color:rgb(191, 199, 213)">sslmode</span><span class="token operator" style="color:rgb(137, 221, 255)">=</span><span class="token plain">disable'</span><br></span></code></pre></div></div>
<p>Then, run the migration:</p>
<div class="language-shell codeBlockContainer_ZGJx theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockContent_kX1v"><pre tabindex="0" class="prism-code language-shell codeBlock_TAPP thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_AdAo"><span class="token-line" style="color:#bfc7d5"><span class="token plain">terraform apply</span><br></span></code></pre></div></div>
<p>This will apply the latest migration from the S3 bucket specified in the <code>s3_bucket</code> variable:</p>
<div class="language-text codeBlockContainer_ZGJx theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockContent_kX1v"><pre tabindex="0" class="prism-code language-text codeBlock_TAPP thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_AdAo"><span class="token-line" style="color:#bfc7d5"><span class="token plain">data.atlas_migration.hello: Reading...</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">data.atlas_migration.hello: Read complete after 6s [id=8cld198f-23dd-61ca-0f97-2a3ealdf1fb6]</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">atlas_migration.testdb: Refreshing state... [id=7cac2593-a043-69f3-7383-ab1f27b14654]</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">Terraform used the selected providers to generate the following execution plan.</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">Resource actions are indicated with the following symbols:</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  + create</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">Terraform will perform the following actions:</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  # atlas_migration.testdb will be created</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  + resource "atlas_migration" "testdb" {</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">      + config = &lt;&lt;-EOT</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">          variable "url" {</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">            type    = string</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">            default = getenv("DB_URL")</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">          }</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">          variable "s3_bucket" {</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">            type = string</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">          }</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">          data "blob_dir" "migrations" {</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">            url = var.s3_bucket</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">          }</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">          env {</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">            name = atlas.env</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">            url  = var.url</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">            dev  = "docker://postgres/15/dev?search_path=public"</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">            migration {</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">              dir = data.blob_dir.migrations.url</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">            }</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">          }</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">        EOT</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">      + env_name  = "foo"</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">      + id        = (known after apply)</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">      + status    = (known after apply)</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">      + variables = jsonencode({</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">          53_bucket = "s3://my-s3-bucket/migrations?profile=tf-dev"</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">        })</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">      + version   = "20250618181441"</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">    }</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">Plan: 1 to add, 0 to change, 0 to destroy.</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">Do you want to perform these actions?</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  Terraform will perform the actions described above.</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  Only 'yes' will be accepted to approve.</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">Enter a value: yes</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">atlas_migration.testdb: Creating...</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">atlas_migration.testdb: Still creating... [10s elapsed]</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">atlas_migration.testdb: Creation complete after 18s [id=d9eb9c09-0c95-fldd-46e0-0de31df39581]</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">Apply complete! Resources: 1 added, 0 changed, 0 destroyed.</span><br></span></code></pre></div></div>]]></content:encoded>
            <category>faq</category>
            <category>versioned migrations</category>
            <category>s3</category>
            <category>migrate apply</category>
            <category>terraform</category>
            <category>blob_dir</category>
        </item>
        <item>
            <title><![CDATA[Why docker:// does not work inside the Atlas Docker image]]></title>
            <link>https://atlasgo.io/faq/docker-in-docker</link>
            <guid>https://atlasgo.io/faq/docker-in-docker</guid>
            <pubDate>Fri, 20 Nov 2026 20:08:41 GMT</pubDate>
            <description><![CDATA[Learn why docker:// URLs fail inside the Atlas Docker image and how to properly configure dev databases in container environments.]]></description>
            <content:encoded><![CDATA[<h3 class="anchor anchorTargetStickyNavbar_SAay" id="question">Question<a href="https://atlasgo.io/faq/docker-in-docker#question" class="hash-link" aria-label="Direct link to Question" title="Direct link to Question" translate="no">​</a></h3>
<p>Why does using a dev URL like <code>docker://postgres/15/dev</code> inside the official <code>arigaio/atlas</code> image fail with:
<code>exec: "docker": executable file not found in $PATH</code>?</p>
<h3 class="anchor anchorTargetStickyNavbar_SAay" id="answer">Answer<a href="https://atlasgo.io/faq/docker-in-docker#answer" class="hash-link" aria-label="Direct link to Answer" title="Direct link to Answer" translate="no">​</a></h3>
<p>Commands that use <code>docker://</code> dev-database URLs (such as <code>schema diff</code>, <code>schema apply</code>, and <code>migrate test</code>) fail when run inside
the Atlas Docker image. This is expected behavior.</p>
<p>The <code>docker://</code> scheme requires Atlas to run the docker client to start a temporary database container.
The official Atlas image is minimal and does not include the docker binary. Additionally, the Docker daemon
is unreachable from inside the container unless explicitly mounted.</p>
<h3 class="anchor anchorTargetStickyNavbar_SAay" id="where-docker-urls-work">Where docker:// URLs Work<a href="https://atlasgo.io/faq/docker-in-docker#where-docker-urls-work" class="hash-link" aria-label="Direct link to Where docker:// URLs Work" title="Direct link to Where docker:// URLs Work" translate="no">​</a></h3>
<p>The <code>docker://</code> scheme is supported when:</p>
<ul>
<li class="">Running Atlas directly on a machine where docker is installed</li>
<li class="">Running Atlas in a CI environment where docker is available (both docker client and docker daemon)</li>
<li class="">Using custom container images that include the docker client and have access to the host docker daemon</li>
</ul>
<h3 class="anchor anchorTargetStickyNavbar_SAay" id="recommended-approach">Recommended Approach<a href="https://atlasgo.io/faq/docker-in-docker#recommended-approach" class="hash-link" aria-label="Direct link to Recommended Approach" title="Direct link to Recommended Approach" translate="no">​</a></h3>
<p>In container-based platforms (Kubernetes, ECS, CI runners, etc.), it is not recommended for a container to spin up
other containers on the host. Instead:</p>
<ol>
<li class="">Run a separate dev database container</li>
<li class="">Pass its connection URL to the Atlas container</li>
</ol>
<p>For example:</p>
<div class="language-hcl codeBlockContainer_ZGJx theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockContent_kX1v"><pre tabindex="0" class="prism-code language-hcl codeBlock_TAPP thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_AdAo"><span class="token-line" style="color:#bfc7d5"><span class="token plain">env </span><span class="token string" style="color:rgb(195, 232, 141)">"local"</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token property">url</span><span class="token plain">  </span><span class="token punctuation" style="color:rgb(199, 146, 234)">=</span><span class="token plain"> getenv(</span><span class="token string" style="color:rgb(195, 232, 141)">"DATABASE_URL"</span><span class="token plain">)</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token property">src</span><span class="token plain">  </span><span class="token punctuation" style="color:rgb(199, 146, 234)">=</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"file://schema"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token property">dev</span><span class="token plain">  </span><span class="token punctuation" style="color:rgb(199, 146, 234)">=</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"postgres://user:pass@dev-db:5432/dev?sslmode=disable"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token punctuation" style="color:rgb(199, 146, 234)">}</span><br></span></code></pre></div></div>
<p>This keeps Atlas isolated and avoids granting containers permissions to manage host resources.</p>
<h3 class="anchor anchorTargetStickyNavbar_SAay" id="advanced-workaround">Advanced Workaround<a href="https://atlasgo.io/faq/docker-in-docker#advanced-workaround" class="hash-link" aria-label="Direct link to Advanced Workaround" title="Direct link to Advanced Workaround" translate="no">​</a></h3>
<p>If <code>docker://</code> must be used inside a container, you can provide the docker CLI and daemon access to the Atlas container. For example:</p>
<div class="language-bash codeBlockContainer_ZGJx theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockContent_kX1v"><pre tabindex="0" class="prism-code language-bash codeBlock_TAPP thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_AdAo"><span class="token-line" style="color:#bfc7d5"><span class="token function" style="color:rgb(130, 170, 255)">docker</span><span class="token plain"> run </span><span class="token punctuation" style="color:rgb(199, 146, 234)">\</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token parameter variable" style="color:rgb(191, 199, 213)">--volume</span><span class="token operator" style="color:rgb(137, 221, 255)">=</span><span class="token plain">/usr/local/bin/docker:/usr/local/bin/docker:ro </span><span class="token punctuation" style="color:rgb(199, 146, 234)">\</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  --add-host</span><span class="token operator" style="color:rgb(137, 221, 255)">=</span><span class="token string" style="color:rgb(195, 232, 141)">"host.docker.internal:</span><span class="token string variable" style="color:rgb(191, 199, 213)">$DOCKER_HOST</span><span class="token string" style="color:rgb(195, 232, 141)">"</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">\</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  arigaio/atlas:latest</span><br></span></code></pre></div></div>
<p>This approach mounts the docker client into the container and requires the host docker daemon to be reachable (e.g., via <code>host.docker.internal</code> in Docker Desktop, or by mounting <code>/var/run/docker.sock</code> on Linux). This is an advanced setup and not recommended for most CI or container environments. Configuration details vary by platform (Bitbucket Pipelines, GitHub Actions, GitLab CI, etc.).</p>
<p>Have additional questions or feedback? Feel free to reach out on our <a href="https://discord.gg/zZ6sWVg6NT" target="_blank" rel="noopener noreferrer" class="">Discord server</a>.</p>]]></content:encoded>
            <category>docker</category>
            <category>dev-database</category>
            <category>container</category>
            <category>ci</category>
        </item>
        <item>
            <title><![CDATA[Using dotenv (.env) files with Atlas]]></title>
            <link>https://atlasgo.io/faq/dotenv-files</link>
            <guid>https://atlasgo.io/faq/dotenv-files</guid>
            <pubDate>Fri, 20 Nov 2026 20:08:41 GMT</pubDate>
            <description><![CDATA[Learn how to access environment variables with Atlas.]]></description>
            <content:encoded><![CDATA[<p>A <code>.env</code> file is a simple text file used to store environment variables for applications. It helps developers manage
configuration settings, such as database credentials, API keys, and other sensitive information, without hardcoding them
into the source code. By using a <code>.env</code> file, developers can keep their codebase clean, secure, and easily configurable
across different environments.</p>
<p>For developers who want to use <code>.env</code> files with Atlas, there are two ways users can do so through the standard Atlas
HCL configuration file:</p>
<h3 class="anchor anchorTargetStickyNavbar_SAay" id="write-an-hcl-expression-to-load-the-file-into-atlas">Write an HCL expression to load the file into Atlas<a href="https://atlasgo.io/faq/dotenv-files#write-an-hcl-expression-to-load-the-file-into-atlas" class="hash-link" aria-label="Direct link to Write an HCL expression to load the file into Atlas" title="Direct link to Write an HCL expression to load the file into Atlas" translate="no">​</a></h3>
<p>First, create a <code>string</code> variable in your <code>atlas.hcl</code> file that will contain the content of your <code>.env</code> file.
Next, use a local expression to split the string and create a map of your <code>.env</code> variable keys to their values.
Now, your <code>.env</code> variables can be accessed by simply indexing this map with the name of your desired variable.</p>
<p>For example, let's say the URL to my database is defined in my <code>.env</code> file, so I'd like to use that variable in my
<code>atlas.hcl</code> file rather than having it written out in two different places.</p>
<div class="language-bash codeBlockContainer_ZGJx theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockTitle_L5qy">.env</div><div class="codeBlockContent_kX1v"><pre tabindex="0" class="prism-code language-bash codeBlock_TAPP thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_AdAo"><span class="token-line" style="color:#bfc7d5"><span class="token comment" style="color:rgb(105, 112, 152);font-style:italic"># ... more variables</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token assign-left variable" style="color:rgb(191, 199, 213)">DATABASE_URL</span><span class="token operator" style="color:rgb(137, 221, 255)">=</span><span class="token plain">mysql://localhost:3306/dev</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token comment" style="color:rgb(105, 112, 152);font-style:italic"># ... more variables</span><br></span></code></pre></div></div>
<div class="language-hcl codeBlockContainer_ZGJx theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockTitle_L5qy">atlas.hcl</div><div class="codeBlockContent_kX1v"><pre tabindex="0" class="prism-code language-hcl codeBlock_TAPP thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_AdAo"><span class="token-line" style="color:#bfc7d5"><span class="token keyword" style="font-style:italic">variable</span><span class="token keyword type variable" style="font-style:italic;color:rgb(191, 199, 213)"> "envfile" </span><span class="token punctuation" style="color:rgb(199, 146, 234)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">    </span><span class="token property">type</span><span class="token plain">    </span><span class="token punctuation" style="color:rgb(199, 146, 234)">=</span><span class="token plain"> string</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">    </span><span class="token property">default</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">=</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"/path/to/.env"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token punctuation" style="color:rgb(199, 146, 234)">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token keyword" style="font-style:italic">locals</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">    </span><span class="token property">envfile</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">=</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">        for line in split(</span><span class="token string" style="color:rgb(195, 232, 141)">"\n"</span><span class="token plain">, file(var.envfile)): split(</span><span class="token string" style="color:rgb(195, 232, 141)">"="</span><span class="token plain">, line)</span><span class="token punctuation" style="color:rgb(199, 146, 234)">[</span><span class="token number" style="color:rgb(247, 140, 108)">0</span><span class="token punctuation" style="color:rgb(199, 146, 234)">]</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">=</span><span class="token plain">&gt; regex(</span><span class="token string" style="color:rgb(195, 232, 141)">"=(.*)"</span><span class="token plain">, line)</span><span class="token punctuation" style="color:rgb(199, 146, 234)">[</span><span class="token number" style="color:rgb(247, 140, 108)">0</span><span class="token punctuation" style="color:rgb(199, 146, 234)">]</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">        if !startswith(line, </span><span class="token string" style="color:rgb(195, 232, 141)">"#"</span><span class="token plain">) &amp;&amp; length(split(</span><span class="token string" style="color:rgb(195, 232, 141)">"="</span><span class="token plain">, line)) &gt; </span><span class="token number" style="color:rgb(247, 140, 108)">1</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">    </span><span class="token punctuation" style="color:rgb(199, 146, 234)">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token punctuation" style="color:rgb(199, 146, 234)">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token keyword" style="font-style:italic">env</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">    </span><span class="token property">name</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">=</span><span class="token plain"> atlas.env</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">    </span><span class="token property">url</span><span class="token plain">  </span><span class="token punctuation" style="color:rgb(199, 146, 234)">=</span><span class="token plain"> local.envfile</span><span class="token punctuation" style="color:rgb(199, 146, 234)">[</span><span class="token string" style="color:rgb(195, 232, 141)">"DATABASE_URL"</span><span class="token punctuation" style="color:rgb(199, 146, 234)">]</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token punctuation" style="color:rgb(199, 146, 234)">}</span><br></span></code></pre></div></div>
<p>Since I've loaded my <code>.env</code> variables into a local map, I can easily grab the URL to my database and apply it to <code>env.url</code>.</p>
<h3 class="anchor anchorTargetStickyNavbar_SAay" id="use-an-external-program">Use an external program<a href="https://atlasgo.io/faq/dotenv-files#use-an-external-program" class="hash-link" aria-label="Direct link to Use an external program" title="Direct link to Use an external program" translate="no">​</a></h3>
<p>If you have a <code>.env</code> reader/parser of choice, you can also integrate that external program into <code>atlas.hcl</code> so it can use its output.</p>
<p>Take the following implementation example:</p>
<div class="language-hcl codeBlockContainer_ZGJx theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockContent_kX1v"><pre tabindex="0" class="prism-code language-hcl codeBlock_TAPP thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_AdAo"><span class="token-line" style="color:#bfc7d5"><span class="token keyword" style="font-style:italic">data </span><span class="token keyword type variable" style="font-style:italic;color:rgb(191, 199, 213)">"external"</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"envfile"</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token property">program</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">=</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">[</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">    </span><span class="token string" style="color:rgb(195, 232, 141)">"node"</span><span class="token plain">, </span><span class="token string" style="color:rgb(195, 232, 141)">"envfile.cjs"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token punctuation" style="color:rgb(199, 146, 234)">]</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token punctuation" style="color:rgb(199, 146, 234)">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token keyword" style="font-style:italic">locals</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token property">envfile</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">=</span><span class="token plain"> jsondecode(data.external.envfile)</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token punctuation" style="color:rgb(199, 146, 234)">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">env </span><span class="token string" style="color:rgb(195, 232, 141)">"local"</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token property">src</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">=</span><span class="token plain"> local.envfile.DATABASE_URL</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token punctuation" style="color:rgb(199, 146, 234)">}</span><br></span></code></pre></div></div>
<div class="language-js codeBlockContainer_ZGJx theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockContent_kX1v"><pre tabindex="0" class="prism-code language-js codeBlock_TAPP thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_AdAo"><span class="token-line" style="color:#bfc7d5"><span class="token keyword" style="font-style:italic">const</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">{</span><span class="token plain"> loadEnvFile </span><span class="token punctuation" style="color:rgb(199, 146, 234)">}</span><span class="token plain"> </span><span class="token operator" style="color:rgb(137, 221, 255)">=</span><span class="token plain"> </span><span class="token function" style="color:rgb(130, 170, 255)">require</span><span class="token punctuation" style="color:rgb(199, 146, 234)">(</span><span class="token string" style="color:rgb(195, 232, 141)">'node:process'</span><span class="token punctuation" style="color:rgb(199, 146, 234)">)</span><span class="token punctuation" style="color:rgb(199, 146, 234)">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token function" style="color:rgb(130, 170, 255)">loadEnvFile</span><span class="token punctuation" style="color:rgb(199, 146, 234)">(</span><span class="token punctuation" style="color:rgb(199, 146, 234)">)</span><span class="token punctuation" style="color:rgb(199, 146, 234)">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token console class-name" style="color:rgb(255, 203, 107)">console</span><span class="token punctuation" style="color:rgb(199, 146, 234)">.</span><span class="token method function property-access" style="color:rgb(130, 170, 255)">log</span><span class="token punctuation" style="color:rgb(199, 146, 234)">(</span><span class="token known-class-name class-name" style="color:rgb(255, 203, 107)">JSON</span><span class="token punctuation" style="color:rgb(199, 146, 234)">.</span><span class="token method function property-access" style="color:rgb(130, 170, 255)">stringify</span><span class="token punctuation" style="color:rgb(199, 146, 234)">(</span><span class="token plain">process</span><span class="token punctuation" style="color:rgb(199, 146, 234)">.</span><span class="token property-access">env</span><span class="token punctuation" style="color:rgb(199, 146, 234)">)</span><span class="token punctuation" style="color:rgb(199, 146, 234)">)</span><span class="token punctuation" style="color:rgb(199, 146, 234)">;</span><br></span></code></pre></div></div>
<p>First, we use <code>node</code> to run a Javascript file <code>envfile.cjs</code> that returns a string or JSON representation of the <code>.env</code>
file. Then, we use <code>jsondecode</code> to read the JSON object or interpret the string as JSON to create a local object with the
<code>.env</code> variables as its attributes. Finally, we can retrieve the values of the <code>.env</code> variables by accessing them from
the <code>envfile</code> object.</p>
<p>Have additional questions or feedback? Feel free to reach out on our <a href="https://discord.gg/zZ6sWVg6NT" target="_blank" rel="noopener noreferrer" class="">Discord server</a>.</p>]]></content:encoded>
            <category>environment-variables</category>
            <category>env-file</category>
            <category>dotenv</category>
        </item>
        <item>
            <title><![CDATA[Why Atlas doesn't detect PostgreSQL event_trigger objects when the search_path parameter is set]]></title>
            <link>https://atlasgo.io/faq/event-trigger-search-path</link>
            <guid>https://atlasgo.io/faq/event-trigger-search-path</guid>
            <pubDate>Fri, 20 Nov 2026 20:08:41 GMT</pubDate>
            <description><![CDATA[Learn why Atlas doesn't detect PostgreSQL event_trigger objects when using search_path parameter and how to fix it.]]></description>
            <content:encoded><![CDATA[<p>Why does Atlas not detect PostgreSQL <code>event_trigger</code> objects when using <code>--dev-url</code> with <code>search_path=public</code>?</p>
<h3 class="anchor anchorTargetStickyNavbar_SAay" id="answer">Answer<a href="https://atlasgo.io/faq/event-trigger-search-path#answer" class="hash-link" aria-label="Direct link to Answer" title="Direct link to Answer" translate="no">​</a></h3>
<p>When running Atlas against a PostgreSQL database with a dev-URL that includes <code>search_path=public</code>, you may notice that <code>event_trigger</code> objects are not included in the generated migration. This happens because:</p>
<ul>
<li class="">The <code>search_path</code> parameter scopes Atlas to inspect only a specific schema</li>
<li class=""><code>event_trigger</code> objects (like extensions) are database-level objects, not schema-scoped</li>
<li class="">As a result, they are excluded when Atlas inspects only within a schema scope</li>
</ul>
<h3 class="anchor anchorTargetStickyNavbar_SAay" id="solution">Solution<a href="https://atlasgo.io/faq/event-trigger-search-path#solution" class="hash-link" aria-label="Direct link to Solution" title="Direct link to Solution" translate="no">​</a></h3>
<p>Remove the <code>search_path</code> parameter from the <code>--dev-url</code> to ensure Atlas inspects at the database level. Here are examples of both problematic and correct configurations:</p>
<div class="theme-tabs-container tabs-container tabList_M0Dn"><ul role="tablist" aria-orientation="horizontal" class="tabs"><li role="tab" tabindex="0" aria-selected="true" class="tabs__item tabItem_ysIP tabs__item--active">Correct (database-scoped)</li><li role="tab" tabindex="-1" aria-selected="false" class="tabs__item tabItem_ysIP">Problematic (schema-scoped)</li></ul><div class="margin-top--md"><div role="tabpanel" class="tabItem_OMyP"><div class="language-shell codeBlockContainer_ZGJx theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockContent_kX1v"><pre tabindex="0" class="prism-code language-shell codeBlock_TAPP thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_AdAo"><span class="token-line" style="color:#bfc7d5"><span class="token comment" style="color:rgb(105, 112, 152);font-style:italic"># This will detect event_trigger objects</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">atlas migrate </span><span class="token function" style="color:rgb(130, 170, 255)">diff</span><span class="token plain"> --dev-url </span><span class="token string" style="color:rgb(195, 232, 141)">"docker://postgres/16/dev"</span><br></span></code></pre></div></div></div><div role="tabpanel" class="tabItem_OMyP" hidden=""><div class="language-shell codeBlockContainer_ZGJx theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockContent_kX1v"><pre tabindex="0" class="prism-code language-shell codeBlock_TAPP thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_AdAo"><span class="token-line" style="color:#bfc7d5"><span class="token comment" style="color:rgb(105, 112, 152);font-style:italic"># This will NOT detect event_trigger objects</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">atlas migrate </span><span class="token function" style="color:rgb(130, 170, 255)">diff</span><span class="token plain"> --dev-url </span><span class="token string" style="color:rgb(195, 232, 141)">"docker://postgres/16/dev?search_path=public"</span><br></span></code></pre></div></div></div></div></div>
<h3 class="anchor anchorTargetStickyNavbar_SAay" id="configuration-file-example">Configuration File Example<a href="https://atlasgo.io/faq/event-trigger-search-path#configuration-file-example" class="hash-link" aria-label="Direct link to Configuration File Example" title="Direct link to Configuration File Example" translate="no">​</a></h3>
<p>The same principle applies when using an <code>atlas.hcl</code> configuration file:</p>
<div class="theme-tabs-container tabs-container tabList_M0Dn"><ul role="tablist" aria-orientation="horizontal" class="tabs"><li role="tab" tabindex="0" aria-selected="true" class="tabs__item tabItem_ysIP tabs__item--active">Correct</li><li role="tab" tabindex="-1" aria-selected="false" class="tabs__item tabItem_ysIP">Problematic</li></ul><div class="margin-top--md"><div role="tabpanel" class="tabItem_OMyP"><div class="language-hcl codeBlockContainer_ZGJx theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockTitle_L5qy">atlas.hcl</div><div class="codeBlockContent_kX1v"><pre tabindex="0" class="prism-code language-hcl codeBlock_TAPP thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_AdAo"><span class="token-line" style="color:#bfc7d5"><span class="token plain">env </span><span class="token string" style="color:rgb(195, 232, 141)">"local"</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token property">dev</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">=</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"docker://postgres/16/dev"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token comment" style="color:rgb(105, 112, 152);font-style:italic">// ... other configuration</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token punctuation" style="color:rgb(199, 146, 234)">}</span><br></span></code></pre></div></div></div><div role="tabpanel" class="tabItem_OMyP" hidden=""><div class="language-hcl codeBlockContainer_ZGJx theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockTitle_L5qy">atlas.hcl</div><div class="codeBlockContent_kX1v"><pre tabindex="0" class="prism-code language-hcl codeBlock_TAPP thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_AdAo"><span class="token-line" style="color:#bfc7d5"><span class="token plain">env </span><span class="token string" style="color:rgb(195, 232, 141)">"local"</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token property">dev</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">=</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"docker://postgres/16/dev?search_path=public"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token comment" style="color:rgb(105, 112, 152);font-style:italic">// ... other configuration</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token punctuation" style="color:rgb(199, 146, 234)">}</span><br></span></code></pre></div></div></div></div></div>
<h3 class="anchor anchorTargetStickyNavbar_SAay" id="why-this-matters">Why This Matters<a href="https://atlasgo.io/faq/event-trigger-search-path#why-this-matters" class="hash-link" aria-label="Direct link to Why This Matters" title="Direct link to Why This Matters" translate="no">​</a></h3>
<p>Event triggers are powerful PostgreSQL features that execute functions in response to DDL events. For example:</p>
<div class="language-sql codeBlockContainer_ZGJx theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockContent_kX1v"><pre tabindex="0" class="prism-code language-sql codeBlock_TAPP thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_AdAo"><span class="token-line" style="color:#bfc7d5"><span class="token comment" style="color:rgb(105, 112, 152);font-style:italic">-- Create an event trigger that logs table creation</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token keyword" style="font-style:italic">CREATE</span><span class="token plain"> </span><span class="token operator" style="color:rgb(137, 221, 255)">OR</span><span class="token plain"> </span><span class="token keyword" style="font-style:italic">REPLACE</span><span class="token plain"> </span><span class="token keyword" style="font-style:italic">FUNCTION</span><span class="token plain"> record_table_creation</span><span class="token punctuation" style="color:rgb(199, 146, 234)">(</span><span class="token punctuation" style="color:rgb(199, 146, 234)">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token keyword" style="font-style:italic">RETURNS</span><span class="token plain"> event_trigger </span><span class="token keyword" style="font-style:italic">AS</span><span class="token plain"> $$</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token keyword" style="font-style:italic">BEGIN</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  RAISE NOTICE </span><span class="token string" style="color:rgb(195, 232, 141)">'Table created: %'</span><span class="token punctuation" style="color:rgb(199, 146, 234)">,</span><span class="token plain"> tg_tag</span><span class="token punctuation" style="color:rgb(199, 146, 234)">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token keyword" style="font-style:italic">END</span><span class="token punctuation" style="color:rgb(199, 146, 234)">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">$$ </span><span class="token keyword" style="font-style:italic">LANGUAGE</span><span class="token plain"> plpgsql</span><span class="token punctuation" style="color:rgb(199, 146, 234)">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token keyword" style="font-style:italic">CREATE</span><span class="token plain"> EVENT </span><span class="token keyword" style="font-style:italic">TRIGGER</span><span class="token plain"> record_table_creation</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token keyword" style="font-style:italic">ON</span><span class="token plain"> ddl_command_start</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token keyword" style="font-style:italic">WHEN</span><span class="token plain"> TAG </span><span class="token operator" style="color:rgb(137, 221, 255)">IN</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">(</span><span class="token string" style="color:rgb(195, 232, 141)">'CREATE TABLE'</span><span class="token punctuation" style="color:rgb(199, 146, 234)">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token keyword" style="font-style:italic">EXECUTE</span><span class="token plain"> </span><span class="token keyword" style="font-style:italic">FUNCTION</span><span class="token plain"> record_table_creation</span><span class="token punctuation" style="color:rgb(199, 146, 234)">(</span><span class="token punctuation" style="color:rgb(199, 146, 234)">)</span><span class="token punctuation" style="color:rgb(199, 146, 234)">;</span><br></span></code></pre></div></div>
<p>When these objects exist in your database but are not detected by Atlas due to schema scoping, your migration plans will be incomplete, potentially leading to inconsistencies between environments.</p>
<h3 class="anchor anchorTargetStickyNavbar_SAay" id="related-information">Related Information<a href="https://atlasgo.io/faq/event-trigger-search-path#related-information" class="hash-link" aria-label="Direct link to Related Information" title="Direct link to Related Information" translate="no">​</a></h3>
<p>For more details about database-level vs schema-level objects in PostgreSQL with Atlas, see:</p>
<ul>
<li class=""><a class="" href="https://atlasgo.io/faq/postgres-extensions">PostgreSQL Extensions FAQ</a> - Extensions have the same database-level scoping behavior</li>
<li class=""><a class="" href="https://atlasgo.io/concepts/url">Database URL concepts</a> - Understanding URL parameters and their effects</li>
</ul>]]></content:encoded>
            <category>postgres</category>
            <category>event_trigger</category>
            <category>search_path</category>
            <category>dev-url</category>
            <category>database scope</category>
        </item>
        <item>
            <title><![CDATA[Error: extension has no installation script nor update path for version]]></title>
            <link>https://atlasgo.io/faq/extension-version-mismatch</link>
            <guid>https://atlasgo.io/faq/extension-version-mismatch</guid>
            <pubDate>Fri, 20 Nov 2026 20:08:41 GMT</pubDate>
            <description><![CDATA[Learn how to resolve extension version mismatch errors between your database and dev-database.]]></description>
            <content:encoded><![CDATA[<h3 class="anchor anchorTargetStickyNavbar_SAay" id="question">Question<a href="https://atlasgo.io/faq/extension-version-mismatch#question" class="hash-link" aria-label="Direct link to Question" title="Direct link to Question" translate="no">​</a></h3>
<p>Why does <code>atlas schema apply</code> / <code>atlas schema plan</code> fail with an error like this when working with PostgreSQL extensions?</p>
<div class="theme-admonition theme-admonition-danger admonition_IZjC alert alert--danger"><div class="admonitionHeading_uVvU"><span class="admonitionIcon_HiR3"><svg viewBox="0 0 12 16"><path fill-rule="evenodd" d="M5.05.31c.81 2.17.41 3.38-.52 4.31C3.55 5.67 1.98 6.45.9 7.98c-1.45 2.05-1.7 6.53 3.53 7.7-2.2-1.16-2.67-4.52-.3-6.61-.61 2.03.53 3.33 1.94 2.86 1.39-.47 2.3.53 2.27 1.67-.02.78-.31 1.44-1.13 1.81 3.42-.59 4.78-3.42 4.78-5.56 0-2.84-2.53-3.22-1.25-5.61-1.52.13-2.03 1.13-1.89 2.75.09 1.08-1.02 1.8-1.86 1.33-.67-.41-.66-1.19-.06-1.78C8.18 5.31 8.68 2.45 5.05.32L5.03.3l.02.01z"></path></svg></span>danger</div><div class="admonitionContent_bl22"><p><code>Error: create extension "postgis_topology": pq: extension "postgis_topology" has no installation script nor update path for version "3.4.3"</code></p></div></div>
<h3 class="anchor anchorTargetStickyNavbar_SAay" id="answer">Answer<a href="https://atlasgo.io/faq/extension-version-mismatch#answer" class="hash-link" aria-label="Direct link to Answer" title="Direct link to Answer" translate="no">​</a></h3>
<p>This error occurs when there's a version mismatch between the extension installed in your target database (current state)
and the extension available in your local <a class="" href="https://atlasgo.io/concepts/dev-database"><strong>dev-database</strong></a>.</p>
<p>To make sure migration plans are safe, Atlas does the following:</p>
<ol>
<li class="">It first creates the current state (the database schema) on the dev-database</li>
<li class="">Applies the planned migration to it</li>
<li class="">Inspects the result and checks if it matches the desired target state</li>
</ol>
<p>This simulation helps Atlas detect potential issues before touching your actual database while ensuring the migration plans
actually bring the schema to the desired state.</p>
<p>During stages 1 and 2, Atlas needs to recreate your schema's extensions in the dev-database. If the dev-database doesn't
have installation scripts for the exact extension versions (whether from your current schema or desired state), PostgreSQL returns this error.</p>
<p>For example, if your production database has PostGIS 3.4.3 but your dev-database Docker image only includes PostGIS 3.5.x,
Atlas cannot create an identical schema in the dev-database for validation.</p>
<h3 class="anchor anchorTargetStickyNavbar_SAay" id="solutions">Solutions<a href="https://atlasgo.io/faq/extension-version-mismatch#solutions" class="hash-link" aria-label="Direct link to Solutions" title="Direct link to Solutions" translate="no">​</a></h3>
<p>There are several approaches to resolve this issue:</p>
<h4 class="anchor anchorTargetStickyNavbar_SAay" id="1-use-a-dev-database-with-matching-extension-versions">1. Use a dev-database with matching extension versions<a href="https://atlasgo.io/faq/extension-version-mismatch#1-use-a-dev-database-with-matching-extension-versions" class="hash-link" aria-label="Direct link to 1. Use a dev-database with matching extension versions" title="Direct link to 1. Use a dev-database with matching extension versions" translate="no">​</a></h4>
<p>The most reliable solution is to ensure your dev-database has the same extension versions as your target database. You can:</p>
<p><strong>Build a custom Docker image</strong> with the exact PostgreSQL and extension versions:</p>
<div class="language-hcl codeBlockContainer_ZGJx theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockTitle_L5qy">atlas.hcl</div><div class="codeBlockContent_kX1v"><pre tabindex="0" class="prism-code language-hcl codeBlock_TAPP thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_AdAo"><span class="token-line" style="color:#bfc7d5"><span class="token plain">docker </span><span class="token string" style="color:rgb(195, 232, 141)">"postgres"</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"dev"</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token property">image</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">=</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"postgres:16-custom"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token keyword" style="font-style:italic">build</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">    </span><span class="token property">context</span><span class="token plain">    </span><span class="token punctuation" style="color:rgb(199, 146, 234)">=</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"."</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">    </span><span class="token property">dockerfile</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">=</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"Dockerfile"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token punctuation" style="color:rgb(199, 146, 234)">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token punctuation" style="color:rgb(199, 146, 234)">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">env </span><span class="token string" style="color:rgb(195, 232, 141)">"dev"</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token property">url</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">=</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"postgres://user:pass@host:5432/mydb"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token property">dev</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">=</span><span class="token plain"> docker.postgres.dev.url</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token punctuation" style="color:rgb(199, 146, 234)">}</span><br></span></code></pre></div></div>
<div class="language-dockerfile codeBlockContainer_ZGJx theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockTitle_L5qy">Dockerfile</div><div class="codeBlockContent_kX1v"><pre tabindex="0" class="prism-code language-dockerfile codeBlock_TAPP thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_AdAo"><span class="token-line" style="color:#bfc7d5"><span class="token instruction keyword" style="font-style:italic">FROM</span><span class="token instruction"> postgres:16.8</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token instruction keyword" style="font-style:italic">RUN</span><span class="token instruction"> apt-get update &amp;&amp; apt-get install -y </span><span class="token instruction operator" style="color:rgb(137, 221, 255)">\</span><span class="token instruction"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token instruction">    postgresql-16-postgis-3.4.3 </span><span class="token instruction operator" style="color:rgb(137, 221, 255)">\</span><span class="token instruction"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token instruction">    &amp;&amp; rm -rf /var/lib/apt/lists/*</span><br></span></code></pre></div></div>
<h4 class="anchor anchorTargetStickyNavbar_SAay" id="2-use-a-compatible-pre-built-image">2. Use a compatible pre-built image<a href="https://atlasgo.io/faq/extension-version-mismatch#2-use-a-compatible-pre-built-image" class="hash-link" aria-label="Direct link to 2. Use a compatible pre-built image" title="Direct link to 2. Use a compatible pre-built image" translate="no">​</a></h4>
<p>For PostGIS specifically, you can use the PostGIS Docker images that match your major version:</p>
<div class="language-hcl codeBlockContainer_ZGJx theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockTitle_L5qy">atlas.hcl</div><div class="codeBlockContent_kX1v"><pre tabindex="0" class="prism-code language-hcl codeBlock_TAPP thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_AdAo"><span class="token-line" style="color:#bfc7d5"><span class="token plain">env </span><span class="token string" style="color:rgb(195, 232, 141)">"dev"</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token property">url</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">=</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"postgres://user:pass@host:5432/mydb"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token property">dev</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">=</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"docker://postgis/16-3.4/dev"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token punctuation" style="color:rgb(199, 146, 234)">}</span><br></span></code></pre></div></div>
<h4 class="anchor anchorTargetStickyNavbar_SAay" id="3-use-version-any-for-postgis-extensions">3. Use version 'ANY' for PostGIS extensions<a href="https://atlasgo.io/faq/extension-version-mismatch#3-use-version-any-for-postgis-extensions" class="hash-link" aria-label="Direct link to 3. Use version 'ANY' for PostGIS extensions" title="Direct link to 3. Use version 'ANY' for PostGIS extensions" translate="no">​</a></h4>
<p>PostGIS supports installing any available version when you specify <code>version = "ANY"</code>. This tells PostGIS to install whatever version is available in the system:</p>
<div class="language-hcl codeBlockContainer_ZGJx theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockTitle_L5qy">schema.hcl</div><div class="codeBlockContent_kX1v"><pre tabindex="0" class="prism-code language-hcl codeBlock_TAPP thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_AdAo"><span class="token-line" style="color:#bfc7d5"><span class="token plain">extension </span><span class="token string" style="color:rgb(195, 232, 141)">"postgis"</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token property">schema</span><span class="token plain">  </span><span class="token punctuation" style="color:rgb(199, 146, 234)">=</span><span class="token plain"> schema.public</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token property">version</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">=</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"ANY"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token punctuation" style="color:rgb(199, 146, 234)">}</span><br></span></code></pre></div></div>
<p>This approach works well when exact version matching isn't critical for your use case. PostGIS will store the version as "ANY" in the database metadata.</p>
<h4 class="anchor anchorTargetStickyNavbar_SAay" id="4-exclude-extension-versions-from-atlas-management">4. Exclude extension versions from Atlas management<a href="https://atlasgo.io/faq/extension-version-mismatch#4-exclude-extension-versions-from-atlas-management" class="hash-link" aria-label="Direct link to 4. Exclude extension versions from Atlas management" title="Direct link to 4. Exclude extension versions from Atlas management" translate="no">​</a></h4>
<p>You can tell Atlas to ignore extension versions entirely using the <code>exclude</code> attribute:</p>
<div class="language-hcl codeBlockContainer_ZGJx theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockTitle_L5qy">atlas.hcl</div><div class="codeBlockContent_kX1v"><pre tabindex="0" class="prism-code language-hcl codeBlock_TAPP thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_AdAo"><span class="token-line" style="color:#bfc7d5"><span class="token plain">env </span><span class="token string" style="color:rgb(195, 232, 141)">"production"</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token property">url</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">=</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"postgres://user:pass@host:5432/mydb"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token property">dev</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">=</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"docker://postgres/16/dev"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token property">exclude</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">=</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">[</span><span class="token string" style="color:rgb(195, 232, 141)">"*[type=extension].version"</span><span class="token punctuation" style="color:rgb(199, 146, 234)">]</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token punctuation" style="color:rgb(199, 146, 234)">}</span><br></span></code></pre></div></div>
<p>Or use the <code>--exclude</code> flag when running commands:</p>
<div class="language-bash codeBlockContainer_ZGJx theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockContent_kX1v"><pre tabindex="0" class="prism-code language-bash codeBlock_TAPP thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_AdAo"><span class="token-line" style="color:#bfc7d5"><span class="token plain">atlas schema apply </span><span class="token parameter variable" style="color:rgb(191, 199, 213)">--env</span><span class="token plain"> production </span><span class="token parameter variable" style="color:rgb(191, 199, 213)">--exclude</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"*[type=extension].version"</span><br></span></code></pre></div></div>
<p>This allows Atlas to manage extensions without caring about specific versions, avoiding version mismatch errors while still tracking that extensions exist.</p>
<h4 class="anchor anchorTargetStickyNavbar_SAay" id="5-manage-extensions-separately">5. Manage extensions separately<a href="https://atlasgo.io/faq/extension-version-mismatch#5-manage-extensions-separately" class="hash-link" aria-label="Direct link to 5. Manage extensions separately" title="Direct link to 5. Manage extensions separately" translate="no">​</a></h4>
<p>As mentioned in our <a class="" href="https://atlasgo.io/faq/manage-extension-only">extension management guide</a>, you can also manage extensions outside of Atlas migrations.
This approach treats extension upgrades as infrastructure changes rather than schema migrations:</p>
<ol>
<li class="">Remove extension definitions from your schema files</li>
<li class="">Manage extensions through a separate deployment process</li>
<li class="">Let Atlas handle only tables, indexes, and other schema objects</li>
</ol>
<p>This avoids version conflicts but requires additional coordination for extension management.</p>]]></content:encoded>
            <category>faq</category>
            <category>postgres-extensions</category>
            <category>postgis</category>
            <category>dev-database</category>
        </item>
        <item>
            <title><![CDATA[Using Geometry types (PostGIS) with Atlas]]></title>
            <link>https://atlasgo.io/faq/geometry-type</link>
            <guid>https://atlasgo.io/faq/geometry-type</guid>
            <pubDate>Fri, 20 Nov 2026 20:08:41 GMT</pubDate>
            <description><![CDATA[Learn how to integrate the PostGIS extension into your schema to use the geometry type with SQLAlchemy.]]></description>
            <content:encoded><![CDATA[<p>PostGIS is a spatial database extension for PostgreSQL. It adds support for geometric objects, enabling the processing
of spatial data like points, lines, and polygons. After installing PostGIS, the <code>GEOMETRY</code> data type can be used to define
tables that capture geo-spatial data, for example:</p>
<div class="language-sql codeBlockContainer_ZGJx theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockContent_kX1v"><pre tabindex="0" class="prism-code language-sql codeBlock_TAPP thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_AdAo"><span class="token-line" style="color:#bfc7d5"><span class="token comment" style="color:rgb(105, 112, 152);font-style:italic">-- Create extension "postgis"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token keyword" style="font-style:italic">CREATE</span><span class="token plain"> EXTENSION </span><span class="token string" style="color:rgb(195, 232, 141)">"postgis"</span><span class="token plain"> </span><span class="token keyword" style="font-style:italic">WITH</span><span class="token plain"> </span><span class="token keyword" style="font-style:italic">SCHEMA</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"public"</span><span class="token plain"> VERSION </span><span class="token string" style="color:rgb(195, 232, 141)">"3.5.2"</span><span class="token punctuation" style="color:rgb(199, 146, 234)">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token comment" style="color:rgb(105, 112, 152);font-style:italic">-- Create "users" table</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token keyword" style="font-style:italic">CREATE</span><span class="token plain"> </span><span class="token keyword" style="font-style:italic">TABLE</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"public"</span><span class="token punctuation" style="color:rgb(199, 146, 234)">.</span><span class="token string" style="color:rgb(195, 232, 141)">"users"</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">(</span><span class="token string" style="color:rgb(195, 232, 141)">"id"</span><span class="token plain"> </span><span class="token keyword" style="font-style:italic">serial</span><span class="token plain"> </span><span class="token operator" style="color:rgb(137, 221, 255)">NOT</span><span class="token plain"> </span><span class="token boolean" style="color:rgb(255, 88, 116)">NULL</span><span class="token punctuation" style="color:rgb(199, 146, 234)">,</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"name"</span><span class="token plain"> </span><span class="token keyword" style="font-style:italic">character</span><span class="token plain"> </span><span class="token keyword" style="font-style:italic">varying</span><span class="token plain"> </span><span class="token operator" style="color:rgb(137, 221, 255)">NOT</span><span class="token plain"> </span><span class="token boolean" style="color:rgb(255, 88, 116)">NULL</span><span class="token punctuation" style="color:rgb(199, 146, 234)">,</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"email"</span><span class="token plain"> </span><span class="token keyword" style="font-style:italic">character</span><span class="token plain"> </span><span class="token keyword" style="font-style:italic">varying</span><span class="token plain"> </span><span class="token operator" style="color:rgb(137, 221, 255)">NOT</span><span class="token plain"> </span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token boolean" style="color:rgb(255, 88, 116)">NULL</span><span class="token punctuation" style="color:rgb(199, 146, 234)">,</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"address"</span><span class="token plain"> </span><span class="token keyword" style="font-style:italic">public</span><span class="token punctuation" style="color:rgb(199, 146, 234)">.</span><span class="token keyword" style="font-style:italic">geometry</span><span class="token punctuation" style="color:rgb(199, 146, 234)">(</span><span class="token keyword" style="font-style:italic">Point</span><span class="token punctuation" style="color:rgb(199, 146, 234)">,</span><span class="token number" style="color:rgb(247, 140, 108)">4326</span><span class="token punctuation" style="color:rgb(199, 146, 234)">)</span><span class="token plain"> </span><span class="token operator" style="color:rgb(137, 221, 255)">NOT</span><span class="token plain"> </span><span class="token boolean" style="color:rgb(255, 88, 116)">NULL</span><span class="token punctuation" style="color:rgb(199, 146, 234)">,</span><span class="token plain"> </span><span class="token keyword" style="font-style:italic">PRIMARY</span><span class="token plain"> </span><span class="token keyword" style="font-style:italic">KEY</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">(</span><span class="token string" style="color:rgb(195, 232, 141)">"id"</span><span class="token punctuation" style="color:rgb(199, 146, 234)">)</span><span class="token punctuation" style="color:rgb(199, 146, 234)">)</span><span class="token punctuation" style="color:rgb(199, 146, 234)">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token comment" style="color:rgb(105, 112, 152);font-style:italic">-- Create index "idx_users_address" to table: "users"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token keyword" style="font-style:italic">CREATE</span><span class="token plain"> </span><span class="token keyword" style="font-style:italic">INDEX</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"idx_users_address"</span><span class="token plain"> </span><span class="token keyword" style="font-style:italic">ON</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"public"</span><span class="token punctuation" style="color:rgb(199, 146, 234)">.</span><span class="token string" style="color:rgb(195, 232, 141)">"users"</span><span class="token plain"> </span><span class="token keyword" style="font-style:italic">USING</span><span class="token plain"> gist </span><span class="token punctuation" style="color:rgb(199, 146, 234)">(</span><span class="token string" style="color:rgb(195, 232, 141)">"address"</span><span class="token punctuation" style="color:rgb(199, 146, 234)">)</span><span class="token punctuation" style="color:rgb(199, 146, 234)">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token comment" style="color:rgb(105, 112, 152);font-style:italic">-- Create index "ix_users_id" to table: "users"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token keyword" style="font-style:italic">CREATE</span><span class="token plain"> </span><span class="token keyword" style="font-style:italic">INDEX</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"ix_users_id"</span><span class="token plain"> </span><span class="token keyword" style="font-style:italic">ON</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"public"</span><span class="token punctuation" style="color:rgb(199, 146, 234)">.</span><span class="token string" style="color:rgb(195, 232, 141)">"users"</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">(</span><span class="token string" style="color:rgb(195, 232, 141)">"id"</span><span class="token punctuation" style="color:rgb(199, 146, 234)">)</span><span class="token punctuation" style="color:rgb(199, 146, 234)">;</span><br></span></code></pre></div></div>
<br>
<p>When using the <code>GEOMETRY</code> type, there are two common errors you may experience upon inspecting your schema with Atlas:</p>
<h2 class="anchor anchorTargetStickyNavbar_SAay" id="pq-extension-postgis-is-not-available"><code>pq: extension "postgis" is not available</code><a href="https://atlasgo.io/faq/geometry-type#pq-extension-postgis-is-not-available" class="hash-link" aria-label="Direct link to pq-extension-postgis-is-not-available" title="Direct link to pq-extension-postgis-is-not-available" translate="no">​</a></h2>
<p>This error suggests that your local <a class="" href="https://atlasgo.io/concepts/dev-database">dev database</a> cannot enable the PostGIS extension.</p>
<div class="theme-admonition theme-admonition-note admonition_IZjC alert alert--secondary"><div class="admonitionHeading_uVvU"><span class="admonitionIcon_HiR3"><svg viewBox="0 0 14 16"><path fill-rule="evenodd" d="M6.3 5.69a.942.942 0 0 1-.28-.7c0-.28.09-.52.28-.7.19-.18.42-.28.7-.28.28 0 .52.09.7.28.18.19.28.42.28.7 0 .28-.09.52-.28.7a1 1 0 0 1-.7.3c-.28 0-.52-.11-.7-.3zM8 7.99c-.02-.25-.11-.48-.31-.69-.2-.19-.42-.3-.69-.31H6c-.27.02-.48.13-.69.31-.2.2-.3.44-.31.69h1v3c.02.27.11.5.31.69.2.2.42.31.69.31h1c.27 0 .48-.11.69-.31.2-.19.3-.42.31-.69H8V7.98v.01zM7 2.3c-3.14 0-5.7 2.54-5.7 5.68 0 3.14 2.56 5.7 5.7 5.7s5.7-2.55 5.7-5.7c0-3.15-2.56-5.69-5.7-5.69v.01zM7 .98c3.86 0 7 3.14 7 7s-3.14 7-7 7-7-3.12-7-7 3.14-7 7-7z"></path></svg></span>note</div><div class="admonitionContent_bl22"><p>This error can also be related to the loading of the extension itself. If you still experience an error after following
these instructions, try following those for the <a class="" href="https://atlasgo.io/faq/geometry-type#pq-type-geometry-does-not-exist">second common error</a>.</p></div></div>
<p>When comparing the  current state of your schema to the desired state, Atlas requires access to a running empty database to process
the migration. To enable a PostgreSQL extension, it must be available in a location the database can access.</p>
<p>This is typically done in one of two ways:</p>
<h3 class="anchor anchorTargetStickyNavbar_SAay" id="using-a-pre-built-docker-image">Using a pre-built docker image<a href="https://atlasgo.io/faq/geometry-type#using-a-pre-built-docker-image" class="hash-link" aria-label="Direct link to Using a pre-built docker image" title="Direct link to Using a pre-built docker image" translate="no">​</a></h3>
<p>In order to use the <code>GEOMETRY</code> type, we can use a PostGIS Docker image as the dev database.</p>
<p>The dev database URL can be provided via the <code>dev</code> attribute in the <code>atlas.hcl</code> configuration, e.g.:</p>
<div class="language-hcl codeBlockContainer_ZGJx theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockContent_kX1v"><pre tabindex="0" class="prism-code language-hcl codeBlock_TAPP thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_AdAo"><span class="token-line" style="color:#bfc7d5"><span class="token plain">env </span><span class="token string" style="color:rgb(195, 232, 141)">"example"</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token property">dev</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">=</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"docker://postgis/latest/dev"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token comment" style="color:rgb(105, 112, 152);font-style:italic">// .. redacted for brevity</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token punctuation" style="color:rgb(199, 146, 234)">}</span><br></span></code></pre></div></div>
<p>Alternatively, use the <code>--dev-url</code> command line flag to set the dev database:</p>
<div class="language-shell codeBlockContainer_ZGJx theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockContent_kX1v"><pre tabindex="0" class="prism-code language-shell codeBlock_TAPP thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_AdAo"><span class="token-line" style="color:#bfc7d5"><span class="token plain">atlas migrate </span><span class="token function" style="color:rgb(130, 170, 255)">diff</span><span class="token plain"> </span><span class="token parameter variable" style="color:rgb(191, 199, 213)">--env</span><span class="token plain"> example --dev-url </span><span class="token string" style="color:rgb(195, 232, 141)">"docker://postgis/latest/dev"</span><br></span></code></pre></div></div>
<h3 class="anchor anchorTargetStickyNavbar_SAay" id="providing-a-url-to-an-already-running-server-that-has-postgis-available">Providing a URL to an already running server that has PostGIS available<a href="https://atlasgo.io/faq/geometry-type#providing-a-url-to-an-already-running-server-that-has-postgis-available" class="hash-link" aria-label="Direct link to Providing a URL to an already running server that has PostGIS available" title="Direct link to Providing a URL to an already running server that has PostGIS available" translate="no">​</a></h3>
<p>If you already have a running server with PostGIS enabled, simply replace the <code>dev</code> attribute with your server's URL, e.g.:</p>
<div class="theme-tabs-container tabs-container tabList_M0Dn"><ul role="tablist" aria-orientation="horizontal" class="tabs"><li role="tab" tabindex="0" aria-selected="true" class="tabs__item tabItem_ysIP tabs__item--active">HCL</li><li role="tab" tabindex="-1" aria-selected="false" class="tabs__item tabItem_ysIP">Command Line</li></ul><div class="margin-top--md"><div role="tabpanel" class="tabItem_OMyP"><div class="language-hcl codeBlockContainer_ZGJx theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockContent_kX1v"><pre tabindex="0" class="prism-code language-hcl codeBlock_TAPP thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_AdAo"><span class="token-line" style="color:#bfc7d5"><span class="token plain">env </span><span class="token string" style="color:rgb(195, 232, 141)">"example"</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token property">dev</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">=</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"postgres://user:pass@hostname:5432/database"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token comment" style="color:rgb(105, 112, 152);font-style:italic">// .. redacted for brevity</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token punctuation" style="color:rgb(199, 146, 234)">}</span><br></span></code></pre></div></div></div><div role="tabpanel" class="tabItem_OMyP" hidden=""><div class="language-shell codeBlockContainer_ZGJx theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockContent_kX1v"><pre tabindex="0" class="prism-code language-shell codeBlock_TAPP thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_AdAo"><span class="token-line" style="color:#bfc7d5"><span class="token plain">atlas migrate </span><span class="token function" style="color:rgb(130, 170, 255)">diff</span><span class="token plain"> </span><span class="token parameter variable" style="color:rgb(191, 199, 213)">--env</span><span class="token plain"> example --dev-url </span><span class="token string" style="color:rgb(195, 232, 141)">"postgres://user:pass@hostname:5432/database&amp;sslmode=disable"</span><br></span></code></pre></div></div></div></div></div>
<p>Additionally, extensions are database-level objects, meaning they exist outside the scope of a specific schema. Therefore,
when defining your dev database, there should not be a <code>search_path</code> attribute in its URL, as this variable defines a schema scope.</p>
<h2 class="anchor anchorTargetStickyNavbar_SAay" id="pq-type-geometry-does-not-exist"><code>pq: type "geometry" does not exist</code><a href="https://atlasgo.io/faq/geometry-type#pq-type-geometry-does-not-exist" class="hash-link" aria-label="Direct link to pq-type-geometry-does-not-exist" title="Direct link to pq-type-geometry-does-not-exist" translate="no">​</a></h2>
<p>This error suggests that the PostGIS extension for PostgreSQL has not been loaded to your database. To properly include the
extension in your database, add it to the start of your SQL or HCL schema definition.</p>
<div class="theme-tabs-container tabs-container tabList_M0Dn"><ul role="tablist" aria-orientation="horizontal" class="tabs"><li role="tab" tabindex="0" aria-selected="true" class="tabs__item tabItem_ysIP tabs__item--active">SQL</li><li role="tab" tabindex="-1" aria-selected="false" class="tabs__item tabItem_ysIP">HCL</li></ul><div class="margin-top--md"><div role="tabpanel" class="tabItem_OMyP"><div class="language-sql codeBlockContainer_ZGJx theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockTitle_L5qy">schema.sql</div><div class="codeBlockContent_kX1v"><pre tabindex="0" class="prism-code language-sql codeBlock_TAPP thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_AdAo"><span class="token-line" style="color:#bfc7d5"><span class="token keyword" style="font-style:italic">CREATE</span><span class="token plain"> EXTENSION postgis</span><span class="token punctuation" style="color:rgb(199, 146, 234)">;</span><br></span></code></pre></div></div></div><div role="tabpanel" class="tabItem_OMyP" hidden=""><div class="language-hcl codeBlockContainer_ZGJx theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockTitle_L5qy">schema.hcl</div><div class="codeBlockContent_kX1v"><pre tabindex="0" class="prism-code language-hcl codeBlock_TAPP thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_AdAo"><span class="token-line" style="color:#bfc7d5"><span class="token plain">schema </span><span class="token string" style="color:rgb(195, 232, 141)">"public"</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">{</span><span class="token punctuation" style="color:rgb(199, 146, 234)">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">extension </span><span class="token string" style="color:rgb(195, 232, 141)">"postgis"</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token property">schema</span><span class="token plain">  </span><span class="token punctuation" style="color:rgb(199, 146, 234)">=</span><span class="token plain"> schema.public</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token property">version</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">=</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"3.4.2"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token property">comment</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">=</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"PostGIS geometry and geography spatial types and functions"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token punctuation" style="color:rgb(199, 146, 234)">}</span><br></span></code></pre></div></div></div></div></div>
<p>Now that the PostGIS extension is defined, it must be properly loaded into the database. The way to do so depends on the
configuration of your system – you may define your schema in SQL or HCL files, or you may use an ORM (e.g. SQLAlchemy)
to define your models.</p>
<h3 class="anchor anchorTargetStickyNavbar_SAay" id="no-orm-only-sqlhcl">No ORM (only SQL/HCL)<a href="https://atlasgo.io/faq/geometry-type#no-orm-only-sqlhcl" class="hash-link" aria-label="Direct link to No ORM (only SQL/HCL)" title="Direct link to No ORM (only SQL/HCL)" translate="no">​</a></h3>
<p>If there is no ORM to integrate into your system and your schema is defined in either a SQL or HCL file, you
can simply create an <code>atlas.hcl</code> file to connect your schema to your dev database.</p>
<div class="language-hcl codeBlockContainer_ZGJx theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockContent_kX1v"><pre tabindex="0" class="prism-code language-hcl codeBlock_TAPP thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_AdAo"><span class="token-line" style="color:#bfc7d5"><span class="token plain">env </span><span class="token string" style="color:rgb(195, 232, 141)">"local"</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token property">src</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">=</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"file://schema.sql"</span><span class="token plain">   </span><span class="token comment" style="color:rgb(105, 112, 152);font-style:italic">// schema file containing PostGIS extension creation</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token property">dev</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">=</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"docker://postgis/latest/dev"</span><span class="token plain">   </span><span class="token comment" style="color:rgb(105, 112, 152);font-style:italic">// dev database</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token punctuation" style="color:rgb(199, 146, 234)">}</span><br></span></code></pre></div></div>
<h3 class="anchor anchorTargetStickyNavbar_SAay" id="using-an-orm">Using an ORM<a href="https://atlasgo.io/faq/geometry-type#using-an-orm" class="hash-link" aria-label="Direct link to Using an ORM" title="Direct link to Using an ORM" translate="no">​</a></h3>
<p>To include both the PostGIS extension and ORM models, we configure Atlas to read the state of the schema from a Composite
Schema data source. We will use SQLAlchemy as our ORM in this example.</p>
<p>In order for Atlas to work alongside your ORM, you need to install the corresponding Atlas provider. For SQLAlchemy, run:</p>
<div class="language-bash codeBlockContainer_ZGJx theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockContent_kX1v"><pre tabindex="0" class="prism-code language-bash codeBlock_TAPP thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_AdAo"><span class="token-line" style="color:#bfc7d5"><span class="token plain">pip </span><span class="token function" style="color:rgb(130, 170, 255)">install</span><span class="token plain"> atlas-provider-sqlalchemy</span><br></span></code></pre></div></div>
<div class="theme-admonition theme-admonition-info admonition_IZjC alert alert--info"><div class="admonitionHeading_uVvU"><span class="admonitionIcon_HiR3"><svg viewBox="0 0 14 16"><path fill-rule="evenodd" d="M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"></path></svg></span>Other ORMs</div><div class="admonitionContent_bl22"><p>If you are using a different ORM, go to our <a href="https://atlasgo.io/orms" target="_blank" rel="noopener noreferrer" class="">ORMs Guide</a> for relevant syntax.</p></div></div>
<ol>
<li class="">In addition to creating the PostGIS extension in your SQL/HCL file, set up a file or directory containing your SQLAlchemy
models which contain the Geometry type, e.g.:</li>
</ol>
<div class="language-bash codeBlockContainer_ZGJx theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockContent_kX1v"><pre tabindex="0" class="prism-code language-bash codeBlock_TAPP thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_AdAo"><span class="token-line" style="color:#bfc7d5"><span class="token plain">project-directory</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">├── models.py</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">├── schema.sql</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">└── atlas.hcl</span><br></span></code></pre></div></div>
<ol start="2">
<li class="">In your <code>atlas.hcl</code> config file, add a <code>composite_schema</code> that includes both your extension definition and your models:</li>
</ol>
<div class="theme-tabs-container tabs-container tabList_M0Dn"><ul role="tablist" aria-orientation="horizontal" class="tabs"><li role="tab" tabindex="0" aria-selected="true" class="tabs__item tabItem_ysIP tabs__item--active">atlas.hcl</li><li role="tab" tabindex="-1" aria-selected="false" class="tabs__item tabItem_ysIP">(Example) schema.sql</li><li role="tab" tabindex="-1" aria-selected="false" class="tabs__item tabItem_ysIP">(Example) models.py using SQLAlchemy</li></ul><div class="margin-top--md"><div role="tabpanel" class="tabItem_OMyP"><div class="language-hcl codeBlockContainer_ZGJx theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockTitle_L5qy">atlas.hcl</div><div class="codeBlockContent_kX1v"><pre tabindex="0" class="prism-code language-hcl codeBlock_TAPP thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_AdAo"><span class="token-line" style="color:#bfc7d5"><span class="token keyword" style="font-style:italic">data </span><span class="token keyword type variable" style="font-style:italic;color:rgb(191, 199, 213)">"external_schema"</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"sqlalchemy"</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">    </span><span class="token property">program</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">=</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">[</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">        </span><span class="token string" style="color:rgb(195, 232, 141)">"atlas-provider-sqlalchemy"</span><span class="token plain">,</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">        </span><span class="token string" style="color:rgb(195, 232, 141)">"--path"</span><span class="token plain">, </span><span class="token string" style="color:rgb(195, 232, 141)">"./models.py"</span><span class="token plain">,   </span><span class="token comment" style="color:rgb(105, 112, 152);font-style:italic">// path to your SQLAlchemy models directory or file</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">        </span><span class="token string" style="color:rgb(195, 232, 141)">"--dialect"</span><span class="token plain">, </span><span class="token string" style="color:rgb(195, 232, 141)">"postgresql"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">    </span><span class="token punctuation" style="color:rgb(199, 146, 234)">]</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token punctuation" style="color:rgb(199, 146, 234)">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token keyword" style="font-style:italic">data </span><span class="token keyword type variable" style="font-style:italic;color:rgb(191, 199, 213)">"composite_schema"</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"app"</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token comment" style="color:rgb(105, 112, 152);font-style:italic"># Load custom types first</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token keyword" style="font-style:italic">schema</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">    </span><span class="token property">url</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">=</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"file://schema.sql"</span><span class="token plain">   </span><span class="token comment" style="color:rgb(105, 112, 152);font-style:italic">// schema file containing PostGIS extension creation</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token punctuation" style="color:rgb(199, 146, 234)">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token comment" style="color:rgb(105, 112, 152);font-style:italic"># Then, load SQLAlchemy models</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  schema </span><span class="token string" style="color:rgb(195, 232, 141)">"public"</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">    </span><span class="token property">url</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">=</span><span class="token plain"> data.external_schema.sqlalchemy.url</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token punctuation" style="color:rgb(199, 146, 234)">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token punctuation" style="color:rgb(199, 146, 234)">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">env </span><span class="token string" style="color:rgb(195, 232, 141)">"local"</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token property">src</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">=</span><span class="token plain"> data.composite_schema.app.url   </span><span class="token comment" style="color:rgb(105, 112, 152);font-style:italic">// link to current schema state</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token property">dev</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">=</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"docker://postgis/latest/dev"</span><span class="token plain">   </span><span class="token comment" style="color:rgb(105, 112, 152);font-style:italic">// dev database</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token punctuation" style="color:rgb(199, 146, 234)">}</span><br></span></code></pre></div></div></div><div role="tabpanel" class="tabItem_OMyP" hidden=""><div class="language-sql codeBlockContainer_ZGJx theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockTitle_L5qy">schema.sql</div><div class="codeBlockContent_kX1v"><pre tabindex="0" class="prism-code language-sql codeBlock_TAPP thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_AdAo"><span class="token-line" style="color:#bfc7d5"><span class="token keyword" style="font-style:italic">CREATE</span><span class="token plain"> EXTENSION postgis</span><span class="token punctuation" style="color:rgb(199, 146, 234)">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token comment" style="color:rgb(105, 112, 152);font-style:italic">// ... other extensions, baseline schema definitions, etc.</span><br></span></code></pre></div></div></div><div role="tabpanel" class="tabItem_OMyP" hidden=""><div class="language-python codeBlockContainer_ZGJx theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockTitle_L5qy">models.py</div><div class="codeBlockContent_kX1v"><pre tabindex="0" class="prism-code language-python codeBlock_TAPP thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_AdAo"><span class="token-line" style="color:#bfc7d5"><span class="token keyword" style="font-style:italic">from</span><span class="token plain"> sqlalchemy </span><span class="token keyword" style="font-style:italic">import</span><span class="token plain"> Column</span><span class="token punctuation" style="color:rgb(199, 146, 234)">,</span><span class="token plain"> Integer</span><span class="token punctuation" style="color:rgb(199, 146, 234)">,</span><span class="token plain"> String</span><span class="token punctuation" style="color:rgb(199, 146, 234)">,</span><span class="token plain"> DateTime</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token keyword" style="font-style:italic">from</span><span class="token plain"> sqlalchemy</span><span class="token punctuation" style="color:rgb(199, 146, 234)">.</span><span class="token plain">orm </span><span class="token keyword" style="font-style:italic">import</span><span class="token plain"> DeclarativeBase</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token keyword" style="font-style:italic">from</span><span class="token plain"> geoalchemy2 </span><span class="token keyword" style="font-style:italic">import</span><span class="token plain"> Geometry</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token keyword" style="font-style:italic">class</span><span class="token plain"> </span><span class="token class-name" style="color:rgb(255, 203, 107)">Base</span><span class="token punctuation" style="color:rgb(199, 146, 234)">(</span><span class="token plain">DeclarativeBase</span><span class="token punctuation" style="color:rgb(199, 146, 234)">)</span><span class="token punctuation" style="color:rgb(199, 146, 234)">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">    </span><span class="token keyword" style="font-style:italic">pass</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token keyword" style="font-style:italic">class</span><span class="token plain"> </span><span class="token class-name" style="color:rgb(255, 203, 107)">Users</span><span class="token punctuation" style="color:rgb(199, 146, 234)">(</span><span class="token plain">Base</span><span class="token punctuation" style="color:rgb(199, 146, 234)">)</span><span class="token punctuation" style="color:rgb(199, 146, 234)">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">    __tablename__ </span><span class="token operator" style="color:rgb(137, 221, 255)">=</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"Users"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">    </span><span class="token builtin" style="color:rgb(130, 170, 255)">id</span><span class="token plain"> </span><span class="token operator" style="color:rgb(137, 221, 255)">=</span><span class="token plain"> Column</span><span class="token punctuation" style="color:rgb(199, 146, 234)">(</span><span class="token plain">Integer</span><span class="token punctuation" style="color:rgb(199, 146, 234)">,</span><span class="token plain"> primary_key</span><span class="token operator" style="color:rgb(137, 221, 255)">=</span><span class="token boolean" style="color:rgb(255, 88, 116)">True</span><span class="token punctuation" style="color:rgb(199, 146, 234)">,</span><span class="token plain"> index</span><span class="token operator" style="color:rgb(137, 221, 255)">=</span><span class="token boolean" style="color:rgb(255, 88, 116)">True</span><span class="token punctuation" style="color:rgb(199, 146, 234)">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">    name </span><span class="token operator" style="color:rgb(137, 221, 255)">=</span><span class="token plain"> Column</span><span class="token punctuation" style="color:rgb(199, 146, 234)">(</span><span class="token plain">String</span><span class="token punctuation" style="color:rgb(199, 146, 234)">,</span><span class="token plain"> nullable</span><span class="token operator" style="color:rgb(137, 221, 255)">=</span><span class="token boolean" style="color:rgb(255, 88, 116)">False</span><span class="token punctuation" style="color:rgb(199, 146, 234)">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">    email </span><span class="token operator" style="color:rgb(137, 221, 255)">=</span><span class="token plain"> Column</span><span class="token punctuation" style="color:rgb(199, 146, 234)">(</span><span class="token plain">String</span><span class="token punctuation" style="color:rgb(199, 146, 234)">,</span><span class="token plain"> nullable</span><span class="token operator" style="color:rgb(137, 221, 255)">=</span><span class="token boolean" style="color:rgb(255, 88, 116)">False</span><span class="token punctuation" style="color:rgb(199, 146, 234)">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">    address </span><span class="token operator" style="color:rgb(137, 221, 255)">=</span><span class="token plain"> Column</span><span class="token punctuation" style="color:rgb(199, 146, 234)">(</span><span class="token plain">Geometry</span><span class="token punctuation" style="color:rgb(199, 146, 234)">(</span><span class="token string" style="color:rgb(195, 232, 141)">'POINT'</span><span class="token punctuation" style="color:rgb(199, 146, 234)">,</span><span class="token plain"> srid</span><span class="token operator" style="color:rgb(137, 221, 255)">=</span><span class="token number" style="color:rgb(247, 140, 108)">4326</span><span class="token punctuation" style="color:rgb(199, 146, 234)">)</span><span class="token punctuation" style="color:rgb(199, 146, 234)">,</span><span class="token plain"> nullable</span><span class="token operator" style="color:rgb(137, 221, 255)">=</span><span class="token boolean" style="color:rgb(255, 88, 116)">False</span><span class="token punctuation" style="color:rgb(199, 146, 234)">)</span><br></span></code></pre></div></div></div></div></div>
<p>Run <code>atlas schema inspect --env local --url env://src</code> to check for additional errors. The expected output using the above example files should be:</p>
<div class="language-shell codeBlockContainer_ZGJx theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockContent_kX1v"><pre tabindex="0" class="prism-code language-shell codeBlock_TAPP thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_AdAo"><span class="token-line" style="color:#bfc7d5"><span class="token plain">table </span><span class="token string" style="color:rgb(195, 232, 141)">"Users"</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  schema </span><span class="token operator" style="color:rgb(137, 221, 255)">=</span><span class="token plain"> schema.public</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token function" style="color:rgb(130, 170, 255)">column</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"id"</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">    null </span><span class="token operator" style="color:rgb(137, 221, 255)">=</span><span class="token plain"> </span><span class="token boolean" style="color:rgb(255, 88, 116)">false</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">    </span><span class="token builtin class-name" style="color:rgb(255, 203, 107)">type</span><span class="token plain"> </span><span class="token operator" style="color:rgb(137, 221, 255)">=</span><span class="token plain"> serial</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token punctuation" style="color:rgb(199, 146, 234)">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token function" style="color:rgb(130, 170, 255)">column</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"name"</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">    null </span><span class="token operator" style="color:rgb(137, 221, 255)">=</span><span class="token plain"> </span><span class="token boolean" style="color:rgb(255, 88, 116)">false</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">    </span><span class="token builtin class-name" style="color:rgb(255, 203, 107)">type</span><span class="token plain"> </span><span class="token operator" style="color:rgb(137, 221, 255)">=</span><span class="token plain"> character_varying</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token punctuation" style="color:rgb(199, 146, 234)">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token function" style="color:rgb(130, 170, 255)">column</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"email"</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">    null </span><span class="token operator" style="color:rgb(137, 221, 255)">=</span><span class="token plain"> </span><span class="token boolean" style="color:rgb(255, 88, 116)">false</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">    </span><span class="token builtin class-name" style="color:rgb(255, 203, 107)">type</span><span class="token plain"> </span><span class="token operator" style="color:rgb(137, 221, 255)">=</span><span class="token plain"> character_varying</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token punctuation" style="color:rgb(199, 146, 234)">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token function" style="color:rgb(130, 170, 255)">column</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"address"</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">    null </span><span class="token operator" style="color:rgb(137, 221, 255)">=</span><span class="token plain"> </span><span class="token boolean" style="color:rgb(255, 88, 116)">false</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">    </span><span class="token builtin class-name" style="color:rgb(255, 203, 107)">type</span><span class="token plain"> </span><span class="token operator" style="color:rgb(137, 221, 255)">=</span><span class="token plain"> sql</span><span class="token punctuation" style="color:rgb(199, 146, 234)">(</span><span class="token string" style="color:rgb(195, 232, 141)">"public.geometry(Point,4326)"</span><span class="token punctuation" style="color:rgb(199, 146, 234)">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token punctuation" style="color:rgb(199, 146, 234)">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  primary_key </span><span class="token punctuation" style="color:rgb(199, 146, 234)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">    columns </span><span class="token operator" style="color:rgb(137, 221, 255)">=</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">[</span><span class="token plain">column.id</span><span class="token punctuation" style="color:rgb(199, 146, 234)">]</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token punctuation" style="color:rgb(199, 146, 234)">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  index </span><span class="token string" style="color:rgb(195, 232, 141)">"idx_Users_address"</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">    columns </span><span class="token operator" style="color:rgb(137, 221, 255)">=</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">[</span><span class="token plain">column.address</span><span class="token punctuation" style="color:rgb(199, 146, 234)">]</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">    </span><span class="token builtin class-name" style="color:rgb(255, 203, 107)">type</span><span class="token plain">    </span><span class="token operator" style="color:rgb(137, 221, 255)">=</span><span class="token plain"> GIST</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token punctuation" style="color:rgb(199, 146, 234)">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  index </span><span class="token string" style="color:rgb(195, 232, 141)">"ix_Users_id"</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">    columns </span><span class="token operator" style="color:rgb(137, 221, 255)">=</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">[</span><span class="token plain">column.id</span><span class="token punctuation" style="color:rgb(199, 146, 234)">]</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token punctuation" style="color:rgb(199, 146, 234)">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token punctuation" style="color:rgb(199, 146, 234)">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">extension </span><span class="token string" style="color:rgb(195, 232, 141)">"postgis"</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  schema  </span><span class="token operator" style="color:rgb(137, 221, 255)">=</span><span class="token plain"> schema.public</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  version </span><span class="token operator" style="color:rgb(137, 221, 255)">=</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"3.5.2"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  comment </span><span class="token operator" style="color:rgb(137, 221, 255)">=</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"PostGIS geometry and geography spatial types and functions"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token punctuation" style="color:rgb(199, 146, 234)">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">schema </span><span class="token string" style="color:rgb(195, 232, 141)">"public"</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  comment </span><span class="token operator" style="color:rgb(137, 221, 255)">=</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"standard public schema"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token punctuation" style="color:rgb(199, 146, 234)">}</span><br></span></code></pre></div></div>
<p>Have additional questions or feedback? Feel free to reach out on our <a href="https://discord.gg/zZ6sWVg6NT" target="_blank" rel="noopener noreferrer" class="">Discord server</a>.</p>]]></content:encoded>
            <category>versioned migrations</category>
            <category>postgres</category>
            <category>postgis</category>
            <category>extensions</category>
            <category>orm</category>
            <category>sqlalchemy</category>
        </item>
        <item>
            <title><![CDATA[Why go install is no longer supported]]></title>
            <link>https://atlasgo.io/faq/go-install-deprecation</link>
            <guid>https://atlasgo.io/faq/go-install-deprecation</guid>
            <pubDate>Fri, 20 Nov 2026 20:08:41 GMT</pubDate>
            <description><![CDATA[Why `go install` is no longer supported and how to install Atlas CLI.]]></description>
            <content:encoded><![CDATA[<p>How can I install Atlas, and why is <code>go install</code> no longer supported?</p>
<h3 class="anchor anchorTargetStickyNavbar_SAay" id="answer">Answer<a href="https://atlasgo.io/faq/go-install-deprecation#answer" class="hash-link" aria-label="Direct link to Answer" title="Direct link to Answer" translate="no">​</a></h3>
<div class="theme-tabs-container tabs-container tabList_M0Dn"><ul role="tablist" aria-orientation="horizontal" class="tabs"><li role="tab" tabindex="0" aria-selected="true" class="tabs__item tabItem_ysIP tabs__item--active">macOS + Linux</li><li role="tab" tabindex="-1" aria-selected="false" class="tabs__item tabItem_ysIP">Homebrew</li><li role="tab" tabindex="-1" aria-selected="false" class="tabs__item tabItem_ysIP">Docker</li><li role="tab" tabindex="-1" aria-selected="false" class="tabs__item tabItem_ysIP">Windows</li><li role="tab" tabindex="-1" aria-selected="false" class="tabs__item tabItem_ysIP">CI</li><li role="tab" tabindex="-1" aria-selected="false" class="tabs__item tabItem_ysIP">Manual Installation</li></ul><div class="margin-top--md"><div role="tabpanel" class="tabItem_OMyP"><p>To download and install the latest release of the Atlas CLI, simply run the following in your terminal:</p><div class="language-shell codeBlockContainer_ZGJx theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockContent_kX1v"><pre tabindex="0" class="prism-code language-shell codeBlock_TAPP thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_AdAo"><span class="token-line" style="color:#bfc7d5"><span class="token function" style="color:rgb(130, 170, 255)">curl</span><span class="token plain"> </span><span class="token parameter variable" style="color:rgb(191, 199, 213)">-sSf</span><span class="token plain"> https://atlasgo.sh </span><span class="token operator" style="color:rgb(137, 221, 255)">|</span><span class="token plain"> </span><span class="token function" style="color:rgb(130, 170, 255)">sh</span><br></span></code></pre></div></div></div><div role="tabpanel" class="tabItem_OMyP" hidden=""><p>Get the latest release with <a href="https://brew.sh/" target="_blank" rel="noopener noreferrer" class="">Homebrew</a>:</p><div class="language-shell codeBlockContainer_ZGJx theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockContent_kX1v"><pre tabindex="0" class="prism-code language-shell codeBlock_TAPP thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_AdAo"><span class="token-line" style="color:#bfc7d5"><span class="token plain">brew </span><span class="token function" style="color:rgb(130, 170, 255)">install</span><span class="token plain"> ariga/tap/atlas</span><br></span></code></pre></div></div></div><div role="tabpanel" class="tabItem_OMyP" hidden=""><p>To pull the Atlas image and run it as a Docker container:</p><div class="language-shell codeBlockContainer_ZGJx theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockContent_kX1v"><pre tabindex="0" class="prism-code language-shell codeBlock_TAPP thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_AdAo"><span class="token-line" style="color:#bfc7d5"><span class="token function" style="color:rgb(130, 170, 255)">docker</span><span class="token plain"> pull arigaio/atlas</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token function" style="color:rgb(130, 170, 255)">docker</span><span class="token plain"> run </span><span class="token parameter variable" style="color:rgb(191, 199, 213)">--rm</span><span class="token plain"> arigaio/atlas </span><span class="token parameter variable" style="color:rgb(191, 199, 213)">--help</span><br></span></code></pre></div></div><p>If the container needs access to the host network or a local directory, use the <code>--net=host</code> flag and mount the desired
directory:</p><div class="language-shell codeBlockContainer_ZGJx theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockContent_kX1v"><pre tabindex="0" class="prism-code language-shell codeBlock_TAPP thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_AdAo"><span class="token-line" style="color:#bfc7d5"><span class="token function" style="color:rgb(130, 170, 255)">docker</span><span class="token plain"> run </span><span class="token parameter variable" style="color:rgb(191, 199, 213)">--rm</span><span class="token plain"> </span><span class="token parameter variable" style="color:rgb(191, 199, 213)">--net</span><span class="token operator" style="color:rgb(137, 221, 255)">=</span><span class="token plain">host </span><span class="token punctuation" style="color:rgb(199, 146, 234)">\</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token parameter variable" style="color:rgb(191, 199, 213)">-v</span><span class="token plain"> </span><span class="token variable" style="color:rgb(191, 199, 213)">$(</span><span class="token variable builtin class-name" style="color:rgb(255, 203, 107)">pwd</span><span class="token variable" style="color:rgb(191, 199, 213)">)</span><span class="token plain">/migrations:/migrations </span><span class="token punctuation" style="color:rgb(199, 146, 234)">\</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  arigaio/atlas migrate apply </span><span class="token punctuation" style="color:rgb(199, 146, 234)">\</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token parameter variable" style="color:rgb(191, 199, 213)">--url</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"mysql://root:pass@:3306/test"</span><br></span></code></pre></div></div></div><div role="tabpanel" class="tabItem_OMyP" hidden=""><p>Download the <a href="https://atlasbinaries.com/atlas/atlas-windows-amd64-latest.exe" target="_blank" rel="noopener noreferrer" class="">latest release</a> and
move the atlas binary to a file location on your system PATH.</p></div><div role="tabpanel" class="tabItem_OMyP" hidden=""><p><strong>GitHub Actions</strong></p><p>Use the <a href="https://github.com/marketplace/actions/setup-atlas" target="_blank" rel="noopener noreferrer" class="">setup-atlas</a> action to install Atlas in your GitHub Actions workflow:</p><div class="language-yaml codeBlockContainer_ZGJx theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockContent_kX1v"><pre tabindex="0" class="prism-code language-yaml codeBlock_TAPP thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_AdAo"><span class="token-line" style="color:#bfc7d5"><span class="token punctuation" style="color:rgb(199, 146, 234)">-</span><span class="token plain"> </span><span class="token key atrule">uses</span><span class="token punctuation" style="color:rgb(199, 146, 234)">:</span><span class="token plain"> ariga/setup</span><span class="token punctuation" style="color:rgb(199, 146, 234)">-</span><span class="token plain">atlas@v0</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token key atrule">with</span><span class="token punctuation" style="color:rgb(199, 146, 234)">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">    </span><span class="token key atrule">cloud-token</span><span class="token punctuation" style="color:rgb(199, 146, 234)">:</span><span class="token plain"> $</span><span class="token punctuation" style="color:rgb(199, 146, 234)">{</span><span class="token punctuation" style="color:rgb(199, 146, 234)">{</span><span class="token plain"> secrets.ATLAS_CLOUD_TOKEN </span><span class="token punctuation" style="color:rgb(199, 146, 234)">}</span><span class="token punctuation" style="color:rgb(199, 146, 234)">}</span><br></span></code></pre></div></div><p><strong>Other CI Platforms</strong></p><p>For other CI/CD platforms, use the installation script. See the <a class="" href="https://atlasgo.io/integrations#cicd-platforms">CI/CD integrations</a> for more details.</p></div><div role="tabpanel" class="tabItem_OMyP" hidden=""><p>If you want to manually install the Atlas CLI, pick one of the below builds suitable for your system.</p><div class="grid grid-cols-1 lg:grid-cols-3 auto-cols-fr gap-4 mt-4"><div class="flex flex-col gap-4"><h3>MacOS</h3><div class="flex flex-col items-center p-4 rounded-lg dark:bg-[#fff] border-lightGrey border"><div class="flex gap-4 items-center"><img class="" src="https://atlasgo.io/icons-docs/download.svg" alt="Download icon"><span class="!text-darkBlue"><p><a href="https://atlasbinaries.com/atlas/atlas-darwin-amd64-latest" class="!font-mono">AMD 64 </a>
(<a href="https://atlasbinaries.com/atlas/atlas-darwin-amd64-latest.md5" class="!font-mono">md5</a>/<a href="https://atlasbinaries.com/atlas/atlas-darwin-amd64-latest.sha256" class="!font-mono">sha256</a>)</p></span></div></div><div class="flex flex-col items-center p-4 rounded-lg dark:bg-[#fff] border-lightGrey border"><div class="flex gap-4 items-center"><img class="" src="https://atlasgo.io/icons-docs/download.svg" alt="Download icon"><span class="!text-darkBlue"><p><a href="https://atlasbinaries.com/atlas/atlas-darwin-arm64-latest" class="!font-mono">ARM 64 </a>
(<a href="https://atlasbinaries.com/atlas/atlas-darwin-arm64-latest.md5" class="!font-mono">md5</a>/<a href="https://atlasbinaries.com/atlas/atlas-darwin-arm64-latest.sha256" class="!font-mono">sha256</a>)</p></span></div></div></div><div class="flex flex-col gap-4"><h3>Linux</h3><div class="flex flex-col items-center p-4 rounded-lg dark:bg-[#fff] border-lightGrey border"><div class="flex gap-4 items-center"><img class="" src="https://atlasgo.io/icons-docs/download.svg" alt="Download icon"><span class="!text-darkBlue !font-mono"><p><a href="https://atlasbinaries.com/atlas/atlas-linux-amd64-latest" class="!font-mono">AMD 64 </a>
(<a href="https://atlasbinaries.com/atlas/atlas-linux-amd64-latest.md5" class="!font-mono">md5</a>/<a href="https://atlasbinaries.com/atlas/atlas-linux-amd64-latest.sha256" class="!font-mono">sha256</a>)</p></span></div></div><div class="flex flex-col items-center p-4 rounded-lg dark:bg-[#fff] border-lightGrey border"><div class="flex gap-4 items-center"><img class="" src="https://atlasgo.io/icons-docs/download.svg" alt="Download icon"><span class="!text-darkBlue !font-mono"><p><a href="https://atlasbinaries.com/atlas/atlas-linux-arm64-latest" class="!font-mono">ARM 64 </a>
(<a href="https://atlasbinaries.com/atlas/atlas-linux-arm64-latest.md5" class="!font-mono">md5</a>/<a href="https://atlasbinaries.com/atlas/atlas-linux-arm64-latest.sha256" class="!font-mono">sha256</a>)</p></span></div></div></div><div class="flex flex-col gap-4"><h3>Windows</h3><div class="flex flex-col items-center p-4 rounded-lg dark:bg-[#fff] border-lightGrey border"><div class="flex gap-4 items-center"><img class="" src="https://atlasgo.io/icons-docs/download.svg" alt="Download icon"><span class="!text-darkBlue !font-mono"><p><a href="https://atlasbinaries.com/atlas/atlas-windows-amd64-latest.exe" class="!font-mono">AMD 64 </a>
(<a href="https://atlasbinaries.com/atlas/atlas-windows-amd64-latest.exe.md5" class="!font-mono">md5</a>/<a href="https://atlasbinaries.com/atlas/atlas-windows-amd64-latest.exe.sha256" class="!font-mono">sha256</a>)</p></span></div></div></div></div></div></div></div>
<h3 class="anchor anchorTargetStickyNavbar_SAay" id="why-doesnt-go-install-work-anymore">Why doesn't <code>go install</code> work anymore?<a href="https://atlasgo.io/faq/go-install-deprecation#why-doesnt-go-install-work-anymore" class="hash-link" aria-label="Direct link to why-doesnt-go-install-work-anymore" title="Direct link to why-doesnt-go-install-work-anymore" translate="no">​</a></h3>
<p>We no longer maintain the <code>cmd/atlas</code> package as an executable. Atlas is used across multiple programming languages,
like Python and Java, and the binary we distribute includes additional features and capabilities that wouldn't be
possible with <code>go install</code>.</p>]]></content:encoded>
            <category>faq</category>
            <category>installation</category>
        </item>
        <item>
            <title><![CDATA[Performing Atlas Migrations When Using Golang Migrate]]></title>
            <link>https://atlasgo.io/faq/migrations-with-golang</link>
            <guid>https://atlasgo.io/faq/migrations-with-golang</guid>
            <pubDate>Fri, 20 Nov 2026 20:08:41 GMT</pubDate>
            <description><![CDATA[Going over how to apply Atlas migrations on a project that also uses golang-migrate.]]></description>
            <content:encoded><![CDATA[<p>Developers who use Atlas to run migrations using a <code>golang-migrate</code> directory format,  may run into an errors like:</p>
<div class="language-bash codeBlockContainer_ZGJx theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockContent_kX1v"><pre tabindex="0" class="prism-code language-bash codeBlock_TAPP thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_AdAo"><span class="token-line" style="color:#bfc7d5"><span class="token plain">-- migrating version </span><span class="token number" style="color:rgb(247, 140, 108)">20250324061649</span><span class="token plain">.down.sql</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">-</span><span class="token operator" style="color:rgb(137, 221, 255)">&gt;</span><span class="token plain"> DROP TABLE </span><span class="token variable" style="color:rgb(191, 199, 213)">`</span><span class="token variable function" style="color:rgb(130, 170, 255)">users</span><span class="token variable" style="color:rgb(191, 199, 213)">`</span><span class="token punctuation" style="color:rgb(199, 146, 234)">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">   Error </span><span class="token number" style="color:rgb(247, 140, 108)">1051</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">(</span><span class="token plain">42S02</span><span class="token punctuation" style="color:rgb(199, 146, 234)">)</span><span class="token plain">: Unknown table </span><span class="token string" style="color:rgb(195, 232, 141)">'public.users'</span><br></span></code></pre></div></div>
<p><code>golang-migrate</code> is a popular migration tool used in the Go community, and Atlas supports working with its migration directory
format, amongst others, through basic configurations.</p>
<h3 class="anchor anchorTargetStickyNavbar_SAay" id="golang-migrate-migration-directory">golang-migrate Migration Directory<a href="https://atlasgo.io/faq/migrations-with-golang#golang-migrate-migration-directory" class="hash-link" aria-label="Direct link to golang-migrate Migration Directory" title="Direct link to golang-migrate Migration Directory" translate="no">​</a></h3>
<p>When creating schema migrations with <code>golang-migrate</code>, users create two empty files for each set of changes like so:</p>
<div class="language-bash codeBlockContainer_ZGJx theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockContent_kX1v"><pre tabindex="0" class="prism-code language-bash codeBlock_TAPP thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_AdAo"><span class="token-line" style="color:#bfc7d5"><span class="token plain">db/migrations</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">├── </span><span class="token number" style="color:rgb(247, 140, 108)">20250324061649</span><span class="token plain">.down.sql</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">└── </span><span class="token number" style="color:rgb(247, 140, 108)">20250324061649</span><span class="token plain">.up.sql</span><br></span></code></pre></div></div>
<p>The files contain the intended schema changes (<code>up</code>) and the instructions to roll back these changes (<code>down</code>).</p>
<p>When applying migrations, you use the <code>up</code> command so golang-migrate knows to use the corresponding <code>up</code> files. When
rolling back on migrations, you use the <code>down</code> command to golang-migrate knows to use the corresponding <code>down</code> files.</p>
<h3 class="anchor anchorTargetStickyNavbar_SAay" id="applying-migrations-with-atlas">Applying Migrations with Atlas<a href="https://atlasgo.io/faq/migrations-with-golang#applying-migrations-with-atlas" class="hash-link" aria-label="Direct link to Applying Migrations with Atlas" title="Direct link to Applying Migrations with Atlas" translate="no">​</a></h3>
<p>The standard migrations directory for Atlas does not contain separate <code>up</code> and <code>down</code> files. Instead, it only contains
files with schema migrations and applies them all in order when running <code>migrate apply</code> and has a separate system for rollbacks.</p>
<p>If a user tries executing <code>migrate apply</code> using a golang-migrate migrations directory setup without any flags, Atlas will
assume it is a standard Atlas directory and run all the files, including the <code>down</code> files. Since Atlas runs the migration
files in lexicographic order, the <code>down</code> files are typically run first, meaning that Atlas tries to run commands that revert
changes that have yet to be made, leading to errors.</p>
<h3 class="anchor anchorTargetStickyNavbar_SAay" id="the-solution">The Solution<a href="https://atlasgo.io/faq/migrations-with-golang#the-solution" class="hash-link" aria-label="Direct link to The Solution" title="Direct link to The Solution" translate="no">​</a></h3>
<p>To ensure that only the <code>up</code> migration files are run, add the <code>format</code> flag to the <code>env</code> block in <code>atlas.hcl</code> either as
a parameter:</p>
<div class="language-hcl codeBlockContainer_ZGJx theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockContent_kX1v"><pre tabindex="0" class="prism-code language-hcl codeBlock_TAPP thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_AdAo"><span class="token-line" style="color:#bfc7d5"><span class="token plain">env </span><span class="token string" style="color:rgb(195, 232, 141)">"dev"</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">    ...</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">    </span><span class="token keyword" style="font-style:italic">migration</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">        </span><span class="token property">dir</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">=</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"file://db/migrations"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">        </span><span class="token property">format</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">=</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"golang-migrate"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">    </span><span class="token punctuation" style="color:rgb(199, 146, 234)">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token punctuation" style="color:rgb(199, 146, 234)">}</span><br></span></code></pre></div></div>
<p>or as a flag in the directory link:</p>
<div class="language-hcl codeBlockContainer_ZGJx theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockContent_kX1v"><pre tabindex="0" class="prism-code language-hcl codeBlock_TAPP thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_AdAo"><span class="token-line" style="color:#bfc7d5"><span class="token plain">env </span><span class="token string" style="color:rgb(195, 232, 141)">"dev"</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">    ...</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">    </span><span class="token keyword" style="font-style:italic">migration</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">        </span><span class="token property">dir</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">=</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"file://db/migrations?format=golang-migrate"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">    </span><span class="token punctuation" style="color:rgb(199, 146, 234)">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token punctuation" style="color:rgb(199, 146, 234)">}</span><br></span></code></pre></div></div>
<p>Alternatively, you can include the directory link with the <code>?format=golang-migrate</code> flag in the command:</p>
<div class="language-bash codeBlockContainer_ZGJx theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockContent_kX1v"><pre tabindex="0" class="prism-code language-bash codeBlock_TAPP thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_AdAo"><span class="token-line" style="color:#bfc7d5"><span class="token plain">atlas migrate apply </span><span class="token parameter variable" style="color:rgb(191, 199, 213)">--dir</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"file://db/migrations?format=golang-migrate"</span><span class="token plain"> </span><span class="token parameter variable" style="color:rgb(191, 199, 213)">--env</span><span class="token plain"> dev</span><br></span></code></pre></div></div>
<p>Defining a <code>format</code> value ensures that Atlas is aware that both <code>up</code> and <code>down</code> files exist in the migrations directory
and it should only use the <code>up</code> files. These <code>up</code> files can have destructive commands in them, but they are not dropping
objects that don't yet exist in the schema.</p>]]></content:encoded>
            <category>faq</category>
            <category>golang-migrate</category>
            <category>versioned migrations</category>
        </item>
        <item>
            <title><![CDATA[Debugging Atlas HCL Using print()]]></title>
            <link>https://atlasgo.io/faq/hcl-debug</link>
            <guid>https://atlasgo.io/faq/hcl-debug</guid>
            <pubDate>Fri, 20 Nov 2026 20:08:41 GMT</pubDate>
            <description><![CDATA[Learn how to use print statements to debug you hcl configuration file.]]></description>
            <content:encoded><![CDATA[<p>With features such as composite schemas, custom rules, schema linting, and more, the <code>atlas.hcl</code> file can get complex.
To validate or debug the file, you can use <code>print</code> statements as you commonly would with other languages.</p>
<h3 class="anchor anchorTargetStickyNavbar_SAay" id="example-1">Example 1<a href="https://atlasgo.io/faq/hcl-debug#example-1" class="hash-link" aria-label="Direct link to Example 1" title="Direct link to Example 1" translate="no">​</a></h3>
<p>To ensure that the proper value is being assigned to a variable, simply wrap it in a print statement:</p>
<div class="language-hcl codeBlockContainer_ZGJx theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockTitle_L5qy">atlas.hcl</div><div class="codeBlockContent_kX1v"><pre tabindex="0" class="prism-code language-hcl codeBlock_TAPP thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_AdAo"><span class="token-line" style="color:#bfc7d5"><span class="token keyword" style="font-style:italic">data </span><span class="token keyword type variable" style="font-style:italic;color:rgb(191, 199, 213)">"runtimevar"</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"myip"</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token property">url</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">=</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"https://api.ipify.org?format=json"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token punctuation" style="color:rgb(199, 146, 234)">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token keyword" style="font-style:italic">locals</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token property">ip</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">=</span><span class="token plain"> print(data.runtimevar.myip)</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token punctuation" style="color:rgb(199, 146, 234)">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">env </span><span class="token string" style="color:rgb(195, 232, 141)">"test"</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token property">url</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">=</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"mysql://user:pass@localhost:3306/my_db"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token punctuation" style="color:rgb(199, 146, 234)">}</span><br></span></code></pre></div></div>
<p>The print statement is evaluated when reached after running a command that accesses the file, such as <code>atlas schema inspect --env test</code>.
After running the command, <code>ip</code> is printed and I see a JSON in the output where I expected a string containing my IP address:</p>
<div class="language-text codeBlockContainer_ZGJx theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockContent_kX1v"><pre tabindex="0" class="prism-code language-text codeBlock_TAPP thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_AdAo"><span class="token-line" style="color:#bfc7d5"><span class="token plain">{"ip":"127.0.0.1"}</span><br></span></code></pre></div></div>
<p>Now I know to decode and index the JSON to get the proper output.</p>
<div class="language-hcl codeBlockContainer_ZGJx theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockTitle_L5qy">atlas.hcl</div><div class="codeBlockContent_kX1v"><pre tabindex="0" class="prism-code language-hcl codeBlock_TAPP thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_AdAo"><span class="token-line" style="color:#bfc7d5"><span class="token keyword" style="font-style:italic">data </span><span class="token keyword type variable" style="font-style:italic;color:rgb(191, 199, 213)">"runtimevar"</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"myip"</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token property">url</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">=</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"https://api.ipify.org?format=json"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token punctuation" style="color:rgb(199, 146, 234)">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token keyword" style="font-style:italic">locals</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token property">ip</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">=</span><span class="token plain"> print(jsondecode(data.runtimevar.myip)</span><span class="token punctuation" style="color:rgb(199, 146, 234)">[</span><span class="token string" style="color:rgb(195, 232, 141)">"ip"</span><span class="token punctuation" style="color:rgb(199, 146, 234)">]</span><span class="token plain">)</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token punctuation" style="color:rgb(199, 146, 234)">}</span><br></span></code></pre></div></div>
<div class="language-text codeBlockContainer_ZGJx theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockContent_kX1v"><pre tabindex="0" class="prism-code language-text codeBlock_TAPP thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_AdAo"><span class="token-line" style="color:#bfc7d5"><span class="token plain">127.0.0.1</span><br></span></code></pre></div></div>
<h3 class="anchor anchorTargetStickyNavbar_SAay" id="example-2">Example 2<a href="https://atlasgo.io/faq/hcl-debug#example-2" class="hash-link" aria-label="Direct link to Example 2" title="Direct link to Example 2" translate="no">​</a></h3>
<p>To ensure that an operation gives the proper result without assigning it to a variable, use the <code>_</code> placeholder:</p>
<div class="language-hcl codeBlockContainer_ZGJx theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockTitle_L5qy">atlas.hcl</div><div class="codeBlockContent_kX1v"><pre tabindex="0" class="prism-code language-hcl codeBlock_TAPP thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_AdAo"><span class="token-line" style="color:#bfc7d5"><span class="token keyword" style="font-style:italic">data </span><span class="token keyword type variable" style="font-style:italic;color:rgb(191, 199, 213)">"runtimevar"</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"myip"</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token property">url</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">=</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"https://api.ipify.org?format=json"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token punctuation" style="color:rgb(199, 146, 234)">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token keyword" style="font-style:italic">locals</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token property">_</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">=</span><span class="token plain"> print(data.runtimevar.myip)</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token punctuation" style="color:rgb(199, 146, 234)">}</span><br></span></code></pre></div></div>
<h3 class="anchor anchorTargetStickyNavbar_SAay" id="example-3">Example 3<a href="https://atlasgo.io/faq/hcl-debug#example-3" class="hash-link" aria-label="Direct link to Example 3" title="Direct link to Example 3" translate="no">​</a></h3>
<p>Let's look at a more involved example that combines these two methods:</p>
<div class="language-hcl codeBlockContainer_ZGJx theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockTitle_L5qy">atlas.hcl</div><div class="codeBlockContent_kX1v"><pre tabindex="0" class="prism-code language-hcl codeBlock_TAPP thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_AdAo"><span class="token-line" style="color:#bfc7d5"><span class="token keyword" style="font-style:italic">data </span><span class="token keyword type variable" style="font-style:italic;color:rgb(191, 199, 213)">"external"</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"envfile"</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">    </span><span class="token property">program</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">=</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">[</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">        </span><span class="token string" style="color:rgb(195, 232, 141)">"node"</span><span class="token plain">,</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">        </span><span class="token string" style="color:rgb(195, 232, 141)">"./envfile.js"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">    </span><span class="token punctuation" style="color:rgb(199, 146, 234)">]</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token punctuation" style="color:rgb(199, 146, 234)">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token keyword" style="font-style:italic">locals</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token property">envfile</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">=</span><span class="token plain"> jsondecode(data.external.envfile)</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token punctuation" style="color:rgb(199, 146, 234)">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">env </span><span class="token string" style="color:rgb(195, 232, 141)">"test"</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token property">url</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">=</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"mysql://</span><span class="token string interpolation punctuation" style="color:rgb(199, 146, 234)">$</span><span class="token string interpolation punctuation" style="color:rgb(199, 146, 234)">{</span><span class="token string interpolation keyword" style="color:rgb(195, 232, 141);font-style:italic">local</span><span class="token string interpolation punctuation" style="color:rgb(199, 146, 234)">.</span><span class="token string interpolation type variable" style="color:rgb(191, 199, 213)">envfile</span><span class="token string interpolation punctuation" style="color:rgb(199, 146, 234)">.</span><span class="token string interpolation" style="color:rgb(195, 232, 141)">DB_USER</span><span class="token string interpolation punctuation" style="color:rgb(199, 146, 234)">}</span><span class="token string" style="color:rgb(195, 232, 141)">:</span><span class="token string interpolation punctuation" style="color:rgb(199, 146, 234)">$</span><span class="token string interpolation punctuation" style="color:rgb(199, 146, 234)">{</span><span class="token string interpolation keyword" style="color:rgb(195, 232, 141);font-style:italic">local</span><span class="token string interpolation punctuation" style="color:rgb(199, 146, 234)">.</span><span class="token string interpolation type variable" style="color:rgb(191, 199, 213)">envfile</span><span class="token string interpolation punctuation" style="color:rgb(199, 146, 234)">.</span><span class="token string interpolation" style="color:rgb(195, 232, 141)">DB_PASS</span><span class="token string interpolation punctuation" style="color:rgb(199, 146, 234)">}</span><span class="token string" style="color:rgb(195, 232, 141)">@localhost:3306/</span><span class="token string interpolation punctuation" style="color:rgb(199, 146, 234)">$</span><span class="token string interpolation punctuation" style="color:rgb(199, 146, 234)">{</span><span class="token string interpolation keyword" style="color:rgb(195, 232, 141);font-style:italic">local</span><span class="token string interpolation punctuation" style="color:rgb(199, 146, 234)">.</span><span class="token string interpolation type variable" style="color:rgb(191, 199, 213)">envfile</span><span class="token string interpolation punctuation" style="color:rgb(199, 146, 234)">.</span><span class="token string interpolation" style="color:rgb(195, 232, 141)">DB_NAME</span><span class="token string interpolation punctuation" style="color:rgb(199, 146, 234)">}</span><span class="token string" style="color:rgb(195, 232, 141)">"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token property">dev</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">=</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"docker://mysql/latest/dev"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token punctuation" style="color:rgb(199, 146, 234)">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain" style="display:inline-block"></span><br></span></code></pre></div></div>
<p>Here, I use a program defined in <code>envfile.js</code> that returns my <code>.env</code> file as a JSON object. Then, I'm using
<code>jsonencode</code> to save the result as a local JSON variable to access the environment variables.</p>
<p>To check that the JSON encoding of my <code>.env</code> file and the resulting URL are correct, I can add print statements and see
if I get the expected results:</p>
<div class="language-hcl codeBlockContainer_ZGJx theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockTitle_L5qy">atlas.hcl</div><div class="codeBlockContent_kX1v"><pre tabindex="0" class="prism-code language-hcl codeBlock_TAPP thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_AdAo"><span class="token-line" style="color:#bfc7d5"><span class="token keyword" style="font-style:italic">data </span><span class="token keyword type variable" style="font-style:italic;color:rgb(191, 199, 213)">"external"</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"envfile"</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">    </span><span class="token property">program</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">=</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">[</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">        </span><span class="token string" style="color:rgb(195, 232, 141)">"node"</span><span class="token plain">,</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">        </span><span class="token string" style="color:rgb(195, 232, 141)">"./envfile.js"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">    </span><span class="token punctuation" style="color:rgb(199, 146, 234)">]</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token punctuation" style="color:rgb(199, 146, 234)">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token keyword" style="font-style:italic">locals</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token property">envfile</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">=</span><span class="token plain"> jsondecode(data.external.envfile)</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token property">_</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">=</span><span class="token plain"> print(local.envfile</span><span class="token punctuation" style="color:rgb(199, 146, 234)">[</span><span class="token string" style="color:rgb(195, 232, 141)">"COMPANY_NAME"</span><span class="token punctuation" style="color:rgb(199, 146, 234)">]</span><span class="token plain">)</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token punctuation" style="color:rgb(199, 146, 234)">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">env </span><span class="token string" style="color:rgb(195, 232, 141)">"test"</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token property">url</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">=</span><span class="token plain"> print(</span><span class="token string" style="color:rgb(195, 232, 141)">"mysql://</span><span class="token string interpolation punctuation" style="color:rgb(199, 146, 234)">$</span><span class="token string interpolation punctuation" style="color:rgb(199, 146, 234)">{</span><span class="token string interpolation keyword" style="color:rgb(195, 232, 141);font-style:italic">local</span><span class="token string interpolation punctuation" style="color:rgb(199, 146, 234)">.</span><span class="token string interpolation type variable" style="color:rgb(191, 199, 213)">envfile</span><span class="token string interpolation punctuation" style="color:rgb(199, 146, 234)">.</span><span class="token string interpolation" style="color:rgb(195, 232, 141)">DB_USER</span><span class="token string interpolation punctuation" style="color:rgb(199, 146, 234)">}</span><span class="token string" style="color:rgb(195, 232, 141)">:</span><span class="token string interpolation punctuation" style="color:rgb(199, 146, 234)">$</span><span class="token string interpolation punctuation" style="color:rgb(199, 146, 234)">{</span><span class="token string interpolation keyword" style="color:rgb(195, 232, 141);font-style:italic">local</span><span class="token string interpolation punctuation" style="color:rgb(199, 146, 234)">.</span><span class="token string interpolation type variable" style="color:rgb(191, 199, 213)">envfile</span><span class="token string interpolation punctuation" style="color:rgb(199, 146, 234)">.</span><span class="token string interpolation" style="color:rgb(195, 232, 141)">DB_PASS</span><span class="token string interpolation punctuation" style="color:rgb(199, 146, 234)">}</span><span class="token string" style="color:rgb(195, 232, 141)">@$localhost:3306/</span><span class="token string interpolation punctuation" style="color:rgb(199, 146, 234)">$</span><span class="token string interpolation punctuation" style="color:rgb(199, 146, 234)">{</span><span class="token string interpolation keyword" style="color:rgb(195, 232, 141);font-style:italic">local</span><span class="token string interpolation punctuation" style="color:rgb(199, 146, 234)">.</span><span class="token string interpolation type variable" style="color:rgb(191, 199, 213)">envfile</span><span class="token string interpolation punctuation" style="color:rgb(199, 146, 234)">.</span><span class="token string interpolation" style="color:rgb(195, 232, 141)">DB_NAME</span><span class="token string interpolation punctuation" style="color:rgb(199, 146, 234)">}</span><span class="token string" style="color:rgb(195, 232, 141)">"</span><span class="token plain">)</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token property">dev</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">=</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"docker://mysql/latest/dev"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token punctuation" style="color:rgb(199, 146, 234)">}</span><br></span></code></pre></div></div>
<p>At the beginning of my CLI output, we get the results of the print statements:</p>
<div class="language-text codeBlockContainer_ZGJx theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockContent_kX1v"><pre tabindex="0" class="prism-code language-text codeBlock_TAPP thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_AdAo"><span class="token-line" style="color:#bfc7d5"><span class="token plain">ariga</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">mysql://root:pass@localhost:3306/example</span><br></span></code></pre></div></div>
<p>Keep in mind when placing print statements that their results are outputted as they are evaluated, so <code>foreach</code>
statements could cause duplicate outputs, printing variables that have yet to be assigned could lead to errors,
and so on.</p>]]></content:encoded>
            <category>hcl</category>
            <category>debug</category>
            <category>print</category>
        </item>
        <item>
            <title><![CDATA[Managing PostgreSQL Extensions in a Dedicated Migration Process]]></title>
            <link>https://atlasgo.io/faq/manage-extension-only</link>
            <guid>https://atlasgo.io/faq/manage-extension-only</guid>
            <pubDate>Fri, 20 Nov 2026 20:08:41 GMT</pubDate>
            <description><![CDATA[Learn how to manage PostgreSQL extensions separately from your main schema migrations using the --include flag in Atlas.]]></description>
            <content:encoded><![CDATA[<p>PostgreSQL extensions are additional modules that extend the functionality of the PostgreSQL database. Examples of popular
extensions include PostGIS for geographic data handling, PGVector for vector similarity search, and pgcrypto for cryptographic functions.</p>
<p>Once installed, these extensions provide additional data types and objects that users' schemas can leverage. However, because
extensions are managed at the <u>database level</u> (and can only be installed once per database rather than per schema), users may prefer
handling these extensions separately from their primary application schema migrations.</p>
<p>For example, if you maintain multiple applications – each with its own schema(s) but several relying on the same PostgreSQL extension –
determining which application should handle installation, upgrades, or removal can be challenging. To address this complexity, managing
extensions through a dedicated migration process is beneficial. This separation ensures extension-related changes remain isolated.</p>
<p>This guide demonstrates how to use the <code>--include</code> flag (or <code>env.include</code> argument) provided by Atlas to limit migrations specifically to PostgreSQL extensions.</p>
<h2 class="anchor anchorTargetStickyNavbar_SAay" id="limit-migration-scope-to-extensions-only">Limit migration scope to extensions only<a href="https://atlasgo.io/faq/manage-extension-only#limit-migration-scope-to-extensions-only" class="hash-link" aria-label="Direct link to Limit migration scope to extensions only" title="Direct link to Limit migration scope to extensions only" translate="no">​</a></h2>
<p>Given a schema file named <code>extensions.pg.hcl</code> listing all extensions we expect to have in our database:</p>
<div class="language-hcl codeBlockContainer_ZGJx theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockTitle_L5qy">extensions.pg.hcl</div><div class="codeBlockContent_kX1v"><pre tabindex="0" class="prism-code language-hcl codeBlock_TAPP thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_AdAo"><span class="token-line" style="color:#bfc7d5"><span class="token plain">extension </span><span class="token string" style="color:rgb(195, 232, 141)">"fuzzystrmatch"</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token property">version</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">=</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"1.1"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token property">comment</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">=</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"Determine similarities and distance between strings"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token punctuation" style="color:rgb(199, 146, 234)">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">extension </span><span class="token string" style="color:rgb(195, 232, 141)">"citext"</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token property">version</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">=</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"1.6"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token property">comment</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">=</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"Data type for case-insensitive character strings"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token punctuation" style="color:rgb(199, 146, 234)">}</span><br></span></code></pre></div></div>
<p>To define a migration process for it, we need to create a new environment in our <code>atlas.hcl</code> file:</p>
<div class="language-hcl codeBlockContainer_ZGJx theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockContent_kX1v"><pre tabindex="0" class="prism-code language-hcl codeBlock_TAPP thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_AdAo"><span class="token-line" style="color:#bfc7d5"><span class="token plain">env </span><span class="token string" style="color:rgb(195, 232, 141)">"extensions"</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token property">src</span><span class="token plain">     </span><span class="token punctuation" style="color:rgb(199, 146, 234)">=</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"file://extensions.pg.hcl"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token property">url</span><span class="token plain">     </span><span class="token punctuation" style="color:rgb(199, 146, 234)">=</span><span class="token plain"> getenv(</span><span class="token string" style="color:rgb(195, 232, 141)">"DATABASE_URL"</span><span class="token plain">)</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token property">include</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">=</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">[</span><span class="token string" style="color:rgb(195, 232, 141)">"*[type=extension]"</span><span class="token punctuation" style="color:rgb(199, 146, 234)">]</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token punctuation" style="color:rgb(199, 146, 234)">}</span><br></span></code></pre></div></div>
<p>The <code>include</code> argument will limit Atlas' scope to inspect and manage only the database extensions in this environment.</p>
<p>Then, running <code>atlas schema apply --env extensions</code> results in:</p>
<div class="language-applylog codeBlockContainer_ZGJx theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockContent_kX1v"><pre tabindex="0" class="prism-code language-applylog codeBlock_TAPP thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_AdAo"><span class="token-line" style="color:#bfc7d5"><span class="token plain">Applying approved migration (2 statements in total):</span><span class="token action1"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token action1"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token action1">  -- </span><span class="token plain">create extension "fuzzystrmatch"</span><span class="token action3"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token action3">    -&gt; </span><span class="token plain">CREATE EXTENSION "fuzzystrmatch" VERSION "1.1";</span><span class="token action1"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token action1">  -- </span><span class="token plain">ok (</span><span class="token duration">8.79975ms</span><span class="token plain">)</span><span class="token action1"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token action1"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token action1">  -- </span><span class="token plain">create extension "citext"</span><span class="token action3"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token action3">    -&gt; </span><span class="token plain">CREATE EXTENSION "citext" VERSION "1.6";</span><span class="token action1"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token action1">  -- </span><span class="token plain">ok (</span><span class="token duration">8.856958ms</span><span class="token plain">)</span><span class="token action2"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token action2"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token action2">  -------------------------</span><span class="token action1"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token action1">  -- </span><span class="token duration">17.845333ms</span><span class="token action1"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token action1">  -- </span><span class="token plain">1 migration</span><span class="token action1"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token action1">  -- </span><span class="token plain">2 sql statements</span><br></span></code></pre></div></div>
<div class="theme-admonition theme-admonition-note admonition_IZjC alert alert--secondary"><div class="admonitionHeading_uVvU"><span class="admonitionIcon_HiR3"><svg viewBox="0 0 14 16"><path fill-rule="evenodd" d="M6.3 5.69a.942.942 0 0 1-.28-.7c0-.28.09-.52.28-.7.19-.18.42-.28.7-.28.28 0 .52.09.7.28.18.19.28.42.28.7 0 .28-.09.52-.28.7a1 1 0 0 1-.7.3c-.28 0-.52-.11-.7-.3zM8 7.99c-.02-.25-.11-.48-.31-.69-.2-.19-.42-.3-.69-.31H6c-.27.02-.48.13-.69.31-.2.2-.3.44-.31.69h1v3c.02.27.11.5.31.69.2.2.42.31.69.31h1c.27 0 .48-.11.69-.31.2-.19.3-.42.31-.69H8V7.98v.01zM7 2.3c-3.14 0-5.7 2.54-5.7 5.68 0 3.14 2.56 5.7 5.7 5.7s5.7-2.55 5.7-5.7c0-3.15-2.56-5.69-5.7-5.69v.01zM7 .98c3.86 0 7 3.14 7 7s-3.14 7-7 7-7-3.12-7-7 3.14-7 7-7z"></path></svg></span>SQL Schema Format</div><div class="admonitionContent_bl22"><p>You can also define your schema using SQL files. In that case, the environment must include a
<code>dev</code> attribute pointing to the <a class="" href="https://atlasgo.io/concepts/dev-database">dev-database</a>.</p></div></div>
<h2 class="anchor anchorTargetStickyNavbar_SAay" id="using-extensions-in-application-schemas">Using extensions in application schemas<a href="https://atlasgo.io/faq/manage-extension-only#using-extensions-in-application-schemas" class="hash-link" aria-label="Direct link to Using extensions in application schemas" title="Direct link to Using extensions in application schemas" translate="no">​</a></h2>
<p>After moving the extensions to a separate migrations process, the application schemas that rely on them must have these
extensions pre-installed in their development environments. The same assumption applies to staging and production environments.</p>
<p>Let's use a <code>docker</code> block with a <code>baseline</code> script to set up such a database:</p>
<div class="language-hcl codeBlockContainer_ZGJx theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockContent_kX1v"><pre tabindex="0" class="prism-code language-hcl codeBlock_TAPP thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_AdAo"><span class="token-line" style="color:#bfc7d5"><span class="token plain">docker </span><span class="token string" style="color:rgb(195, 232, 141)">"postgres"</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"dev"</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token property">image</span><span class="token plain">  </span><span class="token punctuation" style="color:rgb(199, 146, 234)">=</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"postgres:15"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token property">schema</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">=</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"public"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token property">baseline</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">=</span><span class="token plain"> </span><span class="token heredoc string" style="color:rgb(195, 232, 141)">&lt;&lt;SQL</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token heredoc string" style="color:rgb(195, 232, 141)">   CREATE EXTENSION "citext";</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token heredoc string" style="color:rgb(195, 232, 141)">   CREATE EXTENSION "fuzzystrmatch";</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token heredoc string" style="color:rgb(195, 232, 141)">  SQL</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token punctuation" style="color:rgb(199, 146, 234)">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">env </span><span class="token string" style="color:rgb(195, 232, 141)">"app"</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token property">src</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">=</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"file://app.sql"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token property">dev</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">=</span><span class="token plain"> docker.postgres.dev.url</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token punctuation" style="color:rgb(199, 146, 234)">}</span><br></span></code></pre></div></div>
<p>In your application schema (<code>app.sql</code>), you can then utilize the pre-installed extensions:</p>
<div class="language-sql codeBlockContainer_ZGJx theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockContent_kX1v"><pre tabindex="0" class="prism-code language-sql codeBlock_TAPP thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_AdAo"><span class="token-line" style="color:#bfc7d5"><span class="token keyword" style="font-style:italic">CREATE</span><span class="token plain"> </span><span class="token keyword" style="font-style:italic">TABLE</span><span class="token plain"> users </span><span class="token punctuation" style="color:rgb(199, 146, 234)">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">    id </span><span class="token keyword" style="font-style:italic">SERIAL</span><span class="token plain"> </span><span class="token keyword" style="font-style:italic">PRIMARY</span><span class="token plain"> </span><span class="token keyword" style="font-style:italic">KEY</span><span class="token punctuation" style="color:rgb(199, 146, 234)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">    username </span><span class="token keyword" style="font-style:italic">varchar</span><span class="token punctuation" style="color:rgb(199, 146, 234)">(</span><span class="token number" style="color:rgb(247, 140, 108)">100</span><span class="token punctuation" style="color:rgb(199, 146, 234)">)</span><span class="token plain"> </span><span class="token keyword" style="font-style:italic">UNIQUE</span><span class="token punctuation" style="color:rgb(199, 146, 234)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">    email CITEXT </span><span class="token keyword" style="font-style:italic">UNIQUE</span><span class="token plain"> </span><span class="token comment" style="color:rgb(105, 112, 152);font-style:italic">-- The "citext" type is provided by the "citext" extension.</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token punctuation" style="color:rgb(199, 146, 234)">)</span><span class="token punctuation" style="color:rgb(199, 146, 234)">;</span><br></span></code></pre></div></div>
<p>After setting up the <code>app</code> environment, all Atlas <code>schema</code>/<code>migrate</code> commands will first create a temporary database with
the required extensions installed, and then load the schema onto it.</p>]]></content:encoded>
            <category>postgres-extension</category>
            <category>manage-specific-resource</category>
            <category>apply-include-flag</category>
        </item>
        <item>
            <title><![CDATA[How to manage schema migration for a single table in a large schema]]></title>
            <link>https://atlasgo.io/faq/manage-single-table</link>
            <guid>https://atlasgo.io/faq/manage-single-table</guid>
            <pubDate>Fri, 20 Nov 2026 20:08:41 GMT</pubDate>
            <description><![CDATA[How to apply schema changes to a specific table without affecting other tables.]]></description>
            <content:encoded><![CDATA[<p>Given a large database schema, how can I manage schema migration for a single table without affecting the rest of the schema?</p>
<h3 class="anchor anchorTargetStickyNavbar_SAay" id="answer">Answer<a href="https://atlasgo.io/faq/manage-single-table#answer" class="hash-link" aria-label="Direct link to Answer" title="Direct link to Answer" translate="no">​</a></h3>
<p>Atlas supports the <code>--include</code> flag (or the <code>env.include</code> attribute) to scope operations to specific resources.
If you need to manage the lifecycle of a single table (or a set of tables), use this flag to avoid changes to the rest
of the schema.</p>
<p>For example, to manage the <code>products</code> table in a MySQL database:</p>
<div class="language-bash codeBlockContainer_ZGJx theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockContent_kX1v"><pre tabindex="0" class="prism-code language-bash codeBlock_TAPP thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_AdAo"><span class="token-line" style="color:#bfc7d5"><span class="token plain">atlas schema apply </span><span class="token punctuation" style="color:rgb(199, 146, 234)">\</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token parameter variable" style="color:rgb(191, 199, 213)">--url</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"mysql://root:pass@:3308/db"</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">\</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token parameter variable" style="color:rgb(191, 199, 213)">--to</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"file://schema.sql"</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">\</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  --dev-url </span><span class="token string" style="color:rgb(195, 232, 141)">"docker://mysql/8/dev"</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">\</span><span class="token plain"></span><br></span><span class="token-line theme-code-block-highlighted-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token parameter variable" style="color:rgb(191, 199, 213)">--include</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"products"</span><br></span></code></pre></div></div>
<p>If the connection URL is not bound to a schema, specify the schema name in the pattern:</p>
<div class="language-bash codeBlockContainer_ZGJx theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockContent_kX1v"><pre tabindex="0" class="prism-code language-bash codeBlock_TAPP thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_AdAo"><span class="token-line" style="color:#bfc7d5"><span class="token plain">atlas schema apply </span><span class="token punctuation" style="color:rgb(199, 146, 234)">\</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token parameter variable" style="color:rgb(191, 199, 213)">--url</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"mysql://root:pass@:3308/"</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">\</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token parameter variable" style="color:rgb(191, 199, 213)">--to</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"file://schema.sql"</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">\</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  --dev-url </span><span class="token string" style="color:rgb(195, 232, 141)">"docker://mysql/8"</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">\</span><span class="token plain"></span><br></span><span class="token-line theme-code-block-highlighted-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token parameter variable" style="color:rgb(191, 199, 213)">--include</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"db.products"</span><br></span></code></pre></div></div>
<p>This command will only apply changes related to the <code>products</code> table, leaving other tables untouched.</p>
<div class="theme-admonition theme-admonition-info admonition_IZjC alert alert--info"><div class="admonitionHeading_uVvU"><span class="admonitionIcon_HiR3"><svg viewBox="0 0 14 16"><path fill-rule="evenodd" d="M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"></path></svg></span>Wildcard Support</div><div class="admonitionContent_bl22"><p>If the table exists in multiple schemas (tenants), you can use wildcards to include it across all schemas. For example:</p><div class="language-bash codeBlockContainer_ZGJx theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockContent_kX1v"><pre tabindex="0" class="prism-code language-bash codeBlock_TAPP thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_AdAo"><span class="token-line" style="color:#bfc7d5"><span class="token plain">atlas schema apply </span><span class="token punctuation" style="color:rgb(199, 146, 234)">\</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token parameter variable" style="color:rgb(191, 199, 213)">--url</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"mysql://root:pass@:3308/"</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">\</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token parameter variable" style="color:rgb(191, 199, 213)">--to</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"file://schema.sql"</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">\</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  --dev-url </span><span class="token string" style="color:rgb(195, 232, 141)">"docker://mysql/8"</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">\</span><span class="token plain"></span><br></span><span class="token-line theme-code-block-highlighted-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token parameter variable" style="color:rgb(191, 199, 213)">--include</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"*.products"</span><br></span></code></pre></div></div></div></div>
<p>Read more:</p>
<ul>
<li class=""><a class="" href="https://atlasgo.io/inspect#exclude-tables">Exclude Tables</a></li>
<li class=""><a class="" href="https://atlasgo.io/concepts/url#scope">URL Connection Scope</a></li>
<li class=""><a class="" href="https://atlasgo.io/declarative/apply">Declarative Schema Migration</a></li>
</ul>]]></content:encoded>
            <category>faq</category>
            <category>include-flag</category>
            <category>manage-single-table</category>
        </item>
        <item>
            <title><![CDATA[Inspect an external schema data source (ORM schema)]]></title>
            <link>https://atlasgo.io/faq/inspect-external-schema</link>
            <guid>https://atlasgo.io/faq/inspect-external-schema</guid>
            <pubDate>Fri, 20 Nov 2026 20:08:41 GMT</pubDate>
            <description><![CDATA[Learn how to verify that Atlas can properly load and read an external_schema data source defined in atlas.hcl.]]></description>
            <content:encoded><![CDATA[<p>How to inspect an <code>external_schema</code> data source (ORM schema) in <code>atlas.hcl</code> to confirm it loaded correctly?</p>
<h2 class="anchor anchorTargetStickyNavbar_SAay" id="answer">Answer<a href="https://atlasgo.io/faq/inspect-external-schema#answer" class="hash-link" aria-label="Direct link to Answer" title="Direct link to Answer" translate="no">​</a></h2>
<p>When defining an <code>external_schema</code> data source in <code>atlas.hcl</code>, it serves as a schema source that can be used as the desired state. To confirm Atlas can load it correctly, verify that the ORM-generated schema is properly interpreted by running <code>atlas schema inspect</code> against it.</p>
<p>To verify that Atlas can read and load the ORM-generated schema correctly, run <code>atlas schema inspect</code> against the <code>src</code> of your environment.</p>
<div class="theme-admonition theme-admonition-info admonition_IZjC alert alert--info"><div class="admonitionHeading_uVvU"><span class="admonitionIcon_HiR3"><svg viewBox="0 0 14 16"><path fill-rule="evenodd" d="M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"></path></svg></span>info</div><div class="admonitionContent_bl22"><p>By default, <code>inspect</code> uses the <code>url</code> defined in the environment block. To load the schema from the external source instead, override it with <code>--url env://src</code>.</p></div></div>
<h3 class="anchor anchorTargetStickyNavbar_SAay" id="example-configuration">Example Configuration<a href="https://atlasgo.io/faq/inspect-external-schema#example-configuration" class="hash-link" aria-label="Direct link to Example Configuration" title="Direct link to Example Configuration" translate="no">​</a></h3>
<p>Consider the following <code>atlas.hcl</code> configuration:</p>
<div class="language-hcl codeBlockContainer_ZGJx theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockTitle_L5qy">atlas.hcl</div><div class="codeBlockContent_kX1v"><pre tabindex="0" class="prism-code language-hcl codeBlock_TAPP thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_AdAo"><span class="token-line" style="color:#bfc7d5"><span class="token keyword" style="font-style:italic">data </span><span class="token keyword type variable" style="font-style:italic;color:rgb(191, 199, 213)">"external_schema"</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"gorm"</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token property">program</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">=</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">[</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">    </span><span class="token string" style="color:rgb(195, 232, 141)">"go"</span><span class="token plain">, </span><span class="token string" style="color:rgb(195, 232, 141)">"run"</span><span class="token plain">,</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">    </span><span class="token string" style="color:rgb(195, 232, 141)">"ariga.io/atlas-provider-gorm"</span><span class="token plain">, </span><span class="token string" style="color:rgb(195, 232, 141)">"load"</span><span class="token plain">,</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">    </span><span class="token string" style="color:rgb(195, 232, 141)">"--path"</span><span class="token plain">, </span><span class="token string" style="color:rgb(195, 232, 141)">"./path/to/models"</span><span class="token plain">,</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">    </span><span class="token string" style="color:rgb(195, 232, 141)">"--dialect"</span><span class="token plain">, </span><span class="token string" style="color:rgb(195, 232, 141)">"postgres"</span><span class="token plain">,</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token punctuation" style="color:rgb(199, 146, 234)">]</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token punctuation" style="color:rgb(199, 146, 234)">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">env </span><span class="token string" style="color:rgb(195, 232, 141)">"gorm"</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token property">src</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">=</span><span class="token plain"> data.external_schema.gorm.url</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token property">dev</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">=</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"docker://postgres/15/dev?search_path=public"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token punctuation" style="color:rgb(199, 146, 234)">}</span><br></span></code></pre></div></div>
<h3 class="anchor anchorTargetStickyNavbar_SAay" id="basic-inspection">Basic Inspection<a href="https://atlasgo.io/faq/inspect-external-schema#basic-inspection" class="hash-link" aria-label="Direct link to Basic Inspection" title="Direct link to Basic Inspection" translate="no">​</a></h3>
<p>To verify that the ORM schema loads correctly, run:</p>
<div class="language-bash codeBlockContainer_ZGJx theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockContent_kX1v"><pre tabindex="0" class="prism-code language-bash codeBlock_TAPP thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_AdAo"><span class="token-line" style="color:#bfc7d5"><span class="token plain">atlas schema inspect </span><span class="token parameter variable" style="color:rgb(191, 199, 213)">--env</span><span class="token plain"> gorm </span><span class="token parameter variable" style="color:rgb(191, 199, 213)">--url</span><span class="token plain"> env://src</span><br></span></code></pre></div></div>
<p>This command tells Atlas to read the schema from the <code>external_schema</code> data source and outputs it in HCL format, allowing you to verify that the ORM-generated schema was loaded as expected.</p>
<h3 class="anchor anchorTargetStickyNavbar_SAay" id="interactive-visualization-">Interactive Visualization <span class="badge login badge--info" style="font-size:12px"><a style="color:white;text-decoration:none" href="https://atlasgo.io/features#pro">Atlas Pro</a></span><a href="https://atlasgo.io/faq/inspect-external-schema#interactive-visualization-" class="hash-link" aria-label="Direct link to interactive-visualization-" title="Direct link to interactive-visualization-" translate="no">​</a></h3>
<p>To visualize the schema interactively, add the <code>-w</code> flag:</p>
<div class="language-bash codeBlockContainer_ZGJx theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockContent_kX1v"><pre tabindex="0" class="prism-code language-bash codeBlock_TAPP thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_AdAo"><span class="token-line" style="color:#bfc7d5"><span class="token plain">atlas schema inspect </span><span class="token parameter variable" style="color:rgb(191, 199, 213)">--env</span><span class="token plain"> gorm </span><span class="token parameter variable" style="color:rgb(191, 199, 213)">--url</span><span class="token plain"> env://src </span><span class="token parameter variable" style="color:rgb(191, 199, 213)">-w</span><br></span></code></pre></div></div>
<p>This opens a browser window with an ERD (Entity Relationship Diagram) of the schema loaded from your ORM, providing a visual confirmation that the schema structure is correct.</p>
<h3 class="anchor anchorTargetStickyNavbar_SAay" id="sql-format-output">SQL Format Output<a href="https://atlasgo.io/faq/inspect-external-schema#sql-format-output" class="hash-link" aria-label="Direct link to SQL Format Output" title="Direct link to SQL Format Output" translate="no">​</a></h3>
<p>To get an SQL representation of the schema instead of HCL, use the <code>--format</code> flag:</p>
<div class="language-bash codeBlockContainer_ZGJx theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockContent_kX1v"><pre tabindex="0" class="prism-code language-bash codeBlock_TAPP thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_AdAo"><span class="token-line" style="color:#bfc7d5"><span class="token plain">atlas schema inspect </span><span class="token parameter variable" style="color:rgb(191, 199, 213)">--env</span><span class="token plain"> gorm </span><span class="token parameter variable" style="color:rgb(191, 199, 213)">--url</span><span class="token plain"> env://src </span><span class="token parameter variable" style="color:rgb(191, 199, 213)">--format</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">'{{ sql . }}'</span><br></span></code></pre></div></div>
<p>This is particularly useful when you want to see the actual SQL DDL statements that represent your ORM schema.</p>
<h3 class="anchor anchorTargetStickyNavbar_SAay" id="common-use-cases">Common Use Cases<a href="https://atlasgo.io/faq/inspect-external-schema#common-use-cases" class="hash-link" aria-label="Direct link to Common Use Cases" title="Direct link to Common Use Cases" translate="no">​</a></h3>
<p>This inspection technique is especially valuable when:</p>
<ul>
<li class="">Setting up a new <code>external_schema</code> data source for the first time</li>
<li class="">Debugging issues with ORM schema generation</li>
<li class="">Validating that schema changes from your ORM are reflected correctly</li>
<li class="">Ensuring your ORM schema (like GORM, Django ORM, etc.) is generating the expected schema structure</li>
</ul>
<h3 class="anchor anchorTargetStickyNavbar_SAay" id="troubleshooting">Troubleshooting<a href="https://atlasgo.io/faq/inspect-external-schema#troubleshooting" class="hash-link" aria-label="Direct link to Troubleshooting" title="Direct link to Troubleshooting" translate="no">​</a></h3>
<p>If the inspection fails, check:</p>
<ol>
<li class=""><strong>Program accessibility</strong>: Ensure the ORM provider program specified in the <code>external_schema</code> is available and executable</li>
<li class=""><strong>Path correctness</strong>: Verify that paths in the program arguments are correct relative to the working directory</li>
<li class=""><strong>Dependencies</strong>: Make sure all required dependencies for your ORM provider are installed</li>
</ol>]]></content:encoded>
            <category>faq</category>
            <category>external_schema</category>
            <category>atlas.hcl</category>
            <category>schema inspection</category>
            <category>data source</category>
        </item>
        <item>
            <title><![CDATA[Inspect a specific schema resource using the --include flag]]></title>
            <link>https://atlasgo.io/faq/inspect-include-flag</link>
            <guid>https://atlasgo.io/faq/inspect-include-flag</guid>
            <pubDate>Fri, 20 Nov 2026 20:08:41 GMT</pubDate>
            <description><![CDATA[Learn how to inspect a specific resource such as a table, view, or function using the `--include` flag in `atlas schema inspect`.]]></description>
            <content:encoded><![CDATA[<p>How can I inspect a specific resource, such as a function, view, or table, using the schema <code>--include</code> flag?</p>
<h2 class="anchor anchorTargetStickyNavbar_SAay" id="answer">Answer<a href="https://atlasgo.io/faq/inspect-include-flag#answer" class="hash-link" aria-label="Direct link to Answer" title="Direct link to Answer" translate="no">​</a></h2>
<p>The <code>atlas schema inspect</code> command provides an <code>--include</code> flag that allows you to retrieve the schema definition of one or more objects
while ignoring the rest of the schema. There is the option of including the objects' children, as well.</p>
<p>This feature is useful when working with large schemas, allowing you to view or troubleshoot a smaller scope without being overwhelmed by unrelated objects.</p>
<div class="theme-admonition theme-admonition-note admonition_IZjC alert alert--secondary"><div class="admonitionHeading_uVvU"><span class="admonitionIcon_HiR3"><svg viewBox="0 0 14 16"><path fill-rule="evenodd" d="M6.3 5.69a.942.942 0 0 1-.28-.7c0-.28.09-.52.28-.7.19-.18.42-.28.7-.28.28 0 .52.09.7.28.18.19.28.42.28.7 0 .28-.09.52-.28.7a1 1 0 0 1-.7.3c-.28 0-.52-.11-.7-.3zM8 7.99c-.02-.25-.11-.48-.31-.69-.2-.19-.42-.3-.69-.31H6c-.27.02-.48.13-.69.31-.2.2-.3.44-.31.69h1v3c.02.27.11.5.31.69.2.2.42.31.69.31h1c.27 0 .48-.11.69-.31.2-.19.3-.42.31-.69H8V7.98v.01zM7 2.3c-3.14 0-5.7 2.54-5.7 5.68 0 3.14 2.56 5.7 5.7 5.7s5.7-2.55 5.7-5.7c0-3.15-2.56-5.69-5.7-5.69v.01zM7 .98c3.86 0 7 3.14 7 7s-3.14 7-7 7-7-3.12-7-7 3.14-7 7-7z"></path></svg></span>Atlas Pro Require</div><div class="admonitionContent_bl22"><p>Unlike the <code>--exclude</code> flag, <code>--include</code> is an <strong>Atlas Pro</strong> feature and is currently available only for the <code>schema inspect</code> command.</p></div></div>
<p>Given the following schema:</p>
<div class="language-sql codeBlockContainer_ZGJx theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockContent_kX1v"><pre tabindex="0" class="prism-code language-sql codeBlock_TAPP thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_AdAo"><span class="token-line" style="color:#bfc7d5"><span class="token comment" style="color:rgb(105, 112, 152);font-style:italic">-- Table</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token keyword" style="font-style:italic">CREATE</span><span class="token plain"> </span><span class="token keyword" style="font-style:italic">TABLE</span><span class="token plain"> users </span><span class="token punctuation" style="color:rgb(199, 146, 234)">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  id </span><span class="token keyword" style="font-style:italic">serial</span><span class="token plain"> </span><span class="token keyword" style="font-style:italic">PRIMARY</span><span class="token plain"> </span><span class="token keyword" style="font-style:italic">KEY</span><span class="token punctuation" style="color:rgb(199, 146, 234)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  name </span><span class="token keyword" style="font-style:italic">text</span><span class="token plain"> </span><span class="token operator" style="color:rgb(137, 221, 255)">NOT</span><span class="token plain"> </span><span class="token boolean" style="color:rgb(255, 88, 116)">NULL</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token punctuation" style="color:rgb(199, 146, 234)">)</span><span class="token punctuation" style="color:rgb(199, 146, 234)">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token comment" style="color:rgb(105, 112, 152);font-style:italic">-- Function</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token keyword" style="font-style:italic">CREATE</span><span class="token plain"> </span><span class="token keyword" style="font-style:italic">FUNCTION</span><span class="token plain"> get_user_count</span><span class="token punctuation" style="color:rgb(199, 146, 234)">(</span><span class="token punctuation" style="color:rgb(199, 146, 234)">)</span><span class="token plain"> </span><span class="token keyword" style="font-style:italic">RETURNS</span><span class="token plain"> </span><span class="token keyword" style="font-style:italic">integer</span><span class="token plain"> </span><span class="token keyword" style="font-style:italic">AS</span><span class="token plain"> $$</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token keyword" style="font-style:italic">BEGIN</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token keyword" style="font-style:italic">RETURN</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">(</span><span class="token keyword" style="font-style:italic">SELECT</span><span class="token plain"> </span><span class="token function" style="color:rgb(130, 170, 255)">COUNT</span><span class="token punctuation" style="color:rgb(199, 146, 234)">(</span><span class="token operator" style="color:rgb(137, 221, 255)">*</span><span class="token punctuation" style="color:rgb(199, 146, 234)">)</span><span class="token plain"> </span><span class="token keyword" style="font-style:italic">FROM</span><span class="token plain"> users</span><span class="token punctuation" style="color:rgb(199, 146, 234)">)</span><span class="token punctuation" style="color:rgb(199, 146, 234)">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token keyword" style="font-style:italic">END</span><span class="token punctuation" style="color:rgb(199, 146, 234)">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">$$ </span><span class="token keyword" style="font-style:italic">LANGUAGE</span><span class="token plain"> plpgsql</span><span class="token punctuation" style="color:rgb(199, 146, 234)">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token comment" style="color:rgb(105, 112, 152);font-style:italic">-- View</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token keyword" style="font-style:italic">CREATE</span><span class="token plain"> </span><span class="token keyword" style="font-style:italic">VIEW</span><span class="token plain"> active_users </span><span class="token keyword" style="font-style:italic">AS</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token keyword" style="font-style:italic">SELECT</span><span class="token plain"> id</span><span class="token punctuation" style="color:rgb(199, 146, 234)">,</span><span class="token plain"> name </span><span class="token keyword" style="font-style:italic">FROM</span><span class="token plain"> users </span><span class="token keyword" style="font-style:italic">WHERE</span><span class="token plain"> name </span><span class="token operator" style="color:rgb(137, 221, 255)">IS</span><span class="token plain"> </span><span class="token operator" style="color:rgb(137, 221, 255)">NOT</span><span class="token plain"> </span><span class="token boolean" style="color:rgb(255, 88, 116)">NULL</span><span class="token punctuation" style="color:rgb(199, 146, 234)">;</span><br></span></code></pre></div></div>
<p>Below are a few examples of how to inspect specific resources in this schema:</p>
<div class="theme-admonition theme-admonition-note admonition_IZjC alert alert--secondary"><div class="admonitionHeading_uVvU"><span class="admonitionIcon_HiR3"><svg viewBox="0 0 14 16"><path fill-rule="evenodd" d="M6.3 5.69a.942.942 0 0 1-.28-.7c0-.28.09-.52.28-.7.19-.18.42-.28.7-.28.28 0 .52.09.7.28.18.19.28.42.28.7 0 .28-.09.52-.28.7a1 1 0 0 1-.7.3c-.28 0-.52-.11-.7-.3zM8 7.99c-.02-.25-.11-.48-.31-.69-.2-.19-.42-.3-.69-.31H6c-.27.02-.48.13-.69.31-.2.2-.3.44-.31.69h1v3c.02.27.11.5.31.69.2.2.42.31.69.31h1c.27 0 .48-.11.69-.31.2-.19.3-.42.31-.69H8V7.98v.01zM7 2.3c-3.14 0-5.7 2.54-5.7 5.68 0 3.14 2.56 5.7 5.7 5.7s5.7-2.55 5.7-5.7c0-3.15-2.56-5.69-5.7-5.69v.01zM7 .98c3.86 0 7 3.14 7 7s-3.14 7-7 7-7-3.12-7-7 3.14-7 7-7z"></path></svg></span>note</div><div class="admonitionContent_bl22"><p>Since our DDL statements are not schema-qualified, we assume the work is done within a specific schema (e.g., <code>public</code> in PostgreSQL).
Therefore, the top-level objects in our definitions are tables, views, functions, and so on. Read more about <a class="" href="https://atlasgo.io/concepts/url#scope">Schema vs. Database Scope</a>.</p></div></div>
<h3 class="anchor anchorTargetStickyNavbar_SAay" id="query-a-specific-function-by-its-name">Query a specific function by its name<a href="https://atlasgo.io/faq/inspect-include-flag#query-a-specific-function-by-its-name" class="hash-link" aria-label="Direct link to Query a specific function by its name" title="Direct link to Query a specific function by its name" translate="no">​</a></h3>
<p>By default, the <code>--include</code> flag keeps only resources that match the given glob, allowing you to target specific objects by their names.</p>
<div class="language-bash codeBlockContainer_ZGJx theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockContent_kX1v"><pre tabindex="0" class="prism-code language-bash codeBlock_TAPP thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_AdAo"><span class="token-line" style="color:#bfc7d5"><span class="token plain">atlas schema inspect </span><span class="token parameter variable" style="color:rgb(191, 199, 213)">--env</span><span class="token plain"> </span><span class="token builtin class-name" style="color:rgb(255, 203, 107)">local</span><span class="token plain"> </span><span class="token parameter variable" style="color:rgb(191, 199, 213)">--include</span><span class="token plain"> get_user_count</span><br></span></code></pre></div></div>
<p>The default output of <code>schema inspect</code> is formatted in HCL. To retrieve the SQL definition of the resource instead, use the <code>--format</code> flag:</p>
<div class="language-bash codeBlockContainer_ZGJx theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockContent_kX1v"><pre tabindex="0" class="prism-code language-bash codeBlock_TAPP thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_AdAo"><span class="token-line" style="color:#bfc7d5"><span class="token plain">atlas schema inspect </span><span class="token parameter variable" style="color:rgb(191, 199, 213)">--env</span><span class="token plain"> </span><span class="token builtin class-name" style="color:rgb(255, 203, 107)">local</span><span class="token plain"> </span><span class="token parameter variable" style="color:rgb(191, 199, 213)">--include</span><span class="token plain"> get_user_count </span><span class="token parameter variable" style="color:rgb(191, 199, 213)">--format</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">'{{ sql . }}'</span><br></span></code></pre></div></div>
<h3 class="anchor anchorTargetStickyNavbar_SAay" id="query-multiple-resources-by-their-names">Query multiple resources by their names<a href="https://atlasgo.io/faq/inspect-include-flag#query-multiple-resources-by-their-names" class="hash-link" aria-label="Direct link to Query multiple resources by their names" title="Direct link to Query multiple resources by their names" translate="no">​</a></h3>
<p>The command below includes the definitions of both the <code>get_user_count</code> function and the <code>active_users</code> view.</p>
<div class="language-bash codeBlockContainer_ZGJx theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockContent_kX1v"><pre tabindex="0" class="prism-code language-bash codeBlock_TAPP thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_AdAo"><span class="token-line" style="color:#bfc7d5"><span class="token plain">atlas schema inspect </span><span class="token parameter variable" style="color:rgb(191, 199, 213)">--env</span><span class="token plain"> </span><span class="token builtin class-name" style="color:rgb(255, 203, 107)">local</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">\</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token parameter variable" style="color:rgb(191, 199, 213)">--include</span><span class="token plain"> get_user_count </span><span class="token punctuation" style="color:rgb(199, 146, 234)">\</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token parameter variable" style="color:rgb(191, 199, 213)">--include</span><span class="token plain"> active_users</span><br></span></code></pre></div></div>
<p>Another option to achieve this is to use a glob pattern:</p>
<div class="language-bash codeBlockContainer_ZGJx theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockContent_kX1v"><pre tabindex="0" class="prism-code language-bash codeBlock_TAPP thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_AdAo"><span class="token-line" style="color:#bfc7d5"><span class="token plain">atlas schema inspect </span><span class="token parameter variable" style="color:rgb(191, 199, 213)">--env</span><span class="token plain"> </span><span class="token builtin class-name" style="color:rgb(255, 203, 107)">local</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">\</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token parameter variable" style="color:rgb(191, 199, 213)">--include</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"*_user*"</span><br></span></code></pre></div></div>
<h3 class="anchor anchorTargetStickyNavbar_SAay" id="query-resources-by-their-resource-type">Query resources by their resource type<a href="https://atlasgo.io/faq/inspect-include-flag#query-resources-by-their-resource-type" class="hash-link" aria-label="Direct link to Query resources by their resource type" title="Direct link to Query resources by their resource type" translate="no">​</a></h3>
<p>Glob patterns also accept a <code>type</code> selector, which can be used to match only specific types of resources. For example:</p>
<div class="language-bash codeBlockContainer_ZGJx theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockContent_kX1v"><pre tabindex="0" class="prism-code language-bash codeBlock_TAPP thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_AdAo"><span class="token-line" style="color:#bfc7d5"><span class="token plain">atlas schema inspect </span><span class="token parameter variable" style="color:rgb(191, 199, 213)">--env</span><span class="token plain"> </span><span class="token builtin class-name" style="color:rgb(255, 203, 107)">local</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">\</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token parameter variable" style="color:rgb(191, 199, 213)">--include</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"*[type=function]"</span><br></span></code></pre></div></div>
<h3 class="anchor anchorTargetStickyNavbar_SAay" id="qualified-resources">Qualified Resources<a href="https://atlasgo.io/faq/inspect-include-flag#qualified-resources" class="hash-link" aria-label="Direct link to Qualified Resources" title="Direct link to Qualified Resources" translate="no">​</a></h3>
<p>When the database URL is set at the database level (i.e., it does not specify a single schema but operates across multiple schemas),
the scope of work is database-wide.</p>
<p>In this case, the resources you reference with the <code>--include</code> flag must be schema-qualified. This means your glob patterns
should include a schema prefix to match objects such as functions and views. You can qualify the resource name in two ways:</p>
<p>Use an explicit schema prefix:</p>
<div class="language-sh codeBlockContainer_ZGJx theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockContent_kX1v"><pre tabindex="0" class="prism-code language-sh codeBlock_TAPP thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_AdAo"><span class="token-line" style="color:#bfc7d5"><span class="token parameter variable" style="color:rgb(191, 199, 213)">--include</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"public.resource_name"</span><br></span></code></pre></div></div>
<p>Or use a wildcard for the schema part, for example:</p>
<div class="language-sh codeBlockContainer_ZGJx theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockContent_kX1v"><pre tabindex="0" class="prism-code language-sh codeBlock_TAPP thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_AdAo"><span class="token-line" style="color:#bfc7d5"><span class="token parameter variable" style="color:rgb(191, 199, 213)">--include</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"*.resource_name"</span><br></span></code></pre></div></div>]]></content:encoded>
            <category>faq</category>
            <category>inspect-function</category>
            <category>inspect-view</category>
            <category>inspect-table</category>
            <category>inspect-specific-resource</category>
        </item>
        <item>
            <title><![CDATA[Using Migration Baseline in GitHub Actions]]></title>
            <link>https://atlasgo.io/faq/migrate-baseline-github-action</link>
            <guid>https://atlasgo.io/faq/migrate-baseline-github-action</guid>
            <pubDate>Fri, 20 Nov 2026 20:08:41 GMT</pubDate>
            <description><![CDATA[Learn how to configure migration baseline in Atlas GitHub Actions for existing databases.]]></description>
            <content:encoded><![CDATA[<h3 class="anchor anchorTargetStickyNavbar_SAay" id="question">Question<a href="https://atlasgo.io/faq/migrate-baseline-github-action#question" class="hash-link" aria-label="Direct link to Question" title="Direct link to Question" translate="no">​</a></h3>
<p>How to use the baseline option with <code>ariga/atlas-action/migrate/apply</code> when adopting Atlas for an existing database?</p>
<h3 class="anchor anchorTargetStickyNavbar_SAay" id="answer">Answer<a href="https://atlasgo.io/faq/migrate-baseline-github-action#answer" class="hash-link" aria-label="Direct link to Answer" title="Direct link to Answer" translate="no">​</a></h3>
<p>When adopting Atlas for an existing database that already has schema objects, you need to create a baseline migration
that reflects your current database schema. This step is required because it sets the starting point for Atlas's
versioning system. This lets future migrations safely reference existing schema elements, like adding a foreign key to
an existing table or creating a view that refers to existing tables.</p>
<div class="theme-admonition theme-admonition-note admonition_IZjC alert alert--secondary"><div class="admonitionHeading_uVvU"><span class="admonitionIcon_HiR3"><svg viewBox="0 0 14 16"><path fill-rule="evenodd" d="M6.3 5.69a.942.942 0 0 1-.28-.7c0-.28.09-.52.28-.7.19-.18.42-.28.7-.28.28 0 .52.09.7.28.18.19.28.42.28.7 0 .28-.09.52-.28.7a1 1 0 0 1-.7.3c-.28 0-.52-.11-.7-.3zM8 7.99c-.02-.25-.11-.48-.31-.69-.2-.19-.42-.3-.69-.31H6c-.27.02-.48.13-.69.31-.2.2-.3.44-.31.69h1v3c.02.27.11.5.31.69.2.2.42.31.69.31h1c.27 0 .48-.11.69-.31.2-.19.3-.42.31-.69H8V7.98v.01zM7 2.3c-3.14 0-5.7 2.54-5.7 5.68 0 3.14 2.56 5.7 5.7 5.7s5.7-2.55 5.7-5.7c0-3.15-2.56-5.69-5.7-5.69v.01zM7 .98c3.86 0 7 3.14 7 7s-3.14 7-7 7-7-3.12-7-7 3.14-7 7-7z"></path></svg></span>note</div><div class="admonitionContent_bl22"><p>When a migration is marked as baseline, Atlas adds it to the revisions (history) table without running the SQL in it,
but just marks it as already applied.</p></div></div>
<p>If you're using GitHub Actions for CI/CD, you can apply migrations with the <code>ariga/atlas-action/migrate/apply</code> action.
Since this action doesn't expose a direct <code>--baseline</code> flag, you'll need to configure the <code>baseline</code> setting in your
<code>atlas.hcl</code> file instead.</p>
<h3 class="anchor anchorTargetStickyNavbar_SAay" id="complete-workflow">Complete Workflow<a href="https://atlasgo.io/faq/migrate-baseline-github-action#complete-workflow" class="hash-link" aria-label="Direct link to Complete Workflow" title="Direct link to Complete Workflow" translate="no">​</a></h3>
<h4 class="anchor anchorTargetStickyNavbar_SAay" id="step-1-generate-a-baseline-migration">Step 1: Generate a Baseline Migration<a href="https://atlasgo.io/faq/migrate-baseline-github-action#step-1-generate-a-baseline-migration" class="hash-link" aria-label="Direct link to Step 1: Generate a Baseline Migration" title="Direct link to Step 1: Generate a Baseline Migration" translate="no">​</a></h4>
<p>First, create a migration that represents your existing database schema:</p>
<div class="language-bash codeBlockContainer_ZGJx theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockContent_kX1v"><pre tabindex="0" class="prism-code language-bash codeBlock_TAPP thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_AdAo"><span class="token-line" style="color:#bfc7d5"><span class="token plain">atlas migrate </span><span class="token function" style="color:rgb(130, 170, 255)">diff</span><span class="token plain"> baseline </span><span class="token punctuation" style="color:rgb(199, 146, 234)">\</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token parameter variable" style="color:rgb(191, 199, 213)">--dir</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"file://migrations"</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">\</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  --dev-url </span><span class="token string" style="color:rgb(195, 232, 141)">"docker://postgres/15/dev"</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">\</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token parameter variable" style="color:rgb(191, 199, 213)">--to</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"postgres://user:pass@host:5432/mydb"</span><br></span></code></pre></div></div>
<p>This creates a migration file like <code>20240115120000_baseline.sql</code> containing your current schema.</p>
<h4 class="anchor anchorTargetStickyNavbar_SAay" id="step-2-configure-baseline-in-atlashcl">Step 2: Configure Baseline in <code>atlas.hcl</code><a href="https://atlasgo.io/faq/migrate-baseline-github-action#step-2-configure-baseline-in-atlashcl" class="hash-link" aria-label="Direct link to step-2-configure-baseline-in-atlashcl" title="Direct link to step-2-configure-baseline-in-atlashcl" translate="no">​</a></h4>
<p>Add the baseline configuration to your <code>atlas.hcl</code>:</p>
<div class="language-hcl codeBlockContainer_ZGJx theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockTitle_L5qy">atlas.hcl</div><div class="codeBlockContent_kX1v"><pre tabindex="0" class="prism-code language-hcl codeBlock_TAPP thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_AdAo"><span class="token-line" style="color:#bfc7d5"><span class="token plain">env </span><span class="token string" style="color:rgb(195, 232, 141)">"prod"</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token property">url</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">=</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"postgres://user:pass@host:5432/mydb"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token keyword" style="font-style:italic">migration</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">    </span><span class="token property">dir</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">=</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"file://migrations"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">    </span><span class="token property">baseline</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">=</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"20240115120000"</span><span class="token plain">  </span><span class="token comment" style="color:rgb(105, 112, 152);font-style:italic"># Version without .sql extension</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token punctuation" style="color:rgb(199, 146, 234)">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token punctuation" style="color:rgb(199, 146, 234)">}</span><br></span></code></pre></div></div>
<h4 class="anchor anchorTargetStickyNavbar_SAay" id="step-3-use-github-action">Step 3: Use GitHub Action<a href="https://atlasgo.io/faq/migrate-baseline-github-action#step-3-use-github-action" class="hash-link" aria-label="Direct link to Step 3: Use GitHub Action" title="Direct link to Step 3: Use GitHub Action" translate="no">​</a></h4>
<p>The action will respect the baseline configuration:</p>
<div class="language-yaml codeBlockContainer_ZGJx theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockTitle_L5qy">.github/workflows/deploy.yml</div><div class="codeBlockContent_kX1v"><pre tabindex="0" class="prism-code language-yaml codeBlock_TAPP thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_AdAo"><span class="token-line" style="color:#bfc7d5"><span class="token punctuation" style="color:rgb(199, 146, 234)">-</span><span class="token plain"> </span><span class="token key atrule">name</span><span class="token punctuation" style="color:rgb(199, 146, 234)">:</span><span class="token plain"> Apply migrations</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token key atrule">uses</span><span class="token punctuation" style="color:rgb(199, 146, 234)">:</span><span class="token plain"> ariga/atlas</span><span class="token punctuation" style="color:rgb(199, 146, 234)">-</span><span class="token plain">action/migrate/apply@v1</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token key atrule">with</span><span class="token punctuation" style="color:rgb(199, 146, 234)">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">    </span><span class="token key atrule">config</span><span class="token punctuation" style="color:rgb(199, 146, 234)">:</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"file://path/to/atlas.hcl"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">    </span><span class="token key atrule">env</span><span class="token punctuation" style="color:rgb(199, 146, 234)">:</span><span class="token plain"> prod</span><br></span></code></pre></div></div>
<p>For more details on working with existing databases, see the <a class="" href="https://atlasgo.io/versioned/apply#existing-databases">versioned migrations documentation</a>.</p>]]></content:encoded>
            <category>baseline</category>
            <category>github actions</category>
        </item>
    </channel>
</rss>