Atlas Best Practices

Atlas Best Practices

Atlas supports declarative and versioned schema workflows. Keep this file minimal and load only the reference file needed for the current task.

Workflow Selection

• Use declarative workflow when desired schema state is the source of truth.
• Use versioned workflow when migration files are required for auditing and staged deployments.
• Use baseline workflow when onboarding an existing database.

Default Execution Flow

1. Confirm the target env in atlas.hcl. 2. Confirm dev is configured and isolated from production. 3. Plan first, then lint/test/validate, then apply. 4. Run production changes through CI/CD or approved deployment workflow.

Quick Commands

# Declarative
atlas schema apply --env local

# Versioned
atlas migrate diff add_change --env local
atlas migrate lint --env local --latest 1
atlas migrate apply --env local

# Integrity
atlas migrate validate --env local
atlas migrate status --env local

Reference Map

• core-workflows.md

Use for environment config, schema-as-code patterns, declarative vs versioned workflows, baselining, and ORM provider loading.

• safety-and-quality.md

Use for lint analyzers, transaction modes, schema tests, pre-execution checks, and CI patterns.

• atlas-v1-1-features.md

Use for Atlas v1.1 coverage (released on 2026-02-03), including security as code, declarative data, new drivers/platform support, Slack integration, schema exporters, and MySQL TLS.

• cli-agent-gaps.md

Use for Atlas CLI capabilities and edge cases agents often miss: planning workflows, migration directory maintenance commands, URL/TLS pitfalls, feature availability, and version policy constraints.

Guardrails

• Keep credentials out of source files; prefer Atlas data sources and input variables.
• Require explicit review for destructive or data-dependent migrations.
• Fail loudly on unsupported drivers, missing dev URLs, or unknown environment names.

Atlas v1.1 Feature Coverage

Atlas v1.1.0 was announced on February 3, 2026. This file tracks the new capabilities from that release and how to apply them.

Primary source:

• https://atlasgo.io/blog/2026/02/03/atlas-v1-1

Table of Contents

• Database Security as Code
• Declarative Data Management
• Aurora DSQL support
• ClickHouse improvements
• Azure Fabric support
• PostgreSQL enhancements
• Spanner enhancements
• CockroachDB support
• Slack integration
• Schema exporters
• MySQL TLS support

Database Security as Code

Define roles, users, and permissions in schema state, then manage through normal Atlas workflows.

role "app_readonly" {}

user "app_user" {
  password = var.app_password
}

permission {
  for        = schema.public
  to         = role.app_readonly
  privileges = [SELECT]
}

Enable security mode in environment config:

env "prod" {
  schema {
    src = "file://schema.hcl"
    mode {
      roles       = true
      permissions = true
    }
  }
}

Notes:

• Feature is Atlas Pro.
• Password values are masked in logs/inspect output.
• Prefer data sources + input variables so secrets are not hardcoded.

Declarative Data Management

Manage lookup/seed rows as desired state:

data {
  table = table.countries
  rows = [
    { id = 1, code = "US", name = "United States" },
    { id = 2, code = "DE", name = "Germany" },
  ]
}

Configure data sync policy:

env "prod" {
  data {
    mode    = UPSERT
    include = ["countries"]
  }
}

Modes:

• INSERT: add only.
• UPSERT: add/update by key.
• SYNC: add/update/delete to exact desired state.

Aurora DSQL Support

Use dsql:// URLs:

env "dsql" {
  url = "dsql://admin:${local.dsql_pass}@cluster.dsql.us-east-1.on.aws/?sslmode=require"
  dev = "docker://dsql/16"
}

Atlas adapts generated DDL for DSQL behavior (for example async index creation and non-transactional DDL constraints).

ClickHouse Improvements

Cluster mode

Use ?mode=cluster on URL so Atlas emits cluster-aware DDL.

Data retention on table recreation

Atlas handles table recreation flows that require ORDER BY/PARTITION BY changes by copying/swapping data to avoid loss.

Azure Fabric Support

Atlas supports Microsoft Fabric Data Warehouse (SQL Server/T-SQL based), enabling declarative and CI/CD workflows for Fabric environments.

PostgreSQL Enhancements

CAST support

cast {
  source = int4
  target = composite.my_type
  with   = function.int4_to_my_type
  as     = ASSIGNMENT
}

Replica identity support

