atlas

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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

| CRD | Approach | Use When |
|-----|----------|----------|
| `AtlasSchema` | Declarative | Schema should match a desired state (operator auto-diffs) |
| `AtlasMigration` | Versioned | Need sequential migration files, rollback support, audit trail |

## AtlasSchema (Declarative)

```yaml
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)

```yaml
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
```

Migration files in ConfigMap must be lexicographically ordered:

```yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: migration-files
data:
  000001_init.sql: |
    CREATE TABLE users (...);
  000002_add_posts.sql: |
    CREATE TABLE posts (...);
  000003_add_indexes.sql: |
    CREATE INDEX idx_users_email ON users(email);
```

## Credential Patterns

| Pattern | Example |
|---------|---------|
| Connection URL in Secret | `urlFrom.secretKeyRef.key: url` |
| Credentials struct | `credentials.host`, `.user`, `.passwordFrom`, `.database`, `.port` |
| Extra connection parameters | `credentials.parameters: { sslmode: require }` |

Use `credentials` struct when the URL is constructed from multiple Secret keys:

```yaml
spec:
  credentials:
    host: myhost.example.com
    user: app
    passwordFrom:
      secretKeyRef:
        name: db-creds
        key: password
    database: mydb
    port: 5432

From Aidas-dev/k8s-agent-skills, MIT.

More from Aidas-dev/k8s-agent-skills