Status and SQL surfaces

Inspect SQLStyle through the SQLite connection your application already has. These tables and functions report authority, nodes, backups, and durability waits.

This reference describes the table names, column schemas, scalar-function overloads, SQLite result codes, and direct-only restrictions in the supported Bedrock build. Logical replication remains a separate capability and does not change this SQL surface.

Authority status

SELECT authority, integrity_mode FROM sqlstyle_status;

authority is held or unheld. The live lease, capture lock, usable image, and writer-admission facts still determine whether a write is accepted.

integrity_mode is standard, lightspeed, or permissive and reports the database policy published by the active runtime owner.

The status surface intentionally does not expose transitional controller state as an application contract.

Topology

SELECT * FROM sqlstyle_topology;

Topology describes the controller-backed view available to the runtime. Treat it as operational information, not as independent permission to write.

Backup history

SELECT rowid, *
FROM sqlstyle_backups
ORDER BY rowid;

sqlstyle_backups projects successful retained records from the durable backup catalog. Its implicit rowid is the persisted catalog row identifier.

Request a backup from a managed connection with object storage enabled:

SELECT sqlstyle_backup();
SELECT sqlstyle_incremental_backup();

These functions synchronously coordinate capture and upload, then wait until the controller has accepted the uploaded transaction frontier. The wait is bounded and interruptible. They must be used as standalone statements on a direct managed connection.

DBH capture statistics

SELECT * FROM sqlstyle_dbh_stats;

The single row exposes cumulative and maximum timing, byte, seal, failure, and handoff counters for the local DBH workers. A managed database without active capture reports zero-valued counters rather than changing the schema.

Durability waits

Wait for a local transaction frontier when an application workflow requires it:

SELECT sqlstyle_wait_for_txn(primary_token, txn, timeout_ms);

Use primary_token = 0 for a local-frontier wait. A nonzero token makes the wait lineage-safe across primary changes. A zero transaction succeeds immediately, and a zero timeout waits without a deadline.

Run waits and authority requests as standalone statements outside a transaction. They return SQLITE_MISUSE in an active transaction, preventing a wait from retaining locks needed by the operation it is waiting for. Transaction zero requires no wait and succeeds immediately even inside a transaction.

Read the transaction assigned to the calling connection’s latest successful commit:

PRAGMA sqlstyle_last_commit_txn;

The value is connection-local. It is zero before the first successful commit and on unmanaged connections.

Wait for a required number of replicas:

SELECT sqlstyle_wait_for_replica_watermark(
  txn,
  replica_count,
  timeout_ms
);

The transaction is a SQLStyle transaction frontier and replica_count must be positive. A positive timeout is bounded in milliseconds; zero waits without a deadline. Pass NULL for txn to use the calling connection’s most recently committed SQLStyle transaction.

Wait for the local authority state to change:

SELECT sqlstyle_wait_for_authority_change(observed_authority, timeout_ms);

Live read snapshots

Pin the calling connection’s current committed snapshot:

SELECT sqlstyle_read_begin();
SELECT * FROM orders;
ROLLBACK;

sqlstyle_read_begin() starts a read transaction and returns its SQLStyle transaction number. On another connection to the same managed database, join that snapshot by binding the returned number:

SELECT sqlstyle_read_begin_at(?1);
SELECT * FROM orders;
ROLLBACK;

sqlstyle_read_begin_at() returns 1. At least one reader must keep the snapshot open while another connection joins it. After its last reader ends the transaction, joining returns SQLITE_ERROR_SNAPSHOT; this API does not restore historical data. End each reader with ordinary COMMIT, ROLLBACK, or connection closure.

To observe the current readable transaction without retaining a snapshot:

SELECT sqlstyle_current_read_txn();

All three functions require a standalone statement on a managed connection outside a transaction. Snapshot numbers are non-negative SQLite integers. The functions are SQLITE_DIRECTONLY and cannot run through a view or trigger.

Requesting authority

SELECT sqlstyle_request_authority(timeout_ms);

This asks the controller to move writer authority to the requesting connection and waits for the grant. It returns immediately when the local runtime already holds authority.

Authority movement is fenced by the controller. A request is not permission to write until sqlstyle_status.authority is held.

Shutdown observation

Shutdown operation handles remain a native API because they must survive the calling connection closing. Begin shutdown while a connection is alive, close the application’s connections, then wait on the operation for resource release. A statement running on the database cannot wait for every connection to close while retaining its own connection.