How do I install Atlas on Windows and set up the PATH environment variable so I can run atlas from any directory?

Answer​

Installing Atlas on Windows involves two main steps: downloading the binary and adding it to your system's PATH environment variable.

Step 1: Download Atlas Binary​

1. Download the latest Atlas binary for Windows from the official release page.

2. Choose a permanent location for the Atlas binary. We recommend creating a dedicated directory such as:

   • C:\Program Files\Atlas\ (requires admin privileges)
   • C:\atlas\ (simpler, no admin needed)
   • %USERPROFILE%\atlas\ (user-specific installation)

3. Move or save the downloaded atlas-windows-amd64-latest.exe file to your chosen directory.

4. Rename the file to atlas.exe for convenience (optional but recommended).

Step 2: Add Atlas to PATH​

You can add Atlas to your PATH using either the GUI or PowerShell/Command Prompt.

Method 1: Using Windows GUI

1. Open System Properties:

   • Press Win + R, type sysdm.cpl, and press Enter
   • Or right-click This PC → Properties → Advanced system settings

2. Click Environment Variables at the bottom of the System Properties window.

3. In the User variables section (for current user only) or System variables section (for all users), find and select the Path variable.

4. Click Edit.

5. Click New and add the directory path where you saved atlas.exe (e.g., C:\atlas).

6. Click OK on all windows to save the changes.

7. Important: Close and reopen any open Command Prompt or PowerShell windows for the changes to take effect.

Method 2: Using PowerShell

For the current user only:

# Add to user PATH
$atlasPath = "C:\atlas"
$currentPath = [Environment]::GetEnvironmentVariable("Path", "User")
[Environment]::SetEnvironmentVariable("Path", "$currentPath;$atlasPath", "User")

For all users (requires running PowerShell as Administrator):

# Add to system PATH (run as Administrator)
$atlasPath = "C:\atlas"
$currentPath = [Environment]::GetEnvironmentVariable("Path", "Machine")
[Environment]::SetEnvironmentVariable("Path", "$currentPath;$atlasPath", "Machine")

Method 3: Using Command Prompt

For the current user only:

setx PATH "%PATH%;C:\atlas"

Note: The setx command permanently adds the directory to the user's PATH. You need to close and reopen Command Prompt for changes to take effect.

Step 3: Verify Installation​

After adding Atlas to your PATH, verify the installation:

1. Open a new Command Prompt or PowerShell window.

2. Run the following command:

atlas version

If the installation was successful, you should see the Atlas version information displayed.

If you get an error like 'atlas' is not recognized as an internal or external command, double-check that:

• The directory containing atlas.exe is correctly added to your PATH
• You've closed and reopened your terminal window
• The atlas.exe file exists in the specified directory

Troubleshooting​

PATH changes not taking effect

If you've added the directory to PATH but the atlas command still isn't recognized:

• Make sure you've closed and reopened all Command Prompt or PowerShell windows
• Try logging out and logging back in to Windows
• Verify the PATH was updated by running echo %PATH% (Command Prompt) or $env:Path (PowerShell)

Permission issues

If you encounter permission errors when downloading or moving files:

• Choose a directory where you have write permissions (e.g., %USERPROFILE%\atlas\)
• Or run Command Prompt or PowerShell as Administrator

Multiple Atlas versions

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:

where atlas

This command shows all locations where atlas.exe is found in your PATH.

Have additional questions or feedback? Feel free to reach out on our Discord server.

Is there a way to change which editor opens when I use the --edit flag while creating a migration?

Answer​

Yes. You can control which editor opens by setting the EDITOR environment variable.

When you run atlas migrate new with the --edit flag, Atlas checks the EDITOR environment variable to determine which text editor to launch. If EDITOR is not set, Atlas will use a default editor based on your operating system.

Examples​

To change the editor for a single command, you can set the EDITOR variable inline:

# Use vim
EDITOR=vim atlas migrate new add_users_table --edit

# Use nano
EDITOR=nano atlas migrate new add_users_table --edit

# Use VS Code (wait for the editor to close before continuing)
EDITOR="code --wait" atlas migrate new add_users_table --edit

Have additional questions or feedback? Feel free to reach out on our Discord server.

When using Atlas on my macOS, I can run atlas migrate apply without any issues, and it applies the migrations successfully. But when running in CI on linux, I get the following error: Error: checksum mismatch

Answer​

