Answer​

Exclude the managed admin role and its grants in the environment that targets Cloud SQL:

env "staging" {
  url = getenv("DATABASE_URL")
  dev = "docker://postgres/16/dev"
  exclude = [
    "postgres[type=role|user]",
    "postgres[type=role|user].permission",
  ]
}

The first pattern removes only the role object, since many projects exclude roles but still manage grants to them. The second removes the grants.

Why it happens​

On Cloud SQL for PostgreSQL, the bootstrap superuser is Google's cloudsqladmin. The postgres user is created afterwards as an ordinary role: not a superuser, a member of cloudsqlsuperuser for CREATEROLE and CREATEDB, with an OID above the system range. On a local container, postgres is the bootstrap superuser.

Atlas skips the superuser's implicit grants on a local dev database, but on Cloud SQL postgres is a regular role, so its grants show up in inspection and in every diff.

Managing grants to the admin user​

Grants to postgres cannot be planned through a local dev database, because PostgreSQL makes them implicit for a superuser. To manage them, use a dev database where postgres is an ordinary role, such as a second Cloud SQL instance.

Other managed services​

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 rds_superuser, the admin on Azure Database for PostgreSQL Flexible Server, a member of azure_pg_admin, and the admin on AlloyDB, a member of alloydbsuperuser. Use the same two patterns with that name.

Related​

• PostgreSQL Security as Code (Declarative)
• PostgreSQL Security as Code (Versioned)

An AWS RDS MySQL schema creates IAM-authenticated users, for example:

CREATE USER 'app_iam' IDENTIFIED WITH AWSAuthenticationPlugin AS 'RDS';

Running atlas migrate diff (or any command that uses the dev-database) against a standard mysql Docker image fails, because that plugin exists only on RDS:

Error: failed to run `atlas migrate diff`: Error: sql/migrate: read migration directory state:
sql/migrate: executing statement "CREATE USER 'app_iam' IDENTIFIED WITH AWSAuthenticationPlugin AS 'RDS';"
from version "20260602081826": Error 1524 (HY000): Plugin 'AWSAuthenticationPlugin' is not loaded

Must the dev-url point at a real RDS instance, or can the dev-database run locally in Docker?

Answer​

Atlas replays your schema or migration directory on the dev-database to compute its state. A vanilla mysql image has no AWSAuthenticationPlugin, so that statement fails with Error 1524. Pointing --dev-url at a real RDS instance works, but it is slow, requires network access and credentials, and gives up the hermetic, disposable dev-database.

Instead, build a local MySQL dev image that ships a no-op mock of the plugin: it implements just enough of the interface for the CREATE USER statement to succeed, but always rejects authentication, so nobody can actually log in through it. That makes it safe to run locally and in CI.

1. Save the Dockerfile​

Save this next to your atlas.hcl as aws-auth-mock.Dockerfile. It compiles a small mock plugin and installs it into the official MySQL image:

# syntax=docker/dockerfile:1
# Build a MySQL image with a no-op mock AWSAuthenticationPlugin.

ARG MYSQL_VERSION=8.4

FROM oraclelinux:9-slim AS builder
RUN microdnf install -y gcc && microdnf clean all
COPY <<'EOF' /src/aws_auth_plugin.c
/**
 * No-Op Mock for AWSAuthenticationPlugin.
 *
 * Mimics the AWS IAM authentication plugin interface but always rejects
 * authentication. Intended for local development with Docker so that MySQL
 * does not error about a missing plugin while still preventing IAM login.
 *
 * Minimal MySQL plugin ABI definitions are embedded inline to avoid a
 * build-time dependency on mysql-community-devel packages.
 */

#include <stddef.h>

#define CR_AUTH_USER_CREDENTIALS 1045
#define MYSQL_AUTHENTICATION_INTERFACE_VERSION 0x0201
#define MYSQL_AUTHENTICATION_PLUGIN 7
#define MYSQL_PLUGIN_INTERFACE_VERSION 0x010B
#define PLUGIN_LICENSE_GPL 1

typedef struct st_mysql_plugin_vio MYSQL_PLUGIN_VIO;
typedef struct st_mysql_server_auth_info {
  char *user_name;
  unsigned int user_name_length;
  const char *auth_string;
  unsigned long auth_string_length;
  char authenticated_as[512];
  char external_user[512];
  int password_used;
  const char *host_or_ip;
  unsigned int host_or_ip_length;
} MYSQL_SERVER_AUTH_INFO;