table "accounts" {
  schema = schema.public
  replica_identity = FULL
}

You can use primary key (default), unique index, or FULL.

Spanner Enhancements

PostgreSQL dialect support

env "spanner" {
  url = "spanner://projects/my-project/instances/my-instance/databases/my-db"
  dev = "docker://spannerpg/latest"
}

Vector indexes

index "DocEmbeddingIdx" {
  columns       = [column.DocEmbedding]
  type          = VECTOR
  distance_type = COSINE
}

CockroachDB Support

Dedicated crdb:// driver:

env "cockroach" {
  url = "crdb://user:pass@cluster.cockroachlabs.cloud:26257/defaultdb?sslmode=verify-full"
  dev = "docker://crdb/v25.1.1/dev"
}

Notes:

• Supports declarative and versioned workflows.
• sslmode=verify-full for CockroachDB Cloud.
• Feature is Atlas Pro.

Slack Integration

Atlas Cloud includes native Slack integration for CI completion, migration deployment, drift detection, and review notifications. Configure in Atlas Cloud settings per project/channel.

Schema Exporters

Use declarative exporters and run inspect/diff with --export:

exporter "sql" "schema" {
  path     = "schema/sql"
  split_by = object
  naming   = same
}

env "prod" {
  export {
    schema {
      inspect = exporter.sql.schema
    }
  }
}

Run:

atlas schema inspect --env prod --export

MySQL TLS Support

Use TLS options in MySQL URL:

mysql://user:pass@host:3306/db?tls=true&ssl-ca=/path/to/ca.pem

For client cert auth, include ssl-cert and ssl-key parameters.

Atlas CLI Gaps Agents Often Miss

This reference captures Atlas CLI capabilities and constraints that AI agents commonly omit when proposing workflows.

Table of Contents

• Planning and approval workflows
• Migration directory maintenance
• Schema quality commands beyond apply/diff
• atlas.hcl controls that change behavior
• URL and connection pitfalls
• Dev-database nuances
• Feature availability and version policy
• Suggested default workflow for agents
• Sources

Planning and Approval Workflows

Agents often jump directly to atlas schema apply. Prefer explicit planning when review gates are required:

atlas schema plan --env dev
atlas schema plan --env dev --pending
atlas schema plan lint --env dev --file file://plan.hcl
atlas schema plan validate --env dev --file file://plan.hcl
atlas schema plan approve --url atlas://<schema-slug>/plans/<name>

Key idea:

• schema plan is for pre-planning/review/approval before execution.
• Use --push, --pending, and approve to separate authoring from deployment.

Migration Directory Maintenance

Agents frequently miss non-obvious maintenance commands:

# Create checkpoint snapshot for faster bootstrap of new envs.
atlas migrate checkpoint --env dev

# Recompute atlas.sum after manual file edits.
atlas migrate hash --env dev

# Validate checksums and (optionally) SQL semantics with dev DB execution.
atlas migrate validate --env dev --dev-url "docker://postgres/15/dev?search_path=public"

# Reorder/rebase migration history when needed.
atlas migrate rebase 20240101010101 --env dev

Other high-signal commands:

• atlas migrate test for migration tests.
• atlas migrate set only for explicit revision-table reconciliation.
• atlas migrate import for importing non-Atlas migration formats.

Schema Quality Commands Beyond Apply/Diff

Useful commands agents commonly skip:

atlas schema validate --env dev
atlas schema lint --env dev
atlas schema fmt schema/
atlas schema stats inspect --env prod
atlas tool lsp --stdio

Notes:

• schema stats inspect emits OpenMetrics.
• tool lsp provides language-server support for editor integration.

atlas.hcl Controls That Change Behavior

Schema mode

Roles/permissions are excluded by default and must be explicitly enabled:

schema {
  src = "file://schema.hcl"
  mode {
    roles       = true
    permissions = true
    sensitive   = ALLOW // DENY is default
  }
}

Data config

max_rows is required when syncing data against a live database URL:

data {
  mode     = UPSERT
  include  = ["countries", "currencies"]
  exclude  = ["temp_*"]
  max_rows = 1000
}

Diff policy

Prevent accidental destructive plans at diff time:

diff {
  skip {
    drop_schema = true
    drop_table  = true
  }
  concurrent_index {
    create = true
    drop   = true
  }
}

Lint policy

Non-linear change handling is important for team workflows:

