rdbms-playground/docs/plans/20260525-adr-0035-sql-ddl-4a2.md

Plan: ADR-0035 Phase 4, sub-phase 4a.2 — per-column CHECK/DEFAULT + composite UNIQUE

The constraint slice's first half. Adds, to advanced-mode SQL CREATE TABLE, the constraints that need no new internal table: per-column CHECK (<expr>) and DEFAULT <expr> (via the ADR-0031 sql_expr surface, stored/echoed as raw SQL text), and composite UNIQUE (a, b). Table-level / multi-column CHECK is 4a.3 (it needs a new __rdbms_* metadata table — SQLite has no PRAGMA for CHECK). Builds directly on the 4a SqlCreateTable command + grammar.

1. Baseline

• Tests: 1739 passing, 0 failing, 0 skipped, 1 ignored; clippy clean. Branch main, last commit 631074f (4a). 4a.2 starts here.

2. Decisions locked with the user (do not re-litigate)

1. Scope (2026-05-25): 4a.2 = per-column CHECK/DEFAULT + composite UNIQUE(a,b). No new internal table. Table-level / multi-column CHECK → 4a.3 (new __rdbms_* metadata table).
2. CHECK/DEFAULT are stored as raw SQL text, not a compiled Expr: sql_expr is validate-only (no AST). Per-column CHECK reuses the existing __rdbms_playground_columns.check_expr column; DEFAULT round-trips via the engine's native PRAGMA table_info (dflt_value) — both echoed verbatim by schema_to_ddl.
3. Single-column table-level UNIQUE(a) normalises into the column's unique flag (so it round-trips via the existing single-column path, read_unique_columns); composite UNIQUE(a,b) is a new TableSchema.unique_constraints field, detected on read via the UNIQUE-constraint index (PRAGMA index_list origin u, >1 column).

3. Phase 1 — Requirements checklist (4a.2)

Functional

• Column constraint DEFAULT <sql_expr> parses (advanced mode) and is stored/emitted as raw SQL; round-trips via PRAGMA table_info.
• Column constraint CHECK (<sql_expr>) parses and is stored as raw SQL in __rdbms_playground_columns.check_expr; round-trips.
• CHECK/DEFAULT accept the full sql_expr surface (the same fragment WHERE/projections use), not the DSL subset.
• Table element UNIQUE (<col>, …): single-column normalises into the column's unique; composite (≥2) → unique_constraints.
• Composite UNIQUE emitted in the create DDL and the rebuild DDL (schema_to_ddl); detected by read_schema_snapshot.
• The 4a "not yet supported" parse-rejection is lifted for these forms (the grammar now admits them); table-level/multi-column CHECK still rejected (→ 4a.3).
• One undo step; structural execution reuses do_create_table.
• Engine-neutral errors; STRICT preserved.

Cross-cutting

• Round-trip: a table with per-column CHECK/DEFAULT and a composite UNIQUE survives save → load → rebuild (DDL + enforcement).
• history.log / replay unchanged (these are part of the same create write command).

Testing (ADR-0008 four tiers)

• Tier 1: builder tests — CHECK/DEFAULT raw text captured verbatim; composite vs single UNIQUE routing; the full sql_expr surface parses; table-level/multi-column CHECK still rejected.
• Tier 3 (tests/sql_create_table.rs): worker round-trip — CHECK enforced (a violating insert fails), DEFAULT applied (an omitted column gets it), composite UNIQUE enforced (dup rejected); rebuild preserves all three.

4. Architecture & design

4.1 Grammar (src/dsl/grammar/sql_create_table.rs)

• Column constraints — extend COL_CONSTRAINT_CHOICES with:
  • DEFAULT <sql_expr>: Seq[ Word("default"), Subgrammar(&sql_expr::SQL_OR_EXPR) ].
  • CHECK ( <sql_expr> ): Seq[ Word("check"), Punct('('), Subgrammar(&sql_expr::SQL_OR_EXPR), Punct(')') ].
• Table element — extend ELEMENT_CHOICES with table-level UNIQUE ( col, … ): Seq[ Word("unique"), Punct('('), Repeated(uniq_column, ',', 1), Punct(')') ]. (Distinct ident role, e.g. unique_column, so the builder routes it separately from pk_column.) No table-level CHECK element (→ 4a.3).
• Column-validation in CHECK at create time — verify by test (§6.1): the sql_expr column refs name columns being defined, which don't exist in the schema cache yet. Confirm they don't raise an unknown-column [ERR]; mirror whatever the simple-mode expr-based CHECK does.

4.2 Raw-text capture (the load-bearing mechanism)

