Schema-as-Code & Migrations

MigrationsInstant DDLRollback

Stable On by default · production-ready

What it is

In a traditional database, ALTER TABLE ... ADD COLUMN on a large table can mean hours of locked rewrites and a long maintenance window — and rolling it back means restoring from backup. Tracking which migrations have been applied usually requires a separate tool with its own version table.

AetheriusDB takes a different stance. Schema changes are normal writes, they finish in milliseconds, and the engine tracks the entire migration history natively. Adding a column is a metadata operation; existing data simply learns to supply the new column’s default value when it’s read. Rolling back is a revert, not a backup restore.

Why it matters

Schema evolution stops being a special, scary operation and becomes a normal part of your development cycle. The migration framework is the database — there’s no second source of truth to drift away from the actual schema state.

• Instant column adds — ADD COLUMN ... DEFAULT is a metadata write, not a data rewrite. Returns in milliseconds even on very large tables.
• Native version tracking — every DDL statement is a timestamped, attributable record. No separate migrations table to keep in sync.
• Branchable rollback — an accidental DROP TABLE is recoverable by reverting to the commit just before it. Milliseconds, not hours.

How you use it

DDL is just SQL. The interesting part is what happens around it: you can open a branch, apply changes, test them in isolation, then merge — exactly like a code review on a feature branch.

-- Instant column add — runs in milliseconds, no data rewrite.
ALTER TABLE users ADD COLUMN tier TEXT DEFAULT 'standard';

-- Try a risky migration on a branch first.
CREATE BRANCH feature_pricing_v2 FROM main;

USE BRANCH feature_pricing_v2;
ALTER TABLE orders DROP COLUMN legacy_discount;
ALTER TABLE orders ADD COLUMN discount_v2 DECIMAL(5,2);

-- Validate, run regression queries, eyeball the schema...

-- Either merge into main…
MERGE BRANCH feature_pricing_v2 INTO main;

-- …or revert to the last good commit on main.
REVERT main TO COMMIT '2026-05-17T12:00:00Z';

There is no external migration runner, no version table, and no “applied / not applied” state to keep in sync. The database is the migration system.

sequenceDiagram
  participant Dev as Developer
  participant Eng as AetheriusDB
  participant Main as main branch
  participant Feat as feature branch

  Dev->>Eng: CREATE BRANCH feature_x FROM main
  Eng-->>Feat: branch created at current commit
  Dev->>Feat: ALTER TABLE orders ADD COLUMN x
  Dev->>Feat: SELECT ... (run tests)
  alt tests pass
    Dev->>Eng: MERGE BRANCH feature_x INTO main
    Eng->>Main: fast-forward (or replay changes)
  else tests fail
    Dev->>Eng: DROP BRANCH feature_x
    Eng-->>Feat: gone; main unaffected
  end

Key concepts

Concept	What it means
Instant DDL	ADD / DROP / ALTER COLUMN are metadata-only writes — existing data is not rewritten.
Branch	A named, isolated copy-on-write view of the entire database, including schema.
Revert	Move a branch’s tip back to an earlier commit; nothing is lost — history is preserved.
Default projection	When data is read for a column added later, the DEFAULT value is supplied on the fly.

Tip

Use branches for any DDL you’d normally feel nervous about — type changes, renames, drops. Test on the branch, merge when confident, discard otherwise.

Heads up

Some changes still require data work — for example, changing the physical type of a populated column (INTEGER → DOUBLE) needs a rewrite pass. The engine performs this safely, but it isn’t free; expect it to be proportional to the column’s row count.

Catalog & Metadata →

The system tables that record every DDL change.

Time Travel →

Read and revert to any past point in time.

Storage & Recovery →

Why schema and data recover together.