lint {
  non_linear {
    error   = true
    on_edit = WARN // IGNORE | ERROR
  }
  destructive {
    error = true
    force = true // Pro
  }
}

URL and Connection Pitfalls

TLS defaults and params

• PostgreSQL defaults to SSL mode required; set ?sslmode=disable only for local/non-TLS setups.
• MySQL TLS requires explicit URL parameters like ?tls=true&ssl-ca=... (and optionally ssl-cert, ssl-key).
• Aurora DSQL requires sslmode=require.

URL escaping

Special characters in credentials must be URL-escaped. In atlas.hcl, prefer:

locals {
  db_pass = urlescape(getenv("DB_PASSWORD"))
}

Scope/mode semantics

• PostgreSQL/CockroachDB scope commonly uses search_path.
• SQL Server and Oracle use Atlas mode (schema vs database) to control scope.
• Unix-socket forms exist for MySQL/MariaDB (mysql+unix://..., maria+unix://...).

Dev-Database Nuances

• Use --dev-url for validation and canonicalization to avoid false-positive diffs.
• Atlas uses dev-db execution to catch SQL semantic errors that static parsing may miss.
• For Pro users, baseline dev schemas can be configured with docker/dev blocks and baseline SQL.
• docker+<driver>://... supports custom local/registry images.
• Some emulated dev images do not enforce every managed-service limitation (example: DSQL); keep schema features within target engine support.

Feature Availability and Version Policy

Agents should always account for product/version boundaries:

• Atlas is open-core; many advanced CLI/database capabilities are Pro.
• Drivers like SQL Server, ClickHouse, Redshift, Oracle, Spanner, Snowflake, Databricks, CockroachDB, Aurora DSQL, and Azure Fabric are Pro.
• Supported CLI policy is the latest two minor versions.
• Binaries older than 6 months are removed from CDN/Docker Hub.
• Atlas Community (Apache 2.0) exists separately from Atlas (EULA binary).

Suggested Default Workflow for Agents

1. Validate CLI/version and feature availability (atlas version, Pro vs open checks). 2. Load atlas.hcl env and confirm dev URL is configured. 3. Run schema validate/lint before generating plans. 4. Prefer schema plan for reviewed environments; use apply only after approval. 5. For versioned flow, run migrate diff -> lint -> validate -> status -> apply. 6. After manual migration edits, run migrate hash and then migrate validate. 7. Treat connection URLs and TLS settings as first-class config, not ad hoc flags.

Sources

• https://atlasgo.io/cli-reference
• https://atlasgo.io/atlas-schema/projects
• https://atlasgo.io/concepts/url
• https://atlasgo.io/concepts/dev-database
• https://atlasgo.io/lint/analyzers
• https://atlasgo.io/features#pro

Atlas Core Workflows

Table of Contents

• Workflow choice
• Project configuration (atlas.hcl)
• Dev database patterns
• Declarative workflow
• Versioned workflow
• Baselining existing databases
• Schema sources (HCL, SQL, ORM providers)
• Common commands

Workflow Choice

• Choose declarative for state-driven workflows where Atlas computes and applies drift to target state.
• Choose versioned when migration files must be reviewed, versioned, and promoted across environments.
• Choose baseline flow first for brownfield databases already in production.

Project Configuration (atlas.hcl)

Use explicit environments and variables:

variable "db_url" {
  type = string
}

env "local" {
  src = "file://schema.pg.hcl"
  url = var.db_url
  dev = "docker://postgres/15/dev?search_path=public"

  migration {
    dir = "file://migrations"
  }
}

env "prod" {
  src = "file://schema.pg.hcl"
  url = var.db_url
  migration {
    dir = "atlas://myapp"
  }
}

Use:

atlas schema apply --env local --var "db_url=postgres://..."

Dev Database Patterns

Atlas needs dev for diffing, linting, and validation.

# PostgreSQL
docker://postgres/15/dev?search_path=public

# MySQL
docker://mysql/8/dev

# SQLite
sqlite://dev?mode=memory

Keep dev ephemeral and isolated.

Declarative Workflow

Use desired-state schema files (.hcl or .sql) and let Atlas compute changes:

atlas schema apply --url "postgres://..." --to "file://schema.pg.hcl" --dev-url "docker://postgres/15"

Recommended for:

• Teams that prefer Terraform-style drift correction.
• Faster iteration in lower environments.

Versioned Workflow

Generate migration files and promote through environments:

atlas migrate diff add_users --dir "file://migrations" --to "file://schema.sql" --dev-url "docker://postgres/15"
atlas migrate apply --dir "file://migrations" --url "postgres://..."

Recommended for:

• Regulated workflows requiring immutable migration history.
• Environments where deployment and schema change approvals are separated.

Baselining Existing Databases

When adopting Atlas for an existing database:

# Generate a baseline migration from current desired schema.
atlas migrate diff baseline --env local --to "file://schema.hcl"

# Mark baseline as applied in target env without executing it.
atlas migrate apply --env prod --baseline "20240101000000"

Schema Sources (HCL, SQL, ORM Providers)

HCL

Use database-specific extension hints where practical:

• .pg.hcl for PostgreSQL
• .my.hcl for MySQL
• .lt.hcl for SQLite

SQL

Use standard DDL files for teams that prefer SQL-authoring:

CREATE TABLE users (
  id bigint PRIMARY KEY,
  email varchar(255) NOT NULL UNIQUE
);

ORM Providers

Load schema from external providers:

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

env "local" {
  src = data.external_schema.gorm.url
}

Common Commands

# Versioned flow
atlas migrate diff migration_name --env local
atlas migrate lint --env local --latest 1
atlas migrate apply --env local
atlas migrate validate --env local
atlas migrate status --env local

# Declarative flow
atlas schema apply --env local --auto-approve
atlas schema inspect --url "postgres://..." --format "{{ sql . }}"
atlas schema diff --from "postgres://..." --to "file://schema.hcl"

Atlas Safety and Quality

Table of Contents

• Migration linting
• Lint suppressions
• Schema testing
• Transaction modes
• Pre-execution checks
• CI integration
• Review checklist

Migration Linting

Configure analyzers in atlas.hcl:

lint {
  destructive {
    error = true
  }
  data_depend {
    error = true
  }
  naming {
    match   = "^[a-z_]+$"
    message = "must be lowercase with underscores"
    index {
      match   = "^idx_"
      message = "indexes must start with idx_"
    }
  }
  concurrent_index {
    error = true
  }
}

Analyzer intent:

• DS: destructive changes (drop schema/table/column).
• MF: data-dependent changes (constraints, not-null transitions).
• BC: backward-incompatible changes (renames and incompatible contracts).
• PG (Pro): PostgreSQL operational safety such as concurrent index rules.

Run:

atlas migrate lint --env local --latest 1

Lint Suppressions

Use targeted suppressions only when justified:

-- atlas:nolint destructive
DROP TABLE old_users;

Always include a code review note for why suppression is safe.

Schema Testing

Use .test.hcl files for behavior checks:

test "schema" "user_constraints" {
  exec {
    sql = "INSERT INTO users (id, email) VALUES (1, 'test@example.com')"
  }

  catch {
    sql   = "INSERT INTO users (id, email) VALUES (2, 'test@example.com')"
    error = "duplicate key"
  }

  assert {
    sql = "SELECT COUNT(*) = 1 FROM users"
    error_message = "expected exactly one user"
  }
}

Run:

atlas schema test --env local schema.test.hcl

Transaction Modes

Per-file directive:

-- atlas:txmode none
CREATE INDEX CONCURRENTLY idx_users_email ON users (email);

Modes:

• file (default): one transaction per migration file.
• all: one transaction across all files in apply.
• none: no transaction wrapping (required for some DDL on specific engines).

Pre-Execution Checks

For Atlas Pro, block unsafe plans before apply:

env "prod" {
  check "migrate_apply" {
    deny "too_many_files" {
      condition = length(self.planned_migration.files) > 3
      message   = "Cannot apply more than 3 migrations at once"
    }
  }
}

CI Integration

Example GitHub Actions step:

- uses: ariga/setup-atlas@v0
  with:
    cloud-token: ${{ secrets.ATLAS_CLOUD_TOKEN }}

- name: Lint migrations
  run: atlas migrate lint --env ci --git-base origin/main

Review Checklist

• Is the correct environment selected?
• Is dev configured and isolated?
• Did lint pass without broad suppressions?
• Did schema tests cover constraints and failure paths?
• Are destructive operations intentionally approved?
• Is migration directory integrity validated?

atlas migrate validate --env local
atlas migrate status --env local