Talk to PostgreSQL, MySQL, and SQLite from iii — query, execute, transactions, prepared statements, and change feeds.
iiiverifiedexact versions are immutable; binary and bundle artifacts are digest-pinned.
Open an interactive transaction; returns a handle to use with transactionQuery/transactionExecute/commitTransaction/rollbackTransaction.
Logical database name. Optional — omitting it targets the sole configured database, or `primary` when several are configured.
JSON wire envelope returned by `beginTransaction`.
Read a table page by page with typed filters and sorts, without writing SQL. Filters are structured (column, op, value) and compile to a parameterised WHERE for the driver in hand; the total honours the same filters. Use an equality filter at page_size 1 to follow a foreign key.
Combined with AND.
Postgres only. Rejected elsewhere rather than silently ignored.
Kept in the list but not applied. A caller refining a query wants to switch one condition off and back on without losing how it was built, and a console that only offers delete makes that a retype.
Upper bound for `between`.
Operands for `in` / `not_in`.
A filtered `COUNT(*)` is a second query and can be expensive on a large table. Turn it off while the caller is still typing.
Zero-based.
Applied in order; sort priority is position in the list.
Derived from a sentinel row, so it is correct without a count.
Total matching the same filters. Absent when not requested.
Profile a table's columns. Reads the planner's own statistics by default, which is free and approximate; `exact` runs real aggregates and scans the table. To profile rows you already hold, pipe a browseTable result through the fp worker instead.
Omit to profile every column.
Run real aggregates instead of reading planner statistics. This scans the table.
True when the numbers came from the planner rather than a count.
Only populated in `exact` mode; the planner's own most-common-value lists are not portable enough to report faithfully.
Commit and finalize an interactive transaction.
Delete a saved query by id or by name.
Either the id returned by `saveQuery`, or the name it was saved under.
Describe every table at once — the same shape as describeTable, but one catalog query per aspect across the whole database instead of one call per table. Use this to reason about relationships; set include_indexes only when you need them.
Indexes cost one extra catalog query. Off by default because the common caller (a relationship diagram) only needs columns and keys.
Restrict to these tables. Omit for every table in the database.
1-based ordinal, as the driver reports it.
Driver-reported type text (`TEXT`, `integer`, `varchar(255)`).
Indexed columns in ordinal order. Empty when the index is on an expression rather than plain columns.
Planner estimate, never a `COUNT(*)`. Absent when the driver has no cheap estimate (sqlite) or has not analyzed the table yet.
True when `max_tables` cut the result short. Never silently truncate.
Describe one table or view: columns with type, nullability, default, primary-key membership and foreign-key target; plus indexes and a planner row estimate. Foreign keys are structured (schema, table, column), not a joined string.
Table or view name. May be schema-qualified (`analytics.events`) on postgres; prefer the explicit `schema` field when the name itself contains a dot.
1-based ordinal, as the driver reports it.
Driver-reported type text (`TEXT`, `integer`, `varchar(255)`).
Indexed columns in ordinal order. Empty when the index is on an expression rather than plain columns.
Planner estimate, never a `COUNT(*)`. Absent when the driver has no cheap estimate (sqlite) or has not analyzed the table yet.
Run a write statement (INSERT/UPDATE/DELETE/DDL).
Logical database name. Optional — omitting it targets the sole configured database, or `primary` when several are configured.
Run an ordered batch of SQL statements atomically (bare strings or {sql, params} objects); rolls back on first failure.
Logical database name. Optional — omitting it targets the sole configured database, or `primary` when several are configured.
Optional: `read_committed` | `repeatable_read` | `serializable`.
Statements to run in order inside one transaction. Each entry is either a bare SQL string or `{ "sql": "...", "params": [...] }` — use `params` for dynamic values instead of inlining them into the SQL.
Return a statement's query plan as a tree with per-node costs, row estimates and warnings, instead of the driver's raw text. `analyze` collects real timings by RUNNING the statement, so it defaults to false and is refused for anything that is not a single read.
Runs the statement to collect real timings. Refused for anything that is not a read.
The driver's own output, so a caller is never stuck when the shape is one we do not recognise.
How a table is laid out for reading: column widths, hidden columns and column order. Stored in the state worker rather than a browser, so it survives a restart and any caller can set it up for someone else.
Columns the reader has hidden. Order is not meaningful.
Column display order. Names not listed keep their natural position after those that are, so adding a column to the table does not require re-saving the view.
Per-column pixel width. Absent means "size to content".
Live pool occupancy plus active queries, table sizes, blocking locks and cache hit ratio. Each section reports separately as available, unsupported or denied, so a driver gap or a restricted role is never mistaken for an empty result.
One section of the report.
One section of the report.
Fraction of block reads served from cache. A healthy OLTP database usually sits well above 0.99.
One section of the report.
Live pool occupancy, for `database::health`. `size` and `idle` are `None` where the underlying pool does not expose them — `mysql_async` keeps its counters private. Reporting `None` rather than zero matters: "unknown" and "no idle connections" are different answers, and a health panel that conflates them is actively misleading.
One section of the report.
Recent queries run against a database, newest first. Best effort — recording never blocks or fails a query, so this is a convenience rather than an audit log. For an audit trail bind database::row-changed.
List all configured databases with connection details (driver, credential-redacted URL, pool settings, TLS mode). Config only — no health checks or live pool statistics.
"postgres" | "mysql" | "sqlite".
Logical key (e.g. "primary").
Pool settings echoed back from config (no live stats).
TLS settings. `ca_cert` is reported as a presence boolean only — never the path, which would leak filesystem layout.
Connection URL with credentials redacted.
List the saved queries for a database, sorted by name.
List every table and view in a database, with its kind and (on postgres) its schema. Reads the driver's own catalog, so no dialect-specific SQL is needed from the caller.
Logical database name. Optional — omitting it targets the sole configured database, or `primary` when several are configured.
Internal: reload connection pools from the authoritative configuration when it changes.
Configuration id that changed (advisory; the handler re-fetches the value). Schema-only: kept to publish a typed request schema; the handler ignores it.
Prepare a parameterized statement once.
Logical database name. Optional — omitting it targets the sole configured database, or `primary` when several are configured.
Run a read-only SQL query and return the result rows.
Logical database name. Optional — omitting it targets the sole configured database, or `primary` when several are configured.
Rollback and finalize an interactive transaction.
Run a previously-prepared handle.
Save a named query against a database. Stored in the state worker, so it survives restarts and an agent can save one for a human to find in the console. Saving under an existing name replaces it.
Replace the stored layout for a table. Widths are clamped to a usable range; columns the table no longer has are kept rather than rejected, so a rename degrades to a missing width instead of an error.
Columns the reader has hidden. Order is not meaningful.
Column display order. Names not listed keep their natural position after those that are, so adding a column to the table does not require re-saving the view.
Per-column pixel width. Absent means "size to content".
Lay out the schema as a diagram: positioned table nodes and routed foreign-key edges, plus the hub degree of each table, the isolated tables, and the remaining edge crossings. Reads the whole catalog in a handful of queries rather than one per table.
How many foreign-key hops out from `focus` to include. Ignored without one. 1 is the table and its direct relations.
Lay out only the neighbourhood of this table. A whole schema drawn at once answers "what exists"; it does not answer "what does this table touch", which is the question actually being asked most of the time. With a focus the diagram becomes explorable one hop at a time instead of a wall to be scanned.
Connected groups, with the box that encloses each. A schema is usually several independent clusters rather than one graph, and saying so is most of what makes a large diagram readable — a reader can take in "four unrelated groups" at a glance instead of scanning for edges that are not there.
The most-referenced table in the group, if it has more than one member.
Stable index, in layout order.
Member tables, by node id.
Edge crossings remaining after ordering. Lower is a tidier diagram.
Polyline, already routed. Anchored on the column row where the column is visible, on the node edge otherwise.
Echoed when the caller asked for a neighbourhood rather than the whole schema.
Tables one hop beyond what was drawn. Non-empty means there is more to expand into, which is the difference between a diagram that looks complete and one that says where it stops.
Tables with no foreign keys at all, placed on a trailing shelf.
Number of foreign keys touching this table, in or out. Renderers use it to emphasise hubs.
Columns not drawn because of `MAX_ROWS`.
Terminate a backend session, or cancel just its running statement with `cancel_only`. Takes an id from database::health. Separate from health because it is a write.
Ask the backend to cancel the running statement but keep the session. The default terminates the session outright.
Backend pid (postgres) or connection id (mysql), as reported by `database::health`.
Probe a candidate database config (url + optional tls) with one throwaway connection, without touching configured pools. Reports ok/driver/latency/server version; failures are data, not errors.
Overall budget for the attempt. Default 5000, capped at 30000.
TLS settings to probe with. Defaults like a configured database (mode `require`) when omitted.
Optional path to a PEM file containing one or more CA certificates. Additive by default — these certs **extend** the system trust store rather than replace it. Set `trust_native: false` for strict-isolation deployments that must only trust the operator-supplied bundle.
TLS mode: `disable` (plaintext), `require` (default), or `verify-full`.
When true (default), the system/native trust store is loaded in addition to any `ca_cert` bundle. Set to `false` to trust only the `ca_cert` certificates — useful when an operator wants to pin trust to a private CA and explicitly *not* accept the public web PKI. Effective for postgres. MySQL is forced-additive: `mysql_async`'s rustls path always loads the Mozilla `webpki_roots` bundle and extends it with `ca_cert` — there is no upstream knob to suppress the bundled roots, so `trust_native: false` only affects postgres. Note: with both `trust_native: false` *and* `ca_cert: None` on postgres, no trust roots are available; pool construction fails with `CONFIG_ERROR`.
Connection url to probe (`postgres://…`, `mysql://…`, `sqlite:…`).
"postgres" | "mysql" | "sqlite" | "unknown".
Wall time of the whole attempt.
Why the probe failed (credentials scrubbed). Absent on success.
Whether a connection was established and answered a query.
Server version string, when the probe got far enough to ask.
Run a sequence of statements atomically.
Logical database name. Optional — omitting it targets the sole configured database, or `primary` when several are configured.
Run a write statement inside an interactive transaction. BEGIN/COMMIT/ROLLBACK are rejected; use commit/rollbackTransaction.
Run a read-only SQL query inside an interactive transaction.
Serve the database worker's injected console UI assets (content function for its console:script / console:style triggers).
The asset path from the trigger config (e.g. `state/page.js`).
The asset source, verbatim.
MIME type the console should serve the asset with.
Fires after this worker commits a row change, filtered by `db`, optional `table`, and optional `ops`. Reports only mutations made THROUGH this worker — not change data capture.
Database handle, as named in the worker's config. Required — a binding that watched every database would fire for traffic its owner never asked about.
Operation filter. Omit to hear every operation.
Table filter. Matched case-insensitively and ignoring a schema qualifier. Omit to hear every table in the database.
Epoch millis at emit time.
The kind of row change a statement makes.
The `RETURNING` rows, when the caller asked for them. Absent otherwise — this trigger reports that a change happened, not the new row.
`null` when the statement was recognisably a write but its table could not be read out of the SQL (a CTE-wrapped write, for example).
