Atlas — Declarative Database Schema Management

Introduction

Atlas takes a declarative approach to database migrations: you define the desired schema state and Atlas computes the SQL statements needed to reach it. This eliminates hand-written migration files for many workflows and catches schema drift between environments automatically. It also supports a versioned migration workflow for teams that prefer explicit migration files.

What Atlas Does

• Computes migration plans by diffing the current database state against a desired schema definition
• Supports declarative schemas in HCL, SQL, or ORM definitions (GORM, Ent, Sequelize, Django, and more)
• Detects schema drift between environments and reports differences
• Generates versioned migration files for traditional sequential migration workflows
• Lints migration files to catch destructive changes before they reach production

Architecture Overview

Atlas works by connecting to a database, reading its current schema into an in-memory graph, and comparing it against a target state. The target can be an HCL file, a SQL schema dump, another live database, or an ORM schema. The diff engine produces a set of planned changes which Atlas can apply directly or output as migration files. Versioned migrations are stored alongside a checksum file for integrity verification.

Self-Hosting & Configuration

• Single binary available for Linux, macOS, and Windows with no runtime dependencies
• Configure database URLs via CLI flags, environment variables, or an atlas.hcl project file
• Use dev-url to spin up a temporary database for safe migration planning and linting
• Integrate with CI/CD via GitHub Actions or the atlas migrate lint command
• Atlas Cloud (optional) provides a hosted migration directory and approval workflow

Key Features

• Automatic migration planning from declarative schema definitions
• Schema drift detection comparing live databases against expected state
• Migration linting that warns about destructive operations like column drops
• ORM integration reads schemas from GORM, Ent, Django, SQLAlchemy, and more
• Checksum-based migration integrity verification similar to Go module sums

Comparison with Similar Tools

• Flyway — Versioned migration files only; no declarative schema or automatic plan generation
• Liquibase — XML/YAML changesets with rollback support; more verbose and Java-dependent
• golang-migrate — Lightweight CLI for SQL migrations; no schema inspection or drift detection
• Alembic — Python and SQLAlchemy specific; Atlas is language-agnostic with broader ORM support
• Prisma Migrate — TypeScript ORM migrations; Atlas covers more databases and ORMs

FAQ

Q: Do I have to use the declarative workflow? A: No. Atlas supports both declarative (schema apply) and versioned (migrate) workflows. You can use either or combine them.

Q: Which ORMs does Atlas integrate with? A: Atlas can read schemas from GORM, Ent, Django, SQLAlchemy, Sequelize, TypeORM, Hibernate, and more through its provider system.

Q: Is Atlas Cloud required? A: No. Atlas CLI is fully functional without Atlas Cloud. The cloud service adds collaboration features like migration approval and schema visualization.

Q: How does it handle data migrations? A: Atlas focuses on schema (DDL) changes. For data migrations, you can add custom SQL statements to versioned migration files.

Sources

• https://github.com/ariga/atlas
• https://atlasgo.io/docs