Skip to main content

Manage Your Database Schema as Code

Atlas is built on the concept of "Database Schema-as-Code", where teams define the desired state of their database as part of their code, and use an automated tool (such as Atlas) to test, plan, verify and apply database schema changes (migrations) automatically.

Naturally, the first part of setting up your project is to determine how your "schema as code" project is going to be structured. Atlas provides a lot of flexibility around how to define the "desired state" as we describe below.

Atlas offers three main ways to define the desired state of your database schema:

  1. HCL - HCL based syntax (similar to Terraform) for defining database schemas.
  2. SQL - SQL (DDL) statements to define your database schema. Can be split into multiple files and directories.
  3. ORMs and Frameworks - Use your favorite ORM or framework to define your schema, and load it into Atlas. For example, SQLAlchemy, Entity Framework Core (EF Core), GORM, Drizzle, Django, and more.
  4. Schema Composition - Combine multiple schema sources (HCL, SQL, ORM) into a single desired state using Atlas's schema composition. For example, you can define your core schema in an ORM and augment it with SQL files that add triggers, RLS policies, functions, or other constructs.

SQL Syntax​

Export Your Database Schema to Code

Learn how to export your existing database schema to SQL code using Atlas

SQL Schema Definition

Learn how to define your database schema using SQL files, including Atlas importing system, masking sensitive data, and more.

public/functions/audit_user_changes.sql
-- atlas:import ../public.sql
-- atlas:import ../tables/user_audit.sql

-- create "audit_user_changes" function
CREATE FUNCTION "public"."audit_user_changes" () RETURNS trigger LANGUAGE plpgsql AS $$
BEGIN
    IF TG_OP = 'INSERT' THEN
        INSERT INTO user_audit (user_id, operation, new_values)
        VALUES (NEW.id, 'INSERT', to_jsonb(NEW));
        RETURN NEW;
    // ...
    END IF;
    RETURN NULL;
END;
$$;

HCL Syntax​

HCL Syntax

Define your schema using Atlas HCL

HCL Column Types

How to define HCL column types for various databases

HCL Input Variables

Use input variables in your schema for context-based definitions

schema.pg.hcl
schema "public" {
}

table "users" {
  schema = schema.public
  column "name" {
    type = text
  }
  // ... more
}

ORMs and External Integrations​

ORMs and Frameworks Portal

Guides to help you get started with using various ORMs with Atlas

External Integrations

Load your desired schema from external programs or ORMs

Atlas Configuration​

Atlas Configuration

Using and customizing the Atlas configuration file

Schema Validation and Policies​

Atlas provides commands and tools to ensure your schema definitions are valid and comply with organizational policies before applying them to your databases.

Validate Schema Definitions​

Use the atlas schema validate command to verify that a schema definition can be parsed and loaded correctly by Atlas, and that it is semantically valid, according to the database engine you're using. This fast check is designed for both developers and AI-assisted editors to confirm schema correctness after edits and before running atlas schema apply or atlas migrate diff.

atlas schema validate --dev-url docker://mysql/8/dev --url file://src
atlas schema validate --env dev

If the schema is valid, the command exits successfully without output. If invalid, it prints a detailed error explaining the problem (for example, unresolved references, syntax issues, or unsupported attributes).

Enforce Schema Policies​

Beyond syntax and semantic validation, Atlas lets teams define custom schema linting rules to encode standards, naming conventions, and compliance requirements. These rules are written in HCL using the Atlas Schema Rule language, and allow teams to enforce any organizational policies around database schemas.

Example rule requiring every column to be NOT NULL or have a default value:

predicate "column" "not_null_or_have_default" {
  or {
    default { ne = null }
    null { eq = false }
  }
}

rule "schema" "require-not-null-columns" {
  description = "Require columns to be not null or have a default value"
  table {
    column {
      assert {
        predicate = predicate.column.not_null_or_have_default
        message   = "column ${self.name} must be not null or have a default value"
      }
    }
  }
}

To get started with schema policies, see the Schema Policies Guide.