struct st_mysql_auth {
  int interface_version;
  const char *client_auth_plugin;
  int (*authenticate_user)(MYSQL_PLUGIN_VIO *vio, MYSQL_SERVER_AUTH_INFO *info);
  int (*generate_authentication_string)(char *outbuf, unsigned int *outbuflen,
                                        const char *inbuf, unsigned int inbuflen);
  int (*validate_authentication_string)(char *const inbuf,
                                        unsigned int buflen);
  int (*set_salt)(const char *password, unsigned int password_len,
                  unsigned char *salt, unsigned char *salt_len);
  const unsigned long authentication_flags;
  int (*compare_password_with_hash)(const char *hash,
                                    unsigned long hash_length,
                                    const char *cleartext,
                                    unsigned long cleartext_length,
                                    int *is_error);
};

struct st_mysql_plugin {
  int type;
  void *info;
  const char *name;
  const char *author;
  const char *descr;
  int license;
  int (*init)(void *);
  int (*check_uninstall)(void *);
  int (*deinit)(void *);
  unsigned int version;
  void *status_vars;
  void *system_vars;
  void *__reserved;
  unsigned long flags;
};

#define MYSQL_PLUGIN_EXPORT __attribute__((visibility("default")))

static int aws_auth_authenticate(MYSQL_PLUGIN_VIO *vio,
                                 MYSQL_SERVER_AUTH_INFO *info) {
  return CR_AUTH_USER_CREDENTIALS; /* always reject */
}

static int aws_auth_generate_auth_string(char *outbuf,
                                         unsigned int *outbuflen,
                                         const char *inbuf,
                                         unsigned int inbuflen) {
  if (inbuflen > *outbuflen) inbuflen = *outbuflen;
  for (unsigned int i = 0; i < inbuflen; i++) outbuf[i] = inbuf[i];
  *outbuflen = inbuflen;
  return 0;
}

static int aws_auth_validate_auth_string(char *const inbuf,
                                         unsigned int buflen) {
  return 0;
}

static int aws_auth_set_salt(const char *password, unsigned int password_len,
                             unsigned char *salt, unsigned char *salt_len) {
  if (salt_len) *salt_len = 0;
  return 0;
}

static int aws_auth_compare_password(const char *hash,
                                     unsigned long hash_length,
                                     const char *cleartext,
                                     unsigned long cleartext_length,
                                     int *is_error) {
  if (is_error) *is_error = 0;
  return 1; /* passwords never match (reject) */
}

static struct st_mysql_auth aws_auth_handler = {
  MYSQL_AUTHENTICATION_INTERFACE_VERSION,
  "mysql_clear_password",
  aws_auth_authenticate,
  aws_auth_generate_auth_string,
  aws_auth_validate_auth_string,
  aws_auth_set_salt,
  0,    /* authentication_flags */
  aws_auth_compare_password
};

MYSQL_PLUGIN_EXPORT struct st_mysql_plugin _mysql_plugin_declarations_[] = {
  {
    MYSQL_AUTHENTICATION_PLUGIN,
    &aws_auth_handler,
    "AWSAuthenticationPlugin",
    "Ariga (mock)",
    "No-op mock AWS IAM authentication plugin - always rejects",
    PLUGIN_LICENSE_GPL,
    NULL, NULL, NULL,
    0x0100,
    NULL, NULL, NULL, 0
  },
  {0, NULL, NULL, NULL, NULL, 0, NULL, NULL, NULL, 0, NULL, NULL, NULL, 0}
};

MYSQL_PLUGIN_EXPORT int _mysql_plugin_interface_version_ =
  MYSQL_PLUGIN_INTERFACE_VERSION;
MYSQL_PLUGIN_EXPORT int _mysql_sizeof_struct_st_plugin_ =
  sizeof(struct st_mysql_plugin);
EOF

RUN gcc -shared -fPIC -fvisibility=hidden \
  -o /src/aws_auth_plugin.so /src/aws_auth_plugin.c

