Schema Change Workflow

With your project set up, let's walk through the workflow you'll use day-to-day.

Step 1: Make a Schema Change

Edit your schema files to make a change. For example, add a phone column to the users table:

HCL

schema/users.hcl

table "users" {
  schema = schema.public
  column "id" {
    type = serial
  }
  column "name" {
    type = varchar(100)
  }
  column "phone" {
    type = varchar(20)
    null = true
  }
  primary_key {
    columns = [column.id]
  }
}

SQL

schema/users.sql

CREATE TABLE users (
  id serial PRIMARY KEY,
  name varchar(100) NOT NULL,
  phone varchar(20)
);

Using AI agents?

AI coding tools like Claude Code, GitHub Copilot, and Cursor can edit your schema files directly. Atlas provides Agent Skills so agents can also generate migrations, run linting, and apply changes. The agent edits code, Atlas plans and validates deterministically. See the AI Tools page for setup instructions.

Versioned

Step 2: Generate a Migration

Run atlas migrate diff to generate a migration file that reflects your change:

atlas migrate diff add_phone --env local

Atlas compares your schema files against the current migration directory, calculates the diff, and writes a new migration file:

migrations/
├── 20240604131146_baseline.sql
├── 20260410120000_add_phone.sql   ← new
└── atlas.sum

Review the generated SQL:

migrations/20260410120000_add_phone.sql

-- Add column "phone" to table: "users"
ALTER TABLE "public"."users" ADD COLUMN "phone" character varying(20) NULL;

Step 3: Apply

Apply the migration to your local database:

atlas migrate apply --env local

Atlas reports which migrations were applied:

Migrating to version 20260410120000 (1 migration in total):

  -- migrating version 20260410120000
    -> ALTER TABLE "public"."users" ADD COLUMN "phone" character varying(20) NULL;
  -- ok (1.234ms)

  -------------------------
  -- 1 migration
  -- 1 sql statement

Step 4: Verify

Check the migration status of your database:

atlas migrate status --env local

Migration Status: OK
  -- Current Version: 20260410120000
  -- Next Version:    Already at latest version
  -- Executed Files:  2
  -- Pending Files:   0

This is the core loop: edit schema, migrate diff, review, apply. Each change produces a new migration file that can be reviewed in a pull request.

Declarative (State-based)

Step 2: Apply the Change

Run atlas schema apply to compare your schema files against the target database, plan the migration, and apply it:

atlas schema apply --env local

Atlas loads your desired state into the dev database, compares it against the target, and presents a migration plan for approval. The output has three phases:

1. Planning. Atlas shows the SQL statements it will execute:

Planning migration statements (1 in total):

  -- add column "phone" to table: "users":
    -> ALTER TABLE "public"."users" ADD COLUMN "phone" character varying(20) NULL;

2. Analysis. Atlas runs its linting engine on the planned statements and reports any diagnostics (destructive changes, data-dependent operations, non-optimal column ordering, etc.):

-------------------------------------------

Analyzing planned statements (1 in total):

  -- ok (3.21ms)

  -------------------------
  -- 42.5ms
  -- 1 schema change
  -- 0 diagnostics

If diagnostics are found, Atlas highlights them before prompting for approval. For example:

Analyzing planned statements (2 in total):

  -- non-optimal columns alignment:
    -- L2: Table "users" has 4 redundant bytes of padding per row. To reduce disk space,
       the optimal order of the columns is as follows: "created_at", "id", "name",
       "email" https://atlasgo.io/lint/analyzers#PG110
  -- ok (7.44ms)

  -------------------------
  -- 75.9ms
  -- 2 schema changes
  -- 1 diagnostic

3. Approval. Atlas prompts you to approve or abort:

? Approve or abort the plan:
  ▸ Approve and apply
    Abort

After approving, Atlas applies each statement and reports timing:

Applying approved migration (1 statement in total):

  -- add column "phone" to table: "users"
    -> ALTER TABLE "public"."users" ADD COLUMN "phone" character varying(20) NULL;
  -- ok (5.23ms)

  -------------------------
  -- 5.23ms
  -- 1 migration

Approval policies

By default, schema apply prompts for manual confirmation. You can configure a review policy that auto-approves safe changes (e.g. additive-only) and requires manual review for destructive ones. Use --dry-run to preview changes without applying, or --auto-approve for non-interactive environments (not recommended for production).

Step 3: Verify

Run schema apply again with --dry-run to confirm the database matches your schema:

atlas schema apply --env local --dry-run

Schemas are synced, no changes to be made.

This is the core loop: edit schema, schema apply, review the plan, approve. No migration files to manage. For CI/CD integration with pre-approved plans, see Schema Plan and Declarative CI/CD Setup.