MatchedItem carries span: (usize, usize) byte offsets into the source (confirmed via build_sql_insert, which slices source by a keyword's span). The builder (build_sql_create_table, which already receives source) captures each CHECK/DEFAULT expression's raw text as source[first_expr_terminal.span.0 .. last_expr_terminal.span.1]:

• CHECK ( … ) — paren-delimited: take the text between the matched ( and ) terminals.
• DEFAULT <expr> — the sql_expr match is maximal, so its terminals are exactly the default expression; take from the first expr terminal after the default keyword to the last before the next element boundary (comma / ) / next constraint keyword).

4.3 Column representation for raw CHECK/DEFAULT (implementer call)

ColumnSpec.check: Option<Expr> / default: Option<Value> can't hold raw SQL. Chosen: add check_sql: Option<String> and default_sql: Option<String> to ColumnSpec (the advanced-mode raw-text alternative). do_create_table prefers the raw _sql field when present, else compiles the Expr/Value (simple-mode path). ColumnSpec::new sets them None; struct-literal sites get check_sql: None, default_sql: None (compiler-found). This keeps SqlCreateTable { columns: Vec<ColumnSpec>, … } and reuses do_create_table rather than forking it.

4.4 Composite UNIQUE end-to-end

• Command::SqlCreateTable gains unique_constraints: Vec<Vec<String>>.
• do_create_table + schema_to_ddl emit UNIQUE (<cols>) table clauses (insertion points: after the table-level PK clause, before FK / STRICT).
• TableSchema.unique_constraints: Vec<Vec<String>> + RawTable.unique_constraints (#[serde(default)], optional-on-read); write_table emits only when non-empty.
• read_schema_snapshot detects them: read PRAGMA index_list origin u + index_info; single-column → ColumnSchema.unique (existing read_unique_columns path), multi-column → unique_constraints (lift the current len() == 1 filter that drops composites).

4.5 Worker / undo / persistence

Same as 4a: one create = one undo step (snapshot_then); structural execution; finalize_persistence writes yaml/CSV/journal. No new Request variant (still SqlCreateTable).

5. Out of 4a.2 scope

• Table-level / multi-column CHECK → 4a.3 (new metadata table).
• FK (4b); DROP (4c); indexes (4d); ALTER (4e–4h).

6. Open items / implementer calls

1. CHECK column-validation at create time — verify (test) that sql_expr column refs to columns-being-defined don't raise an unknown-column [ERR]. If they do, the grammar must suppress schema-existence checks in the CREATE-TABLE CHECK context (as the simple-mode path effectively does). Resolve during step 1.
2. DEFAULT expression boundary — confirm the sql_expr match is maximal enough that the raw-text slice for DEFAULT <expr> ends cleanly before the next element. Covered by builder tests.

7. Devil's Advocate review of this plan

• Raw text vs compiled — round-trip safe? CHECK raw text → the same check_expr column simple mode uses (echoed verbatim by schema_to_ddl); DEFAULT → engine PRAGMA. Both reuse proven round-trip paths. The new piece (composite UNIQUE) gets explicit rebuild tests. ✓
• Reuse vs fork? do_create_table is still the single executor; the check_sql/default_sql fields add a branch, not a fork. ✓
• Single vs composite UNIQUE consistency? Single normalises to column.unique so read-back (which maps single-column origin-u to column.unique) round-trips identically — no asymmetry (the 4a lesson). ✓
• Silent scope creep? Table-level CHECK is explicitly out (4a.3), rejected by the grammar, not silently half-done. ✓

8. Implementation sequence (test-first)

1. sql_expr CHECK column-validation probe (§6.1) → settle the grammar's schema-check behaviour before building the shapes.
2. Grammar + builder, CHECK/DEFAULT — Tier-1 tests (raw text captured verbatim; full sql_expr surface; still-rejected table-CHECK) → red → add the constraint shapes + raw-text capture + ColumnSpec.check_sql/default_sql + do_create_table branch → green.
3. Grammar + builder, composite UNIQUE — Tier-1 (single→column, composite→unique_constraints) → red → add the UNIQUE(…) element + Command/do_create_table/schema_to_ddl emission → green.
4. Persistence round-trip — extend TableSchema + YAML + read_schema_snapshot composite-UNIQUE detection → Tier-3 round-trip tests (CHECK enforced, DEFAULT applied, composite UNIQUE enforced; survive rebuild) → green.
5. Full sweep — cargo test (no regressions) + cargo clippy --all-targets -- -D warnings; engine-neutral string audit.
6. Docs — requirements.md Q1 note; ADR §13 already records 4a.2.

9. Exit gate

• All §3 checklist items satisfied; four tiers green, zero skips; no regression from the 1739 baseline; written DA pass; clippy clean.