FROM mysql:${MYSQL_VERSION}
COPY --from=builder /src/aws_auth_plugin.so /usr/lib64/mysql/plugin/aws_auth_plugin.so
RUN mkdir -p /etc/my.cnf.d /etc/mysql/conf.d && \
  printf '[mysqld]\nplugin-load-add=AWSAuthenticationPlugin=aws_auth_plugin.so\n' \
  | tee /etc/my.cnf.d/aws_auth_plugin.cnf > /etc/mysql/conf.d/aws_auth_plugin.cnf

2. Point the dev-database at the built image​

Use a docker block with a build configuration so Atlas builds the image on demand. A locals block keeps the MySQL version in one place instead of two:

locals {
  // Change this to match your RDS engine version, e.g. "8.0".
  mysql_version = "8.4"
}

docker "mysql" "dev" {
  image = "mysql-aws-auth-mock:${local.mysql_version}"
  build {
    context    = "."
    dockerfile = "aws-auth-mock.Dockerfile"
    args = {
      MYSQL_VERSION = local.mysql_version
    }
  }
}

data "runtimevar" "vault" {
  url = "hashivault://secret/data/database"
}

locals {
  vault = jsondecode(data.runtimevar.vault)
}

env "rds" {
  url = "mysql://${local.vault.username}:${local.vault.password}@aws-rds-instance.us-east-1.rds.amazonaws.com:3306/database"
  dev = docker.mysql.dev.url
  // ... the rest of your production config, e.g. migrations_dir, schema, etc.
}

Now any atlas command runs entirely against the local dev-database, with no real RDS instance required. Your production url still points at RDS and uses real IAM authentication as before; the mock plugin lives only in the dev-database.

Have additional questions or feedback? Reach out via the Intercom chat widget on this site.

Why does Atlas report a MODIFY COLUMN drift on a generated column in MySQL or MariaDB where the only difference is a character-set introducer, such as _latin1'-' on one side and _utf8mb4'-' on the other, even though I changed nothing?

Answer​

This is a known class of drift in MySQL and MariaDB. The cause is a charset or collation mismatch between your dev database and your target, not the object itself: when the two servers render the same expression under different connection charsets, they stamp a different character-set introducer (_charset'...') on its string literals. The definitions are logically identical; only their stored text differs, so the drift never converges.

It shows up most visibly on generated columns, but the same cause drifts expression DEFAULTs, functional indexes, CHECK constraints, and view definitions: anything whose canonical form is rendered by the server rather than taken from your source text.

Give the dev database the same charset settings as the target, using the command attribute of the docker block:

docker "mysql" "dev" {
  image   = "mysql:8.4" # match the target version
  command = [
    "--character-set-server=latin1",
    "--collation-server=latin1_swedish_ci",
    "--skip-character-set-client-handshake",
  ]
}

env "dev" {
  src = "file://schema.hcl"
  dev = docker.mysql.dev.url
}

--skip-character-set-client-handshake is the key flag: it forces every connection, including the one Atlas opens, onto character_set_server.

Read the values to reproduce from the target, on a fresh connection without SET NAMES:

SHOW VARIABLES LIKE 'character\_set\_server';
SHOW VARIABLES LIKE 'collation\_server';

Why this happens​

MySQL and MariaDB do not store the source text of these objects; they re-serialize the expression and attach a character-set introducer to every literal, chosen from the session's connection charset at CREATE/ALTER time (usually set by server configuration, not the client). Atlas normalizes both the desired and current states through the dev database and compares the results as text. A utf8mb4 dev writes the literal as _utf8mb4'...' while a latin1 target writes it as _latin1'...', so the two never match and Atlas keeps reporting drift.

With the atlas_schema resource, Terraform can pass connection metadata while Atlas resolves the credential when it evaluates atlas.hcl.

Credential options​

Pick one of three places for the credential:

Terraform setup​

In Terraform, pass only values you can store in state:

resource "atlas_schema" "app" {
  env_name = "local"
  config   = file("${path.module}/atlas.hcl")
  variables = jsonencode({
    database_name = var.db_name
    endpoint      = "${var.db_host}:${var.db_port}"
    username      = var.db_user
  })
  hcl = file("${path.module}/schema.pg.hcl")
}

Terraform stores the config text and variables payload for the resource. Keep passwords, full database URLs with passwords, and decoded secret payloads out of those fields.

IAM authentication​

If the database supports IAM authentication, Atlas can use the runner's cloud identity instead of a stored database password. Terraform can pass the endpoint, username, and region, while Atlas generates a short-lived token with the aws_rds_token or gcp_cloudsql_token data source.

