corium-sql

SQL execution and guarded autocommit mutation planning over immutable Corium database values.

What it does

Projects a Corium Db value as SQL tables, runs queries with DataFusion, and translates a deliberately small DML subset into ordinary Corium transaction forms:

• SqlSession — captures one Db time view and answers SQL queries.
• Current / as-of / since views expose one wide table per attribute namespace (e.g. artist), with cardinality-many attributes as list-valued columns.
• History views expose normalized event relations instead.
• A Corium-owned row API (SqlRow, SqlColumn, SqlValue, SqlType) so callers get typed rows without depending on Arrow directly.
• SqlMutation — plans INSERT, UPDATE, or DELETE against a current basis, exposes the transaction forms and expected basis, and produces RETURNING rows after the caller commits through a transactor.

SqlSession::query remains read-only by construction. SqlSession::mutation is a separate planning path so this crate never bypasses the transactor, authentication, authorization, or durability path.

Mutation subset

• Existing corium.<namespace> projections only; no DDL or schema writes.
• Current views only, one autocommit statement at a time.
• INSERT requires an explicit column list. Omitting e allocates a tempid.
• UPDATE supports one plain target table and SQL expressions in assignments and predicates. NULL clears a scalar; an ARRAY[...] replaces a cardinality-many value.
• DELETE retracts the target namespace's attributes, not the entire entity.
• All three operations support RETURNING.
• A basis fence makes a stale read/modify/write plan fail instead of applying it to a newer database.

Joined/multi-table mutations, conflict clauses, ordered/limited mutations, new keyword interning, explicit transaction blocks, and DDL are deferred.

Dependencies

• corium-core, corium-db — the value being projected.
• datafusion + arrow — SQL planning/execution and the columnar batches produced from a Db view.
• futures, thiserror; tokio (dev) for tests.

Architecture

SQL is a projection layer, not a second storage engine. The catalog derives table schemas from Corium's own schema — attribute namespaces become tables, attributes become columns — and streams rows out of the same covering-index scans the Datalog engine uses, adapted into Arrow RecordBatches for DataFusion. Queries and mutation planning run peer-local against a fixed immutable view; only the normal transactor path commits the generated forms. The read-only query API is used by the corium sql shell, while corium-pgwire connects mutation planning to a write-capable catalog. See docs/sql.md and ADR-0011, and ADR-0015.