Module sql 

Shared SQL statement surface used by both the read follower and the write master.

This module is intentionally transport-light: it owns classification, the version-1 tagged value codec, positional/named binding, and result materialization. Routing and transaction ownership remain with the host. Keeping these pieces here prevents a follower and master from disagreeing about whether caller-supplied SQL is safe to run on a read-only connection.

Structs

PublicAuthorizerGuard

SqlColumn

SqlStatementRequest

StatementResult

Enums

SqlArgs

StatementClass

StatementRunError

Constants

SQL_BIND_LIMIT

SQL_BIND_VALUE_BYTE_LIMIT

SQL_RESULT_BYTE_LIMIT

SQL_RESULT_ROW_LIMIT

SQL_TEXT_LIMIT

Named v1 request limits. They are deliberately conservative relative to SQLite’s own limits; exceeding one is a request/result error, never silent truncation.

Functions

canonical_migration_checksum

Lowercase SHA-256 of the compact JSON encoding of a normalized statement vector.

classify_statement

Classify by the first executable top-level keyword, after stripping comments and accounting for CTE bodies. sqlite3_stmt_readonly remains an execution-time cross-check.

decode_wire_value

Decode one v1 SQL wire value. Integers use a tagged decimal string; finite REALs use JSON numbers and infinities use the tagged float form. There is deliberately no BLOB tag in v1.

encode_wire_value

ensure_single_statement

Reject a second SQL statement while permitting a single trailing semicolon and comments. SQLite’s own completeness parser identifies the outer END; of a CREATE TRIGGER ... BEGIN body, so semicolons between trigger-body statements are not mistaken for a prepare tail.

from_sql

One result cell from its raw SQLite storage class — the storage-class twin of decode_wire_value’s JSON one. No engine coercion (a caller here is writing SQL, not feeding the pipeline); BLOB has no OwnedValue form. Shared by the single-thread writer, the parallel Cluster mutator-read path and ReadConn — and re-exported (sql_cell_to_owned) for the replicator write-master’s session reads, which MUST convert cells identically or the two masters’ /mutate-session/query replies drift (REPLICATOR-INTERACTIVE-TXN-DESIGN.md §7).

install_public_authorizer

Install the reserved-object authorizer on conn for the lifetime of the returned guard. The authorizer denies any statement that touches a reserved _rindle_* / hct_* / sqlite_* object (and any connection-local action — ATTACH/PRAGMA/DETACH), matching the fail-closed rule the public /v1/sql/* execute path already enforces. Exposed so callers outside this module (the mutation facade’s raw statement executor) can bracket a bare conn.execute with the same guard the run_statement path uses. class is the statement class being run.

is_embedded_schema_statement

The trusted embedded replica’s schema setup surface accepts ordinary DDL plus its long-standing bounded ANALYZE maintenance call. Keep this narrower predicate separate from classify_statement: public SQL deliberately rejects ANALYZE, while Db::exec_ddl and Cluster::exec_ddl have historically supported it.

normalize_migration_statements

Normalize migration carrier slots by splitting each one and flattening retained statement bytes in order. Delimiters and trimmed outer whitespace are not identity; comments and whitespace retained inside each statement remain byte-significant. A slot-less migration is a valid version-only journal entry; a supplied slot must still contain a statement.

preflight_public_ddl_statement

Validate a public DDL statement through the same parser and reserved-object authorizer as run_ddl_statement without executing it. The cluster DDL coordinator uses this preflight before installing its action-recording authorizer; SQLite supports one authorizer per connection, so the real execution then runs through run_preflighted_ddl_statement while the recorder observes the exact DROP/ALTER/index actions.

run_ddl_statement

Execute a DDL-class statement after the host has established the migration transaction and quiesced other writers. Keeping this entry point explicit prevents ordinary transaction callers from accidentally admitting DDL.

run_preflighted_ddl_statement

Execute DDL already accepted by preflight_public_ddl_statement while preserving the caller’s currently-installed authorizer (the cluster’s DDL action recorder).

run_statement

Prepare through rusqlite’s per-connection cache, bind either argument form, step through every row (including DML RETURNING), and materialize the common result shape.

split_migration_file

Split one migration-file carrier, treating an exact Drizzle breakpoint physical line as an explicit boundary before passing every carrier through the shared SQL scanner. The breakpoint comment itself is not canonical migration content.

split_sql_script

Split an ordered autocommit script at top-level semicolons. Delimiters inside quoted values, identifiers, and comments are preserved. Empty/comment-only segments are ignored.

split_sql_script_allow_empty

The migration-file variant of split_sql_script. It uses the same quote/comment/trigger aware scanner but permits a comment-only carrier slot so a whole file can be flattened without inventing a second SQL lexer.

statement_is_insert

Whether the statement action can update SQLite’s connection-local last-insert-rowid counter. The host still checks the target table’s WITHOUT ROWID metadata before reporting it.

strip_comments_and_literals

sql with comments removed (each replaced by one space) and single-quoted string literals blanked, for the lexical DDL scanners (design 227 review fix): SQL comments may sit between any two tokens — DROP -- reason\nTABLE kv is valid SQL — so keyword-adjacency scans must run over comment-free text, and literals are blanked so a DEFAULT 'drop column' cannot false-positive. Identifier quoting ("n", `n`, [n]) is preserved verbatim, doubled '' escapes are honored, and an unterminated span runs to the end of the text (harmless for scanning — such a statement fails real execution before any scanner’s verdict matters).

to_value

Map an OwnedValue to a rusqlite bound parameter. Shared with the parallel Cluster write path.