See the secrets guide for AWS RDS and Cloud SQL examples.

Secret manager​

Teams that store database credentials in a secret manager can pass the reference through Terraform and have Atlas read the secret at runtime.

resource "atlas_schema" "app" {
  env_name = "prod"
  config   = file("${path.module}/atlas.hcl")
  variables = jsonencode({
    database_name = var.db_name
    endpoint      = "${var.db_host}:${var.db_port}"
    username      = var.db_user
    password_ref  = "awssecretsmanager://prod/app/db-password?region=us-east-1"
  })
  hcl = file("${path.module}/schema.pg.hcl")
}

variable "password_ref" {
  type = string
}

data "runtimevar" "password" {
  url = var.password_ref
}

env "prod" {
  url = "postgres://${var.username}:${urlescape(data.runtimevar.password)}@${var.endpoint}/${var.database_name}?sslmode=require"
}

Atlas supports secret stores such as AWS Secrets Manager, AWS Systems Manager Parameter Store, GCP Secret Manager, and HashiCorp Vault through the runtimevar data source. For setup details, see the secrets guide.

Environment variable​

A local shell, a CI secret store, and an HCP Terraform workspace environment variable all use the same pattern: the runner sets DB_PASSWORD, and Atlas reads it from the Terraform process environment.

variable "password" {
  type    = string
  default = getenv("DB_PASSWORD")
}

env "local" {
  url = "postgres://${var.username}:${urlescape(var.password)}@${var.endpoint}/${var.database_name}?sslmode=disable"
}

Atlas reads DB_PASSWORD when Terraform runs the atlas_schema resource. The password stays out of atlas_schema.variables, url, and other persisted resource arguments.

Run the plan and apply with the password in the Terraform process environment:

export DB_PASSWORD='example-password'
terraform init
terraform plan -out=tfplan
terraform apply tfplan

Local demo​

Start a disposable PostgreSQL instance to test the environment-variable option:

docker run --rm --name atlas-example-postgres \
  -e POSTGRES_PASSWORD='example-password' \
  -e POSTGRES_DB='appdb' \
  -p 55432:5432 \
  postgres:16-alpine

Then run Terraform with DB_PASSWORD set:

export DB_PASSWORD='example-password'
terraform init
terraform plan -out=tfplan
terraform apply tfplan

Remote state, HCP Terraform, and encrypted backends help protect Terraform state. Terraform still records the values passed through persisted resource arguments. To keep a value out of state, keep it out of the atlas_schema arguments and resolve it when Atlas runs.

Schemas that use postgres_fdw reference an upstream PostgreSQL server (SERVER, USER MAPPING, FOREIGN TABLE). That upstream server is often reachable only from inside the VPC of environments such as staging or production: local workstations and CI runners have no network path to it.

Working with such schemas in Atlas, whether for schema planning, schema testing, or simulating the real setup locally, triggers an FDW connection attempt on the dev-database that fails with errors such as:

08001 could not connect to server "upstream_db"

A common case is a materialized view that selects from a foreign table, which opens the FDW connection at CREATE time. What is the recommended pattern for stubbing the foreign server so that schema design, plan, lint, and diff run hermetically against the dev-database?

Answer​

Why the upstream must be reachable on the dev-database​

Atlas uses the dev-database to simulate the real environment, whether for validating the schema, planning a schema migration, or testing a data migration. Whatever the purpose, the relevant statements are executed against the dev-database. For postgres_fdw, that simulation reaches the upstream server:

• A materialized view that selects FROM foreign_table is populated at CREATE time unless WITH NO DATA is given.
• A foreign table is bound to a SERVER, and the server is bound to a real host:port.
• PostgreSQL opens the FDW connection from whichever database is running CREATE MATERIALIZED VIEW ... AS SELECT ....

Something must answer at the FDW hostname with the table shape the foreign tables expect. In production that role is filled by the real upstream. For local dev and CI, the upstream can be stubbed inside the dev-database itself, the same way any external service is mocked in a unit test.

Stub the upstream inside the dev-database​

In the example below, upstream_db stands in for the hostname of the real upstream server: the production-only PostgreSQL that the SERVER definition points at and that the foreign tables read from. The goal is to make the dev-database resolve that hostname to a stub PostgreSQL running locally.