This issue is likely due to differences in line endings between operating systems. macOS uses LF (Line Feed) for line endings, while Windows uses CRLF (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.

To resolve this issue, you can try the following steps:

1. Add a .gitattributes file to your repository with the following content:

# Ensure all text files use LF line endings
* text=auto eol=lf

2. Commit the .gitattributes file to your repository.
3. 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:

# Remove all files from the index (but keep them on disk)
git rm --cached -r .
# Re-checkout the files from the repository
git reset --hard

Answer​

One option is to run atlas migrate diff --env=<ENV-NAME>, and then check that no files were generated by this command: status=$(git status --porcelain).

If an engineer forgot to run atlas migrate diff 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.

Another option is to use schema diff (with a custom --format) to detect changes and fail if there are any:

atlas schema diff \
  --from "file://migrations" \
  --to env://orm \
  --env local \
  --format '{{ if .Changes }}fail{{ end }}' | grep '.' && exit 1

(Alternatively, convert it to: if [ -n "$output" ]; then .. fi).

See more details, see schema diff documentation.

However, some users prefer to store their migration directories in S3, typically due to internal policies or requirements.

How to deploy migrations from S3 Atlas Pro​

To deploy migrations from S3, use the blob_dir data source in your atlas.hcl file:

data "blob_dir" "migrations" {
  url = "s3://my-s3-bucket/path/to/migrations?profile=aws-profile"
}

env "dev" {
  url = var.url
  migration {
    dir = data.blob_dir.migrations.url
  }
}

You can tell the profile query parameter to use a specific AWS profile through your local AWS credentials file, or set the credentials using environment variables AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY.

How to deploy from blob_dir in Terraform?​

To deploy migrations from S3 using the Atlas Terraform provider, use the atlas_migration resource in combination with a custom configuration block.

terraform {
  required_providers {
    atlas = {
      version = "0.9.8"
      source  = "ariga/atlas"
    }
  }
}

locals {
  config = <<HCL
variable "url" {
  type = string
  default = getenv("DB_URL")
}

variable "s3_bucket" {
  type = string
}

data "blob_dir" "migrations" {
  url = var.s3_bucket
}

env {
  name = atlas.env
  url  = var.url
  dev  = "docker://postgres/15/dev?search_path=public"
  migration {
    dir = data.blob_dir.migrations.url
  }
}
HCL
  vars = jsonencode({
    s3_bucket = "s3://my-s3-bucket/migrations?profile=tf-dev"
  })
}

data "atlas_migration" "hello" {
  config    = local.config
  variables = local.vars
  env_name  = "foo"
}

resource "atlas_migration" "testdb" {
  version   = data.atlas_migration.hello.latest
  config    = local.config
  variables = local.vars
  env_name  = "foo"
}

Assuming we have a local Postgres database running:

docker run --name some-postgres -p 5432:5432 -e POSTGRES_PASSWORD=mysecretpassword -d postgres

Set the environment variable DB_URL to connect to the database:

export DB_URL='export DB_URL='postgresql://postgres:mysecretpassword@localhost:5432?search_path=public&sslmode=disable'

Then, run the migration:

terraform apply

This will apply the latest migration from the S3 bucket specified in the s3_bucket variable:

data.atlas_migration.hello: Reading...
data.atlas_migration.hello: Read complete after 6s [id=8cld198f-23dd-61ca-0f97-2a3ealdf1fb6]
atlas_migration.testdb: Refreshing state... [id=7cac2593-a043-69f3-7383-ab1f27b14654]

Terraform used the selected providers to generate the following execution plan.
Resource actions are indicated with the following symbols:
  + create

Terraform will perform the following actions:

  # atlas_migration.testdb will be created
  + resource "atlas_migration" "testdb" {
      + config = <<-EOT
          variable "url" {
            type    = string
            default = getenv("DB_URL")
          }

          variable "s3_bucket" {
            type = string
          }

          data "blob_dir" "migrations" {
            url = var.s3_bucket
          }

          env {
            name = atlas.env
            url  = var.url
            dev  = "docker://postgres/15/dev?search_path=public"

            migration {
              dir = data.blob_dir.migrations.url
            }
          }
        EOT

      + env_name  = "foo"
      + id        = (known after apply)
      + status    = (known after apply)
      + variables = jsonencode({
          53_bucket = "s3://my-s3-bucket/migrations?profile=tf-dev"
        })
      + version   = "20250618181441"
    }

Plan: 1 to add, 0 to change, 0 to destroy.

Do you want to perform these actions?
  Terraform will perform the actions described above.
  Only 'yes' will be accepted to approve.

Enter a value: yes

atlas_migration.testdb: Creating...
atlas_migration.testdb: Still creating... [10s elapsed]
atlas_migration.testdb: Creation complete after 18s [id=d9eb9c09-0c95-fldd-46e0-0de31df39581]

Apply complete! Resources: 1 added, 0 changed, 0 destroyed.

Why does using a dev URL like docker://postgres/15/dev inside the official arigaio/atlas image fail with: exec: "docker": executable file not found in $PATH?

Answer​

Commands that use docker:// dev-database URLs (such as schema diff, schema apply, and migrate test) fail when run inside the Atlas Docker image. This is expected behavior.

The docker:// 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.

Where docker:// URLs Work​

The docker:// scheme is supported when:

• Running Atlas directly on a machine where docker is installed
• Running Atlas in a CI environment where docker is available (both docker client and docker daemon)
• Using custom container images that include the docker client and have access to the host docker daemon

Recommended Approach​

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:

1. Run a separate dev database container
2. Pass its connection URL to the Atlas container

For example:

env "local" {
  url  = getenv("DATABASE_URL")
  src  = "file://schema"
  dev  = "postgres://user:pass@dev-db:5432/dev?sslmode=disable"
}

This keeps Atlas isolated and avoids granting containers permissions to manage host resources.

Advanced Workaround​

If docker:// must be used inside a container, you can provide the docker CLI and daemon access to the Atlas container. For example:

docker run \
  --volume=/usr/local/bin/docker:/usr/local/bin/docker:ro \
  --add-host="host.docker.internal:$DOCKER_HOST" \
  arigaio/atlas:latest

This approach mounts the docker client into the container and requires the host docker daemon to be reachable (e.g., via host.docker.internal in Docker Desktop, or by mounting /var/run/docker.sock 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.).

Have additional questions or feedback? Feel free to reach out on our Discord server.

For developers who want to use .env files with Atlas, there are two ways users can do so through the standard Atlas HCL configuration file:

Write an HCL expression to load the file into Atlas​

First, create a string variable in your atlas.hcl file that will contain the content of your .env file. Next, use a local expression to split the string and create a map of your .env variable keys to their values. Now, your .env variables can be accessed by simply indexing this map with the name of your desired variable.

For example, let's say the URL to my database is defined in my .env file, so I'd like to use that variable in my atlas.hcl file rather than having it written out in two different places.

# ... more variables
DATABASE_URL=mysql://localhost:3306/dev
# ... more variables

variable "envfile" {
    type    = string
    default = "/path/to/.env"
}

locals {
    envfile = {
        for line in split("\n", file(var.envfile)): split("=", line)[0] => regex("=(.*)", line)[0]
        if !startswith(line, "#") && length(split("=", line)) > 1
    }
}

env {
    name = atlas.env
    url  = local.envfile["DATABASE_URL"]
}

Since I've loaded my .env variables into a local map, I can easily grab the URL to my database and apply it to env.url.

Use an external program​

If you have a .env reader/parser of choice, you can also integrate that external program into atlas.hcl so it can use its output.

Take the following implementation example:

data "external" "envfile" {
  program = [
    "node", "envfile.cjs"
  ]
}

locals {
  envfile = jsondecode(data.external.envfile)
}

env "local" {
  src = local.envfile.DATABASE_URL
}

const { loadEnvFile } = require('node:process');
loadEnvFile();
console.log(JSON.stringify(process.env));

First, we use node to run a Javascript file envfile.cjs that returns a string or JSON representation of the .env file. Then, we use jsondecode to read the JSON object or interpret the string as JSON to create a local object with the .env variables as its attributes. Finally, we can retrieve the values of the .env variables by accessing them from the envfile object.

Have additional questions or feedback? Feel free to reach out on our Discord server.

Answer​

When running Atlas against a PostgreSQL database with a dev-URL that includes search_path=public, you may notice that event_trigger objects are not included in the generated migration. This happens because:

• The search_path parameter scopes Atlas to inspect only a specific schema
• event_trigger objects (like extensions) are database-level objects, not schema-scoped
• As a result, they are excluded when Atlas inspects only within a schema scope

Solution​

Remove the search_path parameter from the --dev-url to ensure Atlas inspects at the database level. Here are examples of both problematic and correct configurations:

# This will detect event_trigger objects
atlas migrate diff --dev-url "docker://postgres/16/dev"

# This will NOT detect event_trigger objects
atlas migrate diff --dev-url "docker://postgres/16/dev?search_path=public"

Configuration File Example​

The same principle applies when using an atlas.hcl configuration file:

env "local" {
  dev = "docker://postgres/16/dev"
  // ... other configuration
}

env "local" {
  dev = "docker://postgres/16/dev?search_path=public"
  // ... other configuration
}

Why This Matters​

Event triggers are powerful PostgreSQL features that execute functions in response to DDL events. For example:

-- Create an event trigger that logs table creation
CREATE OR REPLACE FUNCTION record_table_creation()
RETURNS event_trigger AS $$
BEGIN
  RAISE NOTICE 'Table created: %', tg_tag;
END;
$$ LANGUAGE plpgsql;

CREATE EVENT TRIGGER record_table_creation
  ON ddl_command_start
  WHEN TAG IN ('CREATE TABLE')
  EXECUTE FUNCTION record_table_creation();

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.

Related Information​

For more details about database-level vs schema-level objects in PostgreSQL with Atlas, see:

• PostgreSQL Extensions FAQ - Extensions have the same database-level scoping behavior
• Database URL concepts - Understanding URL parameters and their effects

Why does atlas schema apply / atlas schema plan fail with an error like this when working with PostgreSQL extensions?

Answer​

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 dev-database.

To make sure migration plans are safe, Atlas does the following:

1. It first creates the current state (the database schema) on the dev-database
2. Applies the planned migration to it
3. Inspects the result and checks if it matches the desired target state

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.

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.

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.

Solutions​

There are several approaches to resolve this issue:

1. Use a dev-database with matching extension versions​

The most reliable solution is to ensure your dev-database has the same extension versions as your target database. You can:

Build a custom Docker image with the exact PostgreSQL and extension versions:

docker "postgres" "dev" {
  image = "postgres:16-custom"
  build {
    context    = "."
    dockerfile = "Dockerfile"
  }
}

env "dev" {
  url = "postgres://user:pass@host:5432/mydb"
  dev = docker.postgres.dev.url
}

FROM postgres:16.8
RUN apt-get update && apt-get install -y \
    postgresql-16-postgis-3.4.3 \
    && rm -rf /var/lib/apt/lists/*

2. Use a compatible pre-built image​

For PostGIS specifically, you can use the PostGIS Docker images that match your major version:

env "dev" {
  url = "postgres://user:pass@host:5432/mydb"
  dev = "docker://postgis/16-3.4/dev"
}

3. Use version 'ANY' for PostGIS extensions​

PostGIS supports installing any available version when you specify version = "ANY". This tells PostGIS to install whatever version is available in the system:

extension "postgis" {
  schema  = schema.public
  version = "ANY"
}

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.

4. Exclude extension versions from Atlas management​

You can tell Atlas to ignore extension versions entirely using the exclude attribute:

env "production" {
  url = "postgres://user:pass@host:5432/mydb"
  dev = "docker://postgres/16/dev"
  exclude = ["*[type=extension].version"]
}

Or use the --exclude flag when running commands:

atlas schema apply --env production --exclude "*[type=extension].version"

This allows Atlas to manage extensions without caring about specific versions, avoiding version mismatch errors while still tracking that extensions exist.

5. Manage extensions separately​

As mentioned in our extension management guide, you can also manage extensions outside of Atlas migrations. This approach treats extension upgrades as infrastructure changes rather than schema migrations:

1. Remove extension definitions from your schema files
2. Manage extensions through a separate deployment process
3. Let Atlas handle only tables, indexes, and other schema objects

This avoids version conflicts but requires additional coordination for extension management.

-- Create extension "postgis"
CREATE EXTENSION "postgis" WITH SCHEMA "public" VERSION "3.5.2";
-- Create "users" table
CREATE TABLE "public"."users" ("id" serial NOT NULL, "name" character varying NOT NULL, "email" character varying NOT 
NULL, "address" public.geometry(Point,4326) NOT NULL, PRIMARY KEY ("id"));
-- Create index "idx_users_address" to table: "users"
CREATE INDEX "idx_users_address" ON "public"."users" USING gist ("address");
-- Create index "ix_users_id" to table: "users"
CREATE INDEX "ix_users_id" ON "public"."users" ("id");

When using the GEOMETRY type, there are two common errors you may experience upon inspecting your schema with Atlas:

pq: extension "postgis" is not available​

This error suggests that your local dev database cannot enable the PostGIS extension.

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.

This is typically done in one of two ways:

Using a pre-built docker image​

In order to use the GEOMETRY type, we can use a PostGIS Docker image as the dev database.

The dev database URL can be provided via the dev attribute in the atlas.hcl configuration, e.g.:

env "example" {
  dev = "docker://postgis/latest/dev"
  // .. redacted for brevity
}

Alternatively, use the --dev-url command line flag to set the dev database:

atlas migrate diff --env example --dev-url "docker://postgis/latest/dev"

Providing a URL to an already running server that has PostGIS available​

If you already have a running server with PostGIS enabled, simply replace the dev attribute with your server's URL, e.g.:

env "example" {
  dev = "postgres://user:pass@hostname:5432/database"
  // .. redacted for brevity
}

atlas migrate diff --env example --dev-url "postgres://user:pass@hostname:5432/database&sslmode=disable"

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 search_path attribute in its URL, as this variable defines a schema scope.

pq: type "geometry" does not exist​

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.

CREATE EXTENSION postgis;

schema "public" {}

extension "postgis" {
  schema  = schema.public
  version = "3.4.2"
  comment = "PostGIS geometry and geography spatial types and functions"
}

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.

No ORM (only SQL/HCL)​

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 atlas.hcl file to connect your schema to your dev database.

env "local" {
  src = "file://schema.sql"   // schema file containing PostGIS extension creation
  dev = "docker://postgis/latest/dev"   // dev database
}

Using an ORM​

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.

In order for Atlas to work alongside your ORM, you need to install the corresponding Atlas provider. For SQLAlchemy, run:

pip install atlas-provider-sqlalchemy

1. 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.:

project-directory
├── models.py
├── schema.sql
└── atlas.hcl

2. In your atlas.hcl config file, add a composite_schema that includes both your extension definition and your models:

data "external_schema" "sqlalchemy" {
    program = [
        "atlas-provider-sqlalchemy",
        "--path", "./models.py",   // path to your SQLAlchemy models directory or file
        "--dialect", "postgresql"
    ]
}

data "composite_schema" "app" {
  # Load custom types first
  schema {
    url = "file://schema.sql"   // schema file containing PostGIS extension creation
  }
  # Then, load SQLAlchemy models
  schema "public" {
    url = data.external_schema.sqlalchemy.url
  }
}

env "local" {
  src = data.composite_schema.app.url   // link to current schema state
  dev = "docker://postgis/latest/dev"   // dev database
}

CREATE EXTENSION postgis;

// ... other extensions, baseline schema definitions, etc.

from sqlalchemy import Column, Integer, String, DateTime
from sqlalchemy.orm import DeclarativeBase
from geoalchemy2 import Geometry

class Base(DeclarativeBase):
    pass

class Users(Base):
    __tablename__ = "Users"
    id = Column(Integer, primary_key=True, index=True)
    name = Column(String, nullable=False)
    email = Column(String, nullable=False)
    address = Column(Geometry('POINT', srid=4326), nullable=False)

Run atlas schema inspect --env local --url env://src to check for additional errors. The expected output using the above example files should be:

table "Users" {
  schema = schema.public
  column "id" {
    null = false
    type = serial
  }
  column "name" {
    null = false
    type = character_varying
  }
  column "email" {
    null = false
    type = character_varying
  }
  column "address" {
    null = false
    type = sql("public.geometry(Point,4326)")
  }
  primary_key {
    columns = [column.id]
  }
  index "idx_Users_address" {
    columns = [column.address]
    type    = GIST
  }
  index "ix_Users_id" {
    columns = [column.id]
  }
}
extension "postgis" {
  schema  = schema.public
  version = "3.5.2"
  comment = "PostGIS geometry and geography spatial types and functions"
}
schema "public" {
  comment = "standard public schema"
}

Have additional questions or feedback? Feel free to reach out on our Discord server.

Answer​

• macOS + Linux
• Homebrew
• Docker
• Windows
• CI
• Manual Installation

To download and install the latest release of the Atlas CLI, simply run the following in your terminal:

curl -sSf https://atlasgo.sh | sh

Why doesn't go install work anymore?​

We no longer maintain the cmd/atlas 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 go install.

-- migrating version 20250324061649.down.sql
-> DROP TABLE `users`;
   Error 1051 (42S02): Unknown table 'public.users'

golang-migrate is a popular migration tool used in the Go community, and Atlas supports working with its migration directory format, amongst others, through basic configurations.

golang-migrate Migration Directory​

When creating schema migrations with golang-migrate, users create two empty files for each set of changes like so:

db/migrations
├── 20250324061649.down.sql
└── 20250324061649.up.sql

The files contain the intended schema changes (up) and the instructions to roll back these changes (down).

When applying migrations, you use the up command so golang-migrate knows to use the corresponding up files. When rolling back on migrations, you use the down command to golang-migrate knows to use the corresponding down files.

Applying Migrations with Atlas​

The standard migrations directory for Atlas does not contain separate up and down files. Instead, it only contains files with schema migrations and applies them all in order when running migrate apply and has a separate system for rollbacks.

If a user tries executing migrate apply 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 down files. Since Atlas runs the migration files in lexicographic order, the down files are typically run first, meaning that Atlas tries to run commands that revert changes that have yet to be made, leading to errors.

The Solution​

To ensure that only the up migration files are run, add the format flag to the env block in atlas.hcl either as a parameter:

env "dev" {
    ...
    migration {
        dir = "file://db/migrations"
        format = "golang-migrate"
    }
}

or as a flag in the directory link:

env "dev" {
    ...
    migration {
        dir = "file://db/migrations?format=golang-migrate"
    }
}

Alternatively, you can include the directory link with the ?format=golang-migrate flag in the command:

atlas migrate apply --dir "file://db/migrations?format=golang-migrate" --env dev

Defining a format value ensures that Atlas is aware that both up and down files exist in the migrations directory and it should only use the up files. These up files can have destructive commands in them, but they are not dropping objects that don't yet exist in the schema.

Example 1​

To ensure that the proper value is being assigned to a variable, simply wrap it in a print statement:

data "runtimevar" "myip" {
  url = "https://api.ipify.org?format=json"
}

locals {
  ip = print(data.runtimevar.myip)
}

env "test" {
  url = "mysql://user:pass@localhost:3306/my_db"
}

The print statement is evaluated when reached after running a command that accesses the file, such as atlas schema inspect --env test. After running the command, ip is printed and I see a JSON in the output where I expected a string containing my IP address:

{"ip":"127.0.0.1"}

Now I know to decode and index the JSON to get the proper output.

data "runtimevar" "myip" {
  url = "https://api.ipify.org?format=json"
}

locals {
  ip = print(jsondecode(data.runtimevar.myip)["ip"])
}

127.0.0.1

Example 2​

To ensure that an operation gives the proper result without assigning it to a variable, use the _ placeholder:

data "runtimevar" "myip" {
  url = "https://api.ipify.org?format=json"
}

locals {
  _ = print(data.runtimevar.myip)
}

Example 3​

Let's look at a more involved example that combines these two methods:

data "external" "envfile" {
    program = [
        "node",
        "./envfile.js"
    ]
}

locals {
  envfile = jsondecode(data.external.envfile)
}

env "test" {
  url = "mysql://${local.envfile.DB_USER}:${local.envfile.DB_PASS}@localhost:3306/${local.envfile.DB_NAME}"
  dev = "docker://mysql/latest/dev"
}

Here, I use a program defined in envfile.js that returns my .env file as a JSON object. Then, I'm using jsonencode to save the result as a local JSON variable to access the environment variables.

To check that the JSON encoding of my .env file and the resulting URL are correct, I can add print statements and see if I get the expected results:

data "external" "envfile" {
    program = [
        "node",
        "./envfile.js"
    ]
}

locals {
  envfile = jsondecode(data.external.envfile)
  _ = print(local.envfile["COMPANY_NAME"])
}

env "test" {
  url = print("mysql://${local.envfile.DB_USER}:${local.envfile.DB_PASS}@$localhost:3306/${local.envfile.DB_NAME}")
  dev = "docker://mysql/latest/dev"
}

At the beginning of my CLI output, we get the results of the print statements:

ariga
mysql://root:pass@localhost:3306/example

Keep in mind when placing print statements that their results are outputted as they are evaluated, so foreach statements could cause duplicate outputs, printing variables that have yet to be assigned could lead to errors, and so on.

Once installed, these extensions provide additional data types and objects that users' schemas can leverage. However, because extensions are managed at the database level (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.

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.

This guide demonstrates how to use the --include flag (or env.include argument) provided by Atlas to limit migrations specifically to PostgreSQL extensions.

Limit migration scope to extensions only​

Given a schema file named extensions.pg.hcl listing all extensions we expect to have in our database:

extension "fuzzystrmatch" {
  version = "1.1"
  comment = "Determine similarities and distance between strings"
}
extension "citext" {
  version = "1.6"
  comment = "Data type for case-insensitive character strings"
}

To define a migration process for it, we need to create a new environment in our atlas.hcl file:

env "extensions" {
  src     = "file://extensions.pg.hcl"
  url     = getenv("DATABASE_URL")
  include = ["*[type=extension]"]
}

The include argument will limit Atlas' scope to inspect and manage only the database extensions in this environment.

Then, running atlas schema apply --env extensions results in:

Applying approved migration (2 statements in total):

  -- create extension "fuzzystrmatch"
    -> CREATE EXTENSION "fuzzystrmatch" VERSION "1.1";
  -- ok (8.79975ms)

  -- create extension "citext"
    -> CREATE EXTENSION "citext" VERSION "1.6";
  -- ok (8.856958ms)

  -------------------------
  -- 17.845333ms
  -- 1 migration
  -- 2 sql statements

Using extensions in application schemas​

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.

Let's use a docker block with a baseline script to set up such a database:

docker "postgres" "dev" {
  image  = "postgres:15"
  schema = "public"
  baseline = <<SQL
   CREATE EXTENSION "citext";
   CREATE EXTENSION "fuzzystrmatch";
  SQL
}

env "app" {
  src = "file://app.sql"
  dev = docker.postgres.dev.url
}

In your application schema (app.sql), you can then utilize the pre-installed extensions:

CREATE TABLE users (
    id SERIAL PRIMARY KEY,
    username varchar(100) UNIQUE,
    email CITEXT UNIQUE -- The "citext" type is provided by the "citext" extension.
);

After setting up the app environment, all Atlas schema/migrate commands will first create a temporary database with the required extensions installed, and then load the schema onto it.

Answer​

Atlas supports the --include flag (or the env.include 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.

For example, to manage the products table in a MySQL database:

atlas schema apply \
  --url "mysql://root:pass@:3308/db" \
  --to "file://schema.sql" \
  --dev-url "docker://mysql/8/dev" \
  --include "products"

If the connection URL is not bound to a schema, specify the schema name in the pattern:

atlas schema apply \
  --url "mysql://root:pass@:3308/" \
  --to "file://schema.sql" \
  --dev-url "docker://mysql/8" \
  --include "db.products"

This command will only apply changes related to the products table, leaving other tables untouched.

atlas schema apply \
  --url "mysql://root:pass@:3308/" \
  --to "file://schema.sql" \
  --dev-url "docker://mysql/8" \
  --include "*.products"

Read more:

• Exclude Tables
• URL Connection Scope
• Declarative Schema Migration

Answer​

When defining an external_schema data source in atlas.hcl, 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 atlas schema inspect against it.

To verify that Atlas can read and load the ORM-generated schema correctly, run atlas schema inspect against the src of your environment.

Example Configuration​

Consider the following atlas.hcl configuration:

data "external_schema" "gorm" {
  program = [
    "go", "run",
    "ariga.io/atlas-provider-gorm", "load",
    "--path", "./path/to/models",
    "--dialect", "postgres",
  ]
}

env "gorm" {
  src = data.external_schema.gorm.url
  dev = "docker://postgres/15/dev?search_path=public"
}

Basic Inspection​

To verify that the ORM schema loads correctly, run:

atlas schema inspect --env gorm --url env://src

This command tells Atlas to read the schema from the external_schema data source and outputs it in HCL format, allowing you to verify that the ORM-generated schema was loaded as expected.

Interactive Visualization​

To visualize the schema interactively, add the -w flag:

atlas schema inspect --env gorm --url env://src -w

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.

SQL Format Output​

To get an SQL representation of the schema instead of HCL, use the --format flag:

atlas schema inspect --env gorm --url env://src --format '{{ sql . }}'

This is particularly useful when you want to see the actual SQL DDL statements that represent your ORM schema.

Common Use Cases​

This inspection technique is especially valuable when:

• Setting up a new external_schema data source for the first time
• Debugging issues with ORM schema generation
• Validating that schema changes from your ORM are reflected correctly
• Ensuring your ORM schema (like GORM, Django ORM, etc.) is generating the expected schema structure

Troubleshooting​

If the inspection fails, check:

1. Program accessibility: Ensure the ORM provider program specified in the external_schema is available and executable
2. Path correctness: Verify that paths in the program arguments are correct relative to the working directory
3. Dependencies: Make sure all required dependencies for your ORM provider are installed

Answer​

The atlas schema inspect command provides an --include 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.

This feature is useful when working with large schemas, allowing you to view or troubleshoot a smaller scope without being overwhelmed by unrelated objects.

Given the following schema:

-- Table
CREATE TABLE users (
  id serial PRIMARY KEY,
  name text NOT NULL
);

-- Function
CREATE FUNCTION get_user_count() RETURNS integer AS $$
BEGIN
  RETURN (SELECT COUNT(*) FROM users);
END;
$$ LANGUAGE plpgsql;

-- View
CREATE VIEW active_users AS
SELECT id, name FROM users WHERE name IS NOT NULL;

Below are a few examples of how to inspect specific resources in this schema:

Query a specific function by its name​

By default, the --include flag keeps only resources that match the given glob, allowing you to target specific objects by their names.

atlas schema inspect --env local --include get_user_count

The default output of schema inspect is formatted in HCL. To retrieve the SQL definition of the resource instead, use the --format flag:

atlas schema inspect --env local --include get_user_count --format '{{ sql . }}'

Query multiple resources by their names​

The command below includes the definitions of both the get_user_count function and the active_users view.

atlas schema inspect --env local \
  --include get_user_count \
  --include active_users

Another option to achieve this is to use a glob pattern:

atlas schema inspect --env local \
  --include "*_user*"

Query resources by their resource type​

Glob patterns also accept a type selector, which can be used to match only specific types of resources. For example:

atlas schema inspect --env local \
  --include "*[type=function]"

Qualified Resources​

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.

In this case, the resources you reference with the --include 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:

Use an explicit schema prefix:

--include "public.resource_name"

Or use a wildcard for the schema part, for example:

--include "*.resource_name"

How to use the baseline option with ariga/atlas-action/migrate/apply when adopting Atlas for an existing database?

Answer​

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.

If you're using GitHub Actions for CI/CD, you can apply migrations with the ariga/atlas-action/migrate/apply action. Since this action doesn't expose a direct --baseline flag, you'll need to configure the baseline setting in your atlas.hcl file instead.

Complete Workflow​

Step 1: Generate a Baseline Migration​

First, create a migration that represents your existing database schema:

atlas migrate diff baseline \
  --dir "file://migrations" \
  --dev-url "docker://postgres/15/dev" \
  --to "postgres://user:pass@host:5432/mydb"

This creates a migration file like 20240115120000_baseline.sql containing your current schema.

Step 2: Configure Baseline in atlas.hcl​

Add the baseline configuration to your atlas.hcl:

env "prod" {
  url = "postgres://user:pass@host:5432/mydb"
  migration {
    dir = "file://migrations"
    baseline = "20240115120000"  # Version without .sql extension
  }
}

Step 3: Use GitHub Action​

The action will respect the baseline configuration:

- name: Apply migrations
  uses: ariga/atlas-action/migrate/apply@v1
  with:
    config: "file://path/to/atlas.hcl"
    env: prod

For more details on working with existing databases, see the versioned migrations documentation.

Why does atlas migrate diff fail with the following error after running atlas migrate apply?

Error: sql/migrate: connected database is not clean: found table "atlas_schema_revisions" in schema <schema_name>. baseline version or allow-dirty is required

Answer​

This error occurs when the wrong database is used as a dev database (specified with --dev-url) when running migrate diff. The dev database is meant to be a temporary (and empty), locally-run database. It is used by Atlas to parse, validate, and analyze SQL definitions and is cleaned up after the process.

To simplify this process, Atlas can spin up an ephemeral local Docker container using the Docker driver, apply the statements from the migration directory to it (if there is one), determine the migrations needed to get to the desired schema, and clean up the dev database afterward.

For example, to use a docker-based PostgreSQL 15 database for migrate diff, you can run:

# For a single database schema, use the "public" schema as the search path.
--dev-url "docker://postgres/15/dev?search_path=public"

# For multiple database schemas:
--dev-url "docker://postgres/15/dev"

This is different from the database URL (specified with --url) used when running schema inspect or migrate apply, which is the URL to the database you intend to migrate — the same database used by the application:

# For a single database schema, use the "public" schema as the search path.
--url "postgres://user:pass@localhost:5432/db_name?sslmode_disable&search_path=public"

# For multiple database schemas:
--url "postgres://user:pass@localhost:5432/db_name?sslmode_disable"

If the database URL is used as the dev database because your actual database could have data in it (the database is "not clean") that can lead to inaccurate results during the diffing process, so Atlas stops it and prints the "not clean" error.

For more details on the two different database URLS, refer to the Atlas dev-database documentation and Atlas URL documentation.

In database migrations, a changeset is a unit of schema or data changes made up of SQL statements stored in a migration file, typically executed together in a single transaction.

In Atlas, a changeset is represented by a migration file that includes a version number, an optional description, and a collection of elements, such as: transaction configuration, DDL and DML statements, pre-migration checks, an integrity hash (to ensure content and order haven't changed after apply), optional annotations for masking sensitive values, and more.

Once a changeset is created by a developer or with CI automation, Atlas lets you validate (lint), test, deploy, monitor, and revert it. The rest of this document explains how Atlas handles changesets in detail.

Changeset generation with Atlas​

Unlike traditional migration tools that require writing SQL by hand, Atlas automates changeset generation by diffing your current schema against the desired state of the schema. The process is fully automated and policy-aware, so migrations are consistent, predictable, and follow your rules by default. Here's how it works:

1. Define the desired schema using SQL schema, Atlas HCL syntax, another database, an ORM, or any combination of these options.
2. Run atlas migrate diff.
3. Atlas computes the diff, applies your migration policies, and generates the changeset needed to reach the target schema state.
4. Atlas updates the atlas.sum file with a hash of the new changeset to guarantee integrity and enforce ordering.

Since this process is automated (locally or in CI), you get deterministic, minimal diffs that respect policies like create indexes concurrently for existing tables or never drop a table without a backup.

Read more at:

• Automatic Migration Planning
• Schema as Code: SQL syntax
• Schema as Code: HCL syntax
• ORM integrations: Supports, Python, Go, Java, JS/TS, C#, and more.

Validating and linting changesets​

Atlas provides two commands to validate changesets early in the workflow: atlas migrate validate and atlas migrate lint. These commands work both locally and in CI to help catch mistakes before they reach production.

Highlights of the validation and linting process include:

• Built-in checks include destructive change detection, rename safety, table-lock detection, concurrent index creation, naming conventions, and more.
• Custom policies can be written using the Atlas Schema Rule language, allowing you to enforce project-specific standards like: all tables must have timestamp columns, primary keys must be bigint, column and index names must follow naming conventions, and more.
• Atlas simulates the migration changeset against a temporary dev-database to make sure both generated and manual SQL statements are syntactically and semantically correct.
• Atlas supports CI integration such as GitHub Actions, GitLab CI, BitBucket, Azure DevOps, and more. Once a PR is created, the changeset is automatically validated and linted, and the results are reported back to the PR as comments or warnings.

Read more at:

• Changeset Linting
• Custom Policies
• CI integration: GitHub Actions, CircleCI, GitLab CI Components, BitBucket Pipelines.

Testing changesets​

Atlas includes a built-in testing framework that makes it easy to write both unit and integration tests for your schema and migration logic. Tests are written in HCL, with logic in plain SQL, and can run both locally and in CI.

There are two test types:

• Schema tests ensure your desired schema can be applied cleanly on a blank database, and let you validate constraints, triggers, functions, data logic, and queries.
• Migration tests simulate real-world upgrades by applying one or more changesets and validating the result. Common use: seed data before a changeset version, apply the changeset, then assert that logic like a data transformation worked as expected.

Tests support parallel execution, input variables, executing external tools (other programming languages), and automatic creation using Atlas Copilot.

Read more at:

• Testing Schemas
• Testing Migration Changesets

Deploying changesets​

Once changes are merged to the main branch, the CD (delivery) pipeline can package them so they're available at the deployment stage. Migration changesets can be pushed to Atlas Registry, built into a custom Docker image, or uploaded to a blob store like S3 for Atlas to consume during migrate apply.

Migration Directory push with atlas migrate push to Atlas Registry

Atlas provides a variety of ways to apply changesets as part of your deployment pipelines:

• CI/CD runners: Use Atlas official integration from GitHub Actions, GitLab CI, CircleCI, Bitbucket, Azure Pipelines, and more.
• Atlas Kubernetes Operator: Use the Atlas Operator to manage migrations in Kubernetes clusters. Works out of the box with ArgoCD and Flux.
• Terraform Provider: Use the atlas_migration resource to apply schema changes as part of terraform apply.

Read more at:

• Atlas Kubernetes Operator
• Atlas Terraform Provider

Undoing and rolling back changesets​

Atlas makes it easy to safely revert changesets. If a changeset was applied by mistake or if a deployment needs to be rolled back, use the atlas migrate down command.

Unlike traditional tools, that require pre-written down files, Atlas computes rollback plans automatically based on the current database state. The plan includes reverse SQL statements that bring the database back to a previous version or tag, and can be reviewed with --dry-run before applying.

Highlights of Atlas generated rollback plans:

• Revert the last changeset, a series of changesets, or jump back to a named version or tag.
• Supports reverting partially applied changesets in case the database is in a bad state due to implicit commits or incorrect transaction configuration.
• Automatically protects against unintended data loss by validating the plan for destructive changes.
• Validates and simulate the plan to detect issues before applying.
• Integrates with approval workflows to protect production environments.

Read more at:

• Down migration guide
• Atlas Blog: The Myth of Down Migrations

Monitoring and detecting schema drift​

Atlas helps you detect and respond to schema drift, when the actual state of a database diverges from the expected state defined by the latest changeset applied on the database. Drift can happen when someone bypasses the migration workflow and makes direct changes on the database. These ad-hoc changes introduce risk: queries may break, migrations may fail, and CI assumptions become invalid.

Atlas provides two options for detecting drift:

• Atlas Schema Monitoring – Choose a source (e.g., a deployed changeset or another environment) and let Atlas periodically compare it to the live database. If a drift is found, Atlas will notify you with a detailed report via Slack or a webhook.
• CI or scheduled checks – Use Atlas CI integrartions to auto-compare the live database against the latest changeset or a specific changeset version. This can be done as part of your CI/CD pipeline or scheduled checks.

Read more at:

• Atlas Schema Monitoring: Drift Detection
• Atlas Schema Monitoring: Webhooks

Managing multi-tenant environments​

Atlas includes built-in support for managing multi-tenant database environments, commonly used in database-per-tenant architectures.

Teams can define logical tenant groups and apply the same changeset across many databases or schemas in a single operation. This makes it easier to manage large fleets while ensuring that each tenant stays consistent with the intended schema state.

With Atlas multi-tenancy support, you can:

• Roll out the same changeset to multiple databases using a single command.
• Track which changesets were applied to which tenants.
• Control the target databases and their orders at runtime using Atlas HCL language.
• Gradually deploy or safely revert changesets per tenant if needed.

Read more in the Database-per-Tenant guide.

Read more​

For more information about changesets in Atlas, check out the following resources:

• Pre-migrations Checks
• Migration from Other Tools to Atlas
• Declarative Schema Migrations