atlas

Atlas Operator

Overview

Database schema management on Kubernetes via db.atlasgo.io/v1alpha1. Two approaches: AtlasSchema (declarative — define desired schema, operator diffs and applies) and AtlasMigration (versioned — ordered SQL scripts). Deployed via OCI Helm chart: ghcr.io/ariga/charts/atlas-operator (latest: 0.7.32).

CRD Reference

AtlasSchema (Declarative)

apiVersion: db.atlasgo.io/v1alpha1
kind: AtlasSchema
metadata:
  name: app-schema
spec:
  urlFrom:
    secretKeyRef:
      name: db-creds
      key: url              # postgres://user:pass@host:5432/db?sslmode=require

  schema:
    sql: |
      CREATE TABLE users (
        id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
        email TEXT UNIQUE NOT NULL,
        created_at TIMESTAMPTZ DEFAULT now()
      );
      CREATE TABLE posts (
        id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
        user_id UUID REFERENCES users(id),
        title TEXT NOT NULL
      );

  policy:
    lint:
      destructive:
        error: true          # Block DROP COLUMN / DROP TABLE
    diff:
      skip:
        - drop_column        # Skip dropping columns (compatible changes only)
    exclude:
      - "audit_*"           # Glob patterns to ignore

  prewarmDevDB: true          # Default — ephemeral dev container for diff
  allowCustomConfig: false    # Don't allow DB config changes via atlas

AtlasMigration (Versioned)

apiVersion: db.atlasgo.io/v1alpha1
kind: AtlasMigration
metadata:
  name: app-migrations
spec:
  urlFrom:
    secretKeyRef:
      name: db-creds
      key: url

  dir:
    configMapRef:
      name: migration-files   # ConfigMap with SQL migration scripts

  execOrder: linear           # linear | linear-skip | non-linear
  baseline: "000000"          # Start from this version (skip earlier)

  policy:
    lint:
      destructive:
        error: true

  prewarmDevDB: true
  allowCustomConfig: false