docker "postgres" "dev" {
  image       = "postgres:18"
  extra_hosts = ["upstream_db:127.0.0.1"]
  init        = <<-SQL
    CREATE DATABASE upstream_db;
    CREATE EXTENSION IF NOT EXISTS dblink;
    SELECT dblink_exec(
      'dbname=upstream_db user=postgres password=...',
      'CREATE TABLE public.events (id bigint)'
    );
    DROP EXTENSION dblink;
  SQL
}

Two pieces:

• extra_hosts adds /etc/hosts entries inside the dev-database so the dev DB resolves the upstream hostname to itself (or to a sidecar). It maps to docker run --add-host.
• init provisions the stub: a database named like the real upstream, with the tables the foreign tables expect.

The dev DB now resolves the upstream hostname, finds a real PostgreSQL listening there, and CREATE MATERIALIZED VIEW ... AS SELECT FROM foreign_table succeeds end-to-end. Plan, lint, and diff are reproducible on any workstation or CI runner with no network access to production.

The stub is a test double, not a config switch. It lives only in the dev-database; production continues to use the real upstream.

Why WITH NO DATA is not enough​

Atlas supports a with_no_data diff policy that creates matviews without populating them at apply time:

diff {
  materialized {
    with_no_data = true
  }
}

This is the right escape hatch for matviews that are populated lazily and have no external dependencies. It is not the right answer for a matview that selects from a postgres_fdw foreign table.

The whole point of exercising the matview on the dev-database is to verify that it is well-formed against the upstream it depends on: that the foreign tables resolve, that column shapes line up, that joins and expressions compile. Skipping the populate hides exactly the failure mode worth catching before production. Stubbing the upstream keeps that validation end-to-end in local dev and CI.

Production still needs the real upstream​

The stub is a dev-database mock for local and CI use only. At apply time, the production database executes the same CREATE MATERIALIZED VIEW and opens its own FDW connection to the real upstream. That network path must already exist in production (e.g., VPC peering, security group rules, internal DNS). The dev-side mock does not affect, simulate, or substitute for that connectivity. It only removes the planning stage's dependency on it.

Summary​

postgres_fdw runs the foreign connection from the database executing the statement. For local dev and CI, that database is the Atlas dev-database, so the upstream must be reachable there. Stubbing it inside the dev-database with extra_hosts and an init script makes schema design, plan, lint, and diff hermetic and reproducible, while production keeps talking to the real upstream as before.

Have additional questions or feedback? Reach out via the Intercom chat widget on this site.

Answer​

No, you don't need to plan/approve for every database server if they all share the same schema state.

Atlas matches migration plans by schema state transition, not by database URL. When you run atlas schema apply, Atlas:

1. Computes a fingerprint of the current database state (S1) and the desired state (S2)
2. Checks the Atlas Registry for an approved plan matching this transition (S1 → S2)
3. If a pre-approved plan is found, applies it without requiring additional approval

If all your databases are in the same state, a single approved plan works for all of them.

What if databases have diverged?​

If a database is in a different state (due to manual changes or partial failures) and no pre-approved plan exists, Atlas computes the migration to transition the database from S1 to S2, runs analysis (linting) on the plan, and handles it based on your Review Policy configuration:

• ERROR - Auto-approve if no lint errors; otherwise, wait for approval
• WARNING - Auto-approve if no warnings/errors; otherwise, wait for approval
• ALWAYS - Always wait for approval

When auto-approval doesn't pass and no pre-approved plan exists, Atlas can use ad-hoc approvals: it automatically creates a plan, provides you a link to review it in Atlas Registry, and waits for your approval before continuing. This ensures no unexpected changes are applied without explicit review.

Learn how to set up ad-hoc approvals for your CI/CD pipeline:

The screenshot below shows an ad-hoc plan in the Atlas Registry:

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.

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.

Answer​

Atlas provides programmatic capabilities that allow you to customize inspection output using Go templates. This lets you generate custom reports about your database schema, including counting schemas, tables, views, functions, and other database objects.

By configuring a custom format template in your atlas.hcl file, you can use atlas schema inspect to generate detailed statistics about your database structure, such as the total number of objects per schema and the overall database size.

Example Configuration​

Add a format block to your environment configuration in atlas.hcl:

env "schema-size" {
  url = "<DATABASE-URL>"
  format {
    schema {
      //language=gotemplate
      inspect = <<-EOT
        {{- /* Count number of database objects, such as extensions and schemas. */}}
        {{- $size := add (len .Realm.Objects) (len .Realm.Schemas) }}
        {{- range .Realm.Schemas }}
          {{- $schemaSize := add (len .Tables) (len .Views) (len .Funcs) (len .Procs) (len .Objects) }}
          {{- /* Add the number of triggers in each table to the schema size. */}}
          {{- range .Tables }}
            {{- $schemaSize = add $schemaSize (len .Triggers) }}
          {{- end }}
          {{- /* Print the size of the current schema. */}}
          {{- printf "Schema %q size: %d objects.\n" .Name $schemaSize -}}
          {{- $size = add $size $schemaSize }}
        {{- end }}
        {{- /* Print the total size of the database. */}}
        {{- printf "Total database size: %d objects.\n" $size -}}
      EOT
    }
  }
}

Usage​

Run the inspection command with your configured environment:

atlas schema inspect --env schema-size

Example Output​

The command will output statistics for each schema and the total database size:

Schema "manufacturing" size: 45 objects.
Schema "public" size: 120 objects.
Total database size: 167 objects.

What's Being Counted​

The template counts various database objects to calculate schema and database size:

• Schema-level objects: Tables, views, functions, procedures, and other schema objects
• Table-level objects: Triggers associated with each table
• Database-level objects: Extensions and other database-level objects

Learn More​

For more information on customizing inspection output, see:

• Customizing Inspection Output with Go Templates
• Atlas Schema Inspection

How can I resolve the pq: out of shared memory error that appears while Atlas loads my schema?

Answer​

This message typically comes from the PostgreSQL dev-database that Atlas spins up to simulate your schema changes, not from the target database itself.

Why does this error occur?​

Postgres acquires locks before dropping objects to prevent concurrent modifications. These locks are held within a single transaction until the DROP completes or rolls back. When a large schema is dropped with a CASCADE clause, Postgres must lock every dependent object in that one transaction. If the number of required locks exceeds the available space in the lock table, Postgres raises the following error:

ERROR: out of shared memory
HINT: You might need to increase max_locks_per_transaction.

The lock table and max_locks_per_transaction​

The lock table is created in shared memory when the server starts. This parameter controls the average number of object locks allocated for each transaction. The default is 64.

If the lock table runs out of space, PostgreSQL reports the above error and suggests increasing the parameter value.

Increasing max_locks_per_transaction​

Raising this parameter allows PostgreSQL to allocate more object locks per transaction. Because the lock table is initialized at startup, changing this value requires a server restart.

If you're using an Atlas docker-based dev-database, you can set a higher value in the command argument as shown below:

docker "postgres" "dev" {
  image = "postgres:16"
  // ... other configuration as needed
  command = [
    "-c", "max_locks_per_transaction=512",
  ]
}

env "local" {
  dev = docker.postgres.dev.url
  // ... other configuration as needed
}

This example starts the Postgres server with max_locks_per_transaction=512.

Adjust the value based on your need (for example, 128, 256, 512, or 1024).

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.

My revisions table lists the following versions:

mysql> SELECT * FROM  "atlas_schema_revisions";
+-------------------------+---------+-----+
| version                 | applied | ... |
+-------------------------+---------+-----+
| .atlas_cloud_identifier | 0       |     |
| 20251007053111          | 1       |     |
| 20251007051222          | 1       |     |
| 20250618084333          | 1       |     |
+-------------------------+---------+-----+

However, when I inspect the target database, the schema changes from 20250618084333 were never applied. How can I delete the latest row(s) so the revision history reflects the actual state?

Answer​

Use the atlas migrate set command to reset the recorded version to the last state that truly matches the database. For example:

atlas migrate set 20251007051222 \
  --url "postgres://user:pass@localhost:5432/app"

This removes every row whose version is greater than 20251007051222 from the revision table. After the command finishes, the latest recorded version is 20251007051222:

mysql> SELECT * FROM  "atlas_schema_revisions";
+-------------------------+---------+-----+
| version                 | applied | ... |
+-------------------------+---------+-----+
| .atlas_cloud_identifier | 0       |     |
| 20251007053111          | 1       |     |
| 20251007051222          | 1       |     |
+-------------------------+---------+-----+

