Catalog & Metadata

CatalogSelf-Hosted MetadataTime Travel

Stable On by default · production-ready

What it is

Every database needs a catalog: the list of tables, the columns inside them, indexes, constraints, and policies. In most engines the catalog lives in a separate store or a custom file format — which means recovering after a crash takes two coordinated mechanisms, one for catalog and one for data, to agree on what was committed.

AetheriusDB stores the catalog in ordinary system tables, alongside your user data and sharing the same history. If user data survives a crash, the catalog survives it identically. If you can time-travel a row, you can time-travel a column definition.

Why it matters

• One recovery path — recover and you have both your data and the schema that interprets it, with no race windows or orphaned tables.
• Free schema history — every CREATE, ALTER, and DROP is a row in a system table at a known point in time. “What did this table look like last Tuesday?” is just SELECT ... AS OF TIMESTAMP.
• Hot planning — catalog tables are kept resident in memory, so the planner never waits on disk to resolve a column.

How you use it

You typically don’t touch the catalog directly — DDL statements do it for you. But because the catalog is just tables, you can query it to introspect your schema or to see how it has evolved over time.

-- A schema change is a normal write.
ALTER TABLE users ADD COLUMN tier TEXT DEFAULT 'standard';

-- Look at every column the catalog knows about today.
SELECT t.name AS table_name,
       c.name AS column_name,
       c.data_type,
       c.nullable
FROM   aetherius_catalog.tables  t
JOIN   aetherius_catalog.columns c USING (table_id)
WHERE  t.name = 'users'
ORDER BY c.column_id;

-- See what the schema looked like before the ALTER.
SELECT name, data_type
FROM   aetherius_catalog.columns
AS OF TIMESTAMP '2026-05-01 00:00:00'
WHERE  table_id = (SELECT table_id FROM aetherius_catalog.tables
                   WHERE name = 'users');

The catalog is queryable like any other schema. That makes audits, compliance reports, and “who changed what when” investigations one SELECT away.

Indexes and system views

Every index and constraint you declare is catalog metadata too — including the index method (PTI/BTREE/HASH/HNSW/IVFFLAT), its WITH (…) tuning, any partial-index predicate, and covering INCLUDE aggregates. Because it lives in the catalog snapshot, every index survives a restart: vector indexes rehydrate at boot, tree and covering-aggregate structures rebuild from a scan, and declared graph indexes re-arm from their definition.

The engine also exposes runtime index state through system views. For example, the learned and declared relationship edges of the Graph Index are visible one SELECT away:

SELECT * FROM system.join_graph;
-- edge | declared | parent_rows | child_rows | bytes | hits | last_used_epoch

Key concepts

Concept	What it means
System table	An ordinary table managed by the engine itself, queryable with normal SQL.
Always-resident	Catalog tables are kept in memory at all times for instant lookup.
Time-travel	Catalog and data share one timeline, so AS OF TIMESTAMP works for schema too.

Tip

Treat the aetherius_catalog schema as read-only from application code. Use DDL statements to mutate it — that way constraints, cascades, and indexes are kept in sync automatically.

Heads up

Because catalog history is preserved, a DROP TABLE is recoverable via time-travel until history is compacted past that point. For genuine forget-this-ever-happened deletion, use the explicit purge command — a separate, deliberate operation.

Schema-as-Code →

Git-style branching, instant DDL, and rollback for your schema.

Time Travel →

The history that makes AS OF queries possible.

Storage & Recovery →

How catalog and data recover together.