Define SQL statement model architecture

[piraz]

Goal

Define the sqlok statement model architecture that replaces direct string-builder thinking with structured SQL statements compiled into SQL + args.

Direction

The project direction is:

Builder DSL → Statement model / AST → Compiler/Dialect → SQL + args

The public API should stay ergonomic, but internally the builder should move toward creating structured statement roots instead of assembling SQL strings directly.

Statement roots

The core statement roots are:

• Select for SELECT/DQL
• Insert for INSERT/DML
• Update for UPDATE/DML
• Delete for DELETE/DML

Each statement root owns the shape of its operation.

Vocabulary

Use Criteria / WhereCriteria for WHERE filtering vocabulary, following the SQLAlchemy _where_criteria model. Predicate may remain an explanatory lower-level term for an individual boolean condition, but it should not be the primary statement field name.

Open design choices

1. Compile API ergonomics

   • stmt.Compile() is more ergonomic.
   • compiler.Compile(stmt) keeps the statement model more passive.
   • Hybrid is acceptable if stmt.Compile() is a thin delegation to compiler logic.

2. Visitor vs compiler-owned dispatch

   • Visitor is the established AST traversal pattern.
   • SQLAlchemy manifests this through __visit_name__ plus compiler.visit_<name> runtime dispatch.
   • Go can express the same contract with explicit interfaces and compile-time substitutability.
   • If package layout is split across ast, dql, dml, and elements, compiler-owned dispatch may avoid import cycles.

3. Package layout

   • Single internal/ast package split by files favors typed Visitor without cycles.
   • Separated packages (internal/ast, internal/dql, internal/dml, internal/elements, internal/compiler) are more modular but complicate typed Visitor.

References

See docs/vision.md for the current project direction and docs/research.md for SQLAlchemy source-backed research.