When to use atlas migrate set vs atlas migrate down​

Use atlas migrate set when:

• You are certain that the database schema already matches the version you are setting.
• You encounter an unexpected state during development and want to realign the revision table with the actual schema.

If the statements from the latest version(s) were in fact executed and must be reverted, run atlas migrate down instead. This command computes a safe downgrade plan that undoes the schema changes and updates the revision history. Using atlas migrate set alone in this case would hide applied changes and leave the database inconsistent.

After resetting the revision table, rerun atlas migrate apply when you are ready so the skipped migration can be applied once the underlying issue is resolved.

How can I keep a single canonical schema or model and apply it to multiple database drivers (for example, an application Postgres database and a data-lake store) so the two remain in sync?

Answer​

Maintaining one canonical model for multiple drivers is a robust way to ensure schema parity between your application and downstream stores, such as a data lake.

Some of the benefits of having a single source of truth include:

• Avoiding drift between application and analytical stores
• Simplifying migrations, auditing, and testing
• Enabling deterministic schema generation for environments, test fixtures, and data pipelines

The recommended (and practical) approach for this with Atlas is to:

1. Define your model using your application's ORM (e.g., SQLAlchemy, GORM, etc.) to create a single source of truth
2. Download the corresponding Atlas ORM provider so Atlas can read your model
3. Configure your atlas.hcl file to use the ORM model (a data.external_schema data source) for src and to point migration.dir and url to each target driver.
4. Run atlas migrate diff for each target to produce migration files tailored to each driver (see "Generating Migrations").

Example: Using SQLAlchemy​

If your application defines the model with SQLAlchemy, use the Atlas SQLAlchemy provider to load the models and generate migrations for each target.

Below is an example atlas.hcl file for a multi-dialect setup using an external SQLAlchemy provider program and per-dialect migration directories.

variable "dialect" {
  type = string
}

locals {
  dev_url = {
    mysql = "docker://mysql/8/dev"
    postgresql = "docker://postgres/15"
    sqlite = "sqlite://?mode=memory&_fk=1"
    mssql = "docker://sqlserver/2022-latest"
    clickhouse = "docker://clickhouse/23.11/dev"
  }[var.dialect]
}

data "external_schema" "sqlalchemy" {
  program = [
    "atlas-provider-sqlalchemy",
    "--path", "app",
    "--dialect", var.dialect,
  ]
}

env "sqlalchemy" {
  src = data.external_schema.sqlalchemy.url
  dev = local.dev_url
  migration {
    dir = "file://migrations/${var.dialect}"
  }
}

Run atlas migrate diff --env sqlalchemy --var dialect=postgresql (or set the --var dialect=... for other engines) to generate a migration tailored to the selected dialect and stored under migrations/<dialect>/. See Generating Migrations for more.

Review and commit the generated migration files (including atlas.sum), then apply them to the appropriate targets (for example with atlas migrate apply --env sqlalchemy --var "dialect=postgresql" --url "$APP_DATABASE_URL").

Example project: https://github.com/ariga/atlas-showcase/tree/master/projects/sqlalchemy

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 Atlas Pro​

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​

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

What encoding is used by Atlas for schema files? How do you avoid encoding issues with PowerShell on Windows?

Answer​

Atlas uses UTF-8 to encode schema files and migration files generated by Atlas. UTF-8 is the default encoding on nearly all system terminals, but on Windows, PowerShell uses UTF-16 by default. This can cause an encoding issue when Atlas loads the schema files generated by the inspect command.

For example, running the following command in PowerShell will create the schema.sql file with UTF-16 encoding:

atlas schema inspect -u <URL> > schema.sql

When loading this file for another command, like atlas migrate apply, this will lead to an error because Atlas expects UTF-8 encoding:

Error: schema.sql:1: Error 1064 (42000): You have an error in your SQL syntax; check the manual that corresponds to your MySQL server version for the right syntax to use near '' at line 1

The same problem happens with the external_schema datasource:

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

You will get the following error because the output from program is in UTF-16 encoding:

Error: data.external_schema.gorm: running program C:\\Program Files\\Go\\bin\\go.exe: 13:49: illegal character U+0073 's' in escape sequence (and 6 more errors)
exit status 1

