System Views

Readyset exposes read-only system views under the readyset schema, queryable with plain SELECT statements. Use them to monitor a running deployment.

readyset.replication_status

Reports how far behind Readyset is relative to the upstream database's current replication position. A single row is returned.

SELECT * FROM readyset.replication_status;

Columns

Example output

 replication_mode | upstream_offset | replicator_offset | persisted_offset | consume_lag | persist_lag | heartbeat_staleness_seconds
------------------+-----------------+-------------------+------------------+-------------+-------------+-----------------------------
 postgres         | 0/1A3F2C8       | 0/1A3F200         | 0/1A3F1B0        |         200 |         280 |                       0.004

Notes

• On a quiescent Postgres upstream, consume_lag and persist_lag report a small non-zero value (~288 bytes). This is a measurement artifact from the WAL record that the position query itself generates, not real lag.
• When replication_mode is mysql_gtid, consume_lag and persist_lag are counts of transactions, not bytes.
• heartbeat_staleness_seconds requires --replication-heartbeat to be enabled on the Readyset server, which in turn requires write access to the upstream so Readyset can maintain a small heartbeat table (readyset._heartbeat on Postgres, _readyset_heartbeat on MySQL). If write access is not granted, Readyset logs a warning, disables heartbeat, and the column reports NULL; the other columns are unaffected.
• The poll cadence is controlled by --replication-lag-interval (default 1 second).

Required upstream privileges

• Postgres: none beyond what replication already requires.
• MySQL: REPLICATION CLIENT (already required for replication).
• Heartbeat (optional, either dialect): write access to the upstream.

readyset.users

Lists the usernames currently allowed to authenticate with Readyset. Passwords are never exposed. The list reflects runtime changes made with ALTER READYSET ADD/MODIFY/DROP USER immediately.

SELECT * FROM readyset.users;

Columns

Notes

• user is a reserved word in PostgreSQL (it evaluates to CURRENT_USER), so quote the column to select it explicitly: SELECT "user" FROM readyset.users. On MySQL it may be used unquoted.
• The allowed-users set is seeded on Readyset's first startup from --allowed-users and the --upstream-db-url user, and is managed at runtime with ALTER READYSET ADD/MODIFY/DROP USER thereafter. See User Management.

readyset.cache_grants

Exposes the current cache authorization verdict for every combination of user and cache: whether that user is served from that cache, or routed to the upstream database instead. One row per pair, including pairs the background checks have not resolved yet.

SELECT * FROM readyset.cache_grants;

Columns

Notes

• user is a reserved word in PostgreSQL, so quote the column to select it explicitly: SELECT "user" FROM readyset.cache_grants.
• denied and unknown are served identically (routed to the upstream); they differ only in whether the background check has an answer yet.
• Verdicts converge within one --cache-acl-refresh-interval-secs interval, or immediately on ALTER READYSET FLUSH PRIVILEGES.