Architecture

---

title: Architecture summary: "Two Superpower parsers — the Ddl tokenizer and combinators for CREATE TABLE, the Sql tokenizer and combinators for SELECT — building a record-based syntax tree." tags: [sql-parser, squeal, concept, architecture, sql, parser, superpower, csharp] created: 2026-06-25 status: draft

Architecture

Squeal parses in the two stages Superpower provides: a tokenizer splits SQL text into a stream of typed tokens, then parser combinators consume that stream and build a syntax tree of C# records. The two statement families have separate tokenizers and combinators so each grammar stays self-contained.

The DDL parser

Ddl holds the DdlTokens enum, its Tokenizer, and the combinators for CREATE TABLE (source: Ddl.cs). The token set is broad — column types, constraint keywords, and SQLite specifics such as AUTOINCREMENT, TEMPORARY, and ON CONFLICT. The combinators parse CREATE [TEMP] TABLE [IF NOT EXISTS] [schema.]table (columns) into a CreateTableStatement, each column an identifier, a TypeName, and a list of constraints.

The SELECT parser

Sql holds the SelectTokens enum, its Tokenizer, and the combinators for queries (source: Sql.cs). It produces a SelectStatement — a projection of ProjectedColumns, a TableName, and an optional Predicate — or a SelectCountStatement for SELECT count(*). A WHERE predicate is an expression tree of ConditionalExpression comparisons chained by LogicalExpression AND and OR, over ColumnExpression and StringLiteralExpression operands.

The syntax tree

The statements share a vocabulary of record types (source: Squeal):

• CreateTableStatement, SelectStatement, SelectCountStatement — the statement roots, the SELECT pair behind ISelectStatement.
• ColumnDef, TypeName, TableName, ProjectedColumn — the column, type, table, and projection pieces.
• PrimaryKeyConstraint, NotNullConstraint, UniqueConstraint, CollateConstraint — the column constraints, behind IColumnConstraint.
• Expression, BinaryExpression, ConditionalExpression, LogicalExpression, ColumnExpression, StringLiteralExpression — the WHERE expression tree.
• ColumnTypes, ConditionalOperators, LogicalOperators, Order, ConflictResolutions — the enumerations the records carry.

TableConstraint and TableOptions exist as placeholder records; NumericLiteralExpression is defined but not yet wired into the SELECT parser.