To prevent these errors, we recommend changing the default encoding of PowerShell on Windows to UTF-8 by creating a default profile.

Create or edit your PowerShell profile to set the default encoding to UTF-8. For most users, this is done at the $PROFILE location (typically $HOME\Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1). This does not require administrator privileges and only affects your user account.

If you want to set the encoding for all users (requires administrator privileges), you can create or edit the profile at the $PSHOME location (typically found at C:\Windows\System32\WindowsPowerShell\v1.0). See Microsoft's documentation for more details.

Add the following content to your profile file:

$PSDefaultParameterValues['Out-File:Encoding'] = 'utf8'
$PSDefaultParameterValues['*:Encoding'] = 'utf8'

After creating the profile, restart all Terminal apps by closing and reopening them. Then, run $PSDefaultParameterValues['Out-File:Encoding'] to confirm that the default encoding has been updated:

$ $PSDefaultParameterValues['Out-File:Encoding']
utf8
$ $PSDefaultParameterValues['*:Encoding']
utf8

The Problem​

Consider this scenario:

Initial state:

• Master branch:
  • 001_initial.sql
• Dev branch (PR pending):
  • 001_initial.sql
  • 002_add_posts.sql
  • 004_add_index.sql

After hotfix applied directly to production:

• Master branch:
  • 001_initial.sql
  • 003_hotfix_add_email.sql ← hotfix added
• Dev branch (unchanged):
  • 001_initial.sql
  • 002_add_posts.sql
  • 004_add_index.sql

After merging master into dev - the problem:

• 001_initial.sql - Applied to production
• 002_add_posts.sql - Dev-only, not applied to production
• 003_hotfix_add_email.sql - Applied to production
• 004_add_index.sql - Dev-only, not applied to production

This creates a non-linear migration history where migration files 002 and 004 were created before and after the hotfix timestamp but haven't been applied to production.

The Solution​

Step 1: Get latest changes​

Incorporate the latest changes from master into your dev branch:

git checkout dev
git merge master  # or git rebase master

This will create a conflict in the atlas.sum file, which is expected. Resolve the git conflicts as usual, choosing any version number for atlas.sum.

The version number doesn't matter because you will then re-hash the migration directory by running:

atlas migrate hash

Step 2: Fix your development database​

Since the hotfix was applied to production but not to your dev database, you must bring your dev database to a consistent state before rebasing migrations.

# Apply only the missing hotfix migration
atlas migrate apply --url "mysql://root:pass@localhost:3306/development" \
  --exec-order non-linear

The --exec-order non-linear flag in Atlas lets you run migration files even if they weren’t created in order. This is handy when multiple developers add migrations at the same time and version numbers don’t line up. Learn more about execution order options.

Step 3: Rebase migrations​

With your dev database in a consistent state, run atlas migrate rebase <versions> to shift pending migrations to come after the hotfix. Rebase only the files that haven't been applied to production:

# Rebase the dev-only migrations
atlas migrate rebase 002 004

This command will:

• Rename the out-of-order migration files with new timestamps that come after the hotfix
• Update the atlas.sum file with the new checksums

Step 4: Verify the rebase​

After rebasing, your migration directory should look like:

migrations/
├── 001_initial.sql              
├── 003_hotfix_add_email.sql     # hotfix from master  
├── 005_add_posts.sql            # rebased (was 002_add_posts.sql)
├── 006_add_index.sql            # rebased (was 004_add_index.sql)
└── atlas.sum                    

Since your development database already has the schema changes from the rebased migrations applied, mark them as applied to avoid re-execution:

atlas migrate set 006 --url "mysql://root:pass@localhost:3306/development"

Step 5: Deploy the changes​

Update the PR and deploy the changes:

• With CI/CD setup: Wait for Atlas CI to pass, then merge the changes. The rebased migrations will be applied automatically during deployment.
• Without CI/CD setup: Manually apply the rebased migrations to your production database after merging:

atlas migrate apply --url "mysql://root:pass@aws-rds:3306/production"

# Clean the dev database and reapply all rebased migrations
atlas schema clean --url "mysql://root:pass@localhost:3306/local"
atlas migrate apply --url "mysql://root:pass@localhost:3306/local"

Further Reading​

• Modern Database CI/CD with Atlas
• Non-linear migration execution
• Migration Directory Integrity

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

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