DOCSEARCHbyAlgolia
Submit Docs

Atlas Database Schema-as-Code

website·Indexed 35 days ago

https://atlasgo.io/

A database schema-as-code tool for defining schemas using SQL, HCL, or ORMs such as SQLAlchemy, Prisma, and Ent. Features include schema management, security as code, testing, and versioned or declarative CI/CD workflows, alongside Atlas Cloud integration for schema registry and deployments.

Tokens
2.1K
Snippets
3
Records
18
Agent score
23%

What's inside Atlas

  1. Overview of Atlas database schema-as-code tool

    Atlas is a database schema-as-code tool that allows you to define your database schema using SQL, HCL, or various ORMs (such as SQLAlchemy, Django, Prisma, Drizzle, TypeORM, Sequelize, Hibernate, Ent, GORM, EF Core, and Doctrine). It provides capabilities to diff, plan, lint, test, and apply migrations using either declarative or versioned workflows.

    Beyond schema management, Atlas supports:

    • Security as Code: Managing roles, users, and permissions.
    • Data as Code: Declarative seed and reference data.
    • Monitoring as Code: Drift detection with auto-remediation.

    Supported databases include PostgreSQL, MySQL, MariaDB, SQLite, SQL Server, ClickHouse, Oracle, Snowflake, Spanner, Redshift, and Databricks.

  2. Manage database schemas with Atlas

    Atlas provides multiple ways to define the desired state of a database schema:

    • HCL Syntax: Use the Atlas HCL schema language to define tables, columns, indexes, foreign keys, views, functions, and triggers.
    • SQL Schema: Define the desired schema using plain SQL DDL.
    • External Schemas and ORMs: Load the desired state directly from ORMs or external programs.

  3. Execute data operations using Atlas Data Scripts

    Atlas Data Scripts provide declarative code for complex data operations:

    • Transactional Mutations (script exec): Writes data as a single transactional unit with support for conditions, assertions, checks, and rollback semantics.
    • Queries and Reports (script query): Executes SELECT statements with output as CSV or aligned tables.
    • Batched Loops (script loop): Uses keyset and range iterators to process data in batches, including support for calling external services via HTTP commands.
    • Sensitive Data Masking: Redact result columns using REDACT, PARTIAL, HASH, and REPLACE.

  4. Integrate Atlas with CI/CD and Orchestration Platforms

    Atlas provides native integrations and official components for various CI/CD and infrastructure tools to automate schema linting, planning, and deployment. Supported platforms include:

    • GitHub Actions: Install, lint, plan, and deploy.
    • GitLab CI: Dedicated CI/CD components.
    • CircleCI: Official Orbs.
    • Bitbucket: Official Pipes.
    • Azure DevOps: Official extension.
    • Kubernetes: Managed via the Atlas Operator (supports both declarative AtlasSchema resources and versioned AtlasMigration resources).
    • GitOps: Integration with ArgoCD (declarative and migration-based) and Flux CD.
    • Infrastructure as Code: Terraform provider for planning and applying schema changes.
    • Package Management: Helm charts for deploying migrations.

  5. Manage dbt Projects with Atlas

    Atlas can be used alongside dbt to manage the underlying database infrastructure that dbt models rely on. This includes:

    • Managing databases, source tables, lookup data, and grants (while excluding dbt's own models in atlas.hcl).
    • Implementing safe DDL on large warehouse tables to prevent destructive drops via linting and pre-migration checks.
    • Detecting warehouse drift where the actual state no longer matches the defined schema, ignoring dbt-managed models.

  6. Review and approve declarative migration plans

    Atlas supports a review workflow for declarative migrations. You can save a migration plan to the registry, list pending plans, and approve them before execution.
    # Save a declarative migration plan to the registry
atlas schema plan

# List plans waiting for approval
atlas schema plan list --pending

# Approve a specific plan
atlas schema plan approve

  7. Push schemas and migrations to the Atlas Schema Registry

    The Atlas Schema Registry allows you to store migration directories and schemas centrally. You can push these assets using the CLI and then deploy them using atlas:// URLs.
    # Push migration directories
atlas migrate push

# Push schemas
atlas schema push

  8. Test database schemas and migrations

    Atlas provides several testing capabilities to ensure database stability:

    • Schema Testing: Test logic for functions, views, triggers, and queries.
    • Migration Testing: Test data migrations by using seed data and detecting errors.
    • Data Scripts Testing: Validate script logic and privileges using output, match, and error assertions.
    • Migration Plan Testing: Assert on the SQL plans generated by Atlas before they are executed.

  9. Configure AI Coding Agents for Atlas

    Atlas provides specialized skills and instructions to enable AI coding agents (such as Claude Code, Cursor, and Copilot) to manage migrations, data scripts, and Atlas Cloud status.

    Developers can install the SKILL.md file to provide agents with context on:

    • Schema sources, versioned/declarative workflows, CI/CD, linting, testing, drift detection, and cloud operations.
    • For Claude Code specifically, Atlas provides CLAUDE.md instructions, a migration subagent, slash-command skills, and a post-write lint hook.
    Raw skill file: https://atlasgo.io/skills/atlas/SKILL.md

  10. Manage seed and reference data as code

    Atlas provides 'Data as Code' capabilities to manage declarative seed and reference data, generating the necessary DML to sync the desired state with the live database. This is supported for PostgreSQL, MySQL, and ClickHouse.

  11. Manage database security as code

    Atlas allows you to manage roles, users, and permissions as code. It can diff, plan, and apply security changes across various engines, including PostgreSQL (declarative and versioned workflows, including default privileges), MySQL, ClickHouse, Oracle, and Snowflake.

  12. Implement Declarative vs Versioned workflows in Atlas

    Atlas supports two primary workflows for database migrations:

    1. Declarative Workflow: You define the desired schema state, and Atlas automatically plans and applies the migration to reach that state. This includes the ability to pre-plan, review, and approve changes before deployment.
    2. Versioned Workflow: You use migration files. Atlas provides automatic planning, linting, and CI/CD integration. You can generate versioned migrations by diffing the desired state against the current state, and use lint analyzers to detect destructive or backward-incompatible changes before they are executed.