---
title: "Status and SQL surfaces"
description: "Query authority, topology, backup, and durability state through the managed SQLite connection."
section: "Reference"
source_url: "https://sqlstyle.com/docs/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

```sql
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

```sql
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

```sql
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:

```sql
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

```sql
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:

```sql
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:

```sql
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:

```sql
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:

```sql
SELECT sqlstyle_wait_for_authority_change(observed_authority, timeout_ms);
```

## Live read snapshots

Pin the calling connection's current committed snapshot:

```sql
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:

```sql
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:

```sql
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

```sql
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.