Module schema 

Schema introspection — turn an open Connection into a textual schema dump the LLM can ground its SQL generation on.

Why we don’t SELECT FROM sqlrite_master

The sqlrite_master catalog persists the original CREATE TABLE SQL, so reflecting via SQL would work. But we already have the same information typed in Database.tables (declared columns, primary key, NOT NULL / UNIQUE, vector dimensions, …) — going through SQL would mean parsing the round-tripped CREATE statement a second time. Walking the typed structure is cheaper and matches whatever the engine considers authoritative right now (a relevant distinction inside an open transaction, where the catalog’s persisted state may already be stale).

Determinism (matters for prompt caching)

Tables are dumped in alphabetical order, columns in declaration order. The output is byte-stable for a fixed schema — that’s what lets cache_control: ephemeral actually hit on repeat calls. Any change to the dump format (adding a clause, changing whitespace) will invalidate the cache once for everyone, but steady-state hits are cheap.

Functions

dump_database

Same as dump_schema, but takes a Database reference directly. Useful for callers that already hold a Database (e.g., advanced embedders bypassing the public Connection API).

dump_schema

Render the schema of every user-visible table as a sequence of CREATE TABLE … (…); statements, sorted alphabetically by name.