User manual
Snapshot of the kbdiag README at generation time.
Command pages:status · sessions · session · locks · txn · waits · slots · space · freeze · vacuum · archive · params · repl · cluster · top-objects · table · top · progress · checkpoint · wal · seq
KingbaseES command-line diagnostics. One static binary that talks the wire protocol directly: no ksql, no interactive screens. Each command runs a single read-only look at a live instance and prints a verdict, the evidence, and the next command to run. Works on single nodes and on repmgr primary/standby clusters.
This is kbdiag 2.0, rewritten in Go; v2.0.0-alpha.1 is its first release. The shell toolkit (v1.x) is frozen; use release v1.0.0 if you need it.
Install
Build a static Linux binary (Go from go.mod), then copy it to the database host:
Use GOARCH=arm64 for ARM hosts. The binary has no runtime dependencies.
Quick start
Commands
| Command | What it shows | Flags |
|---|---|---|
status | Version, data directory, port, role; each standby (on a primary) or the WAL upstream (on a standby); uptime, connections used / usable, database sizes, disk of the data directory (local runs only). FAIL when ordinary users can no longer connect; WARN when a standby is not receiving WAL | |
sessions | Who holds the connections (counted by user, database, application, client), then the client sessions that are not idle, longest transaction first; WARN on long idle in transaction. JSON always carries every session | --all, --limit N, --idle-in-txn-warn S |
session <pid> | One session: who and what it is, its full SQL, the lock it waits for and who blocks it, whom it blocks, what it holds | --lock-wait-warn S, --idle-in-txn-warn S |
locks | Who blocks the most (and what it holds), then every lock wait, longest first, with its direct blockers; WARN on long waits | --limit N, --lock-wait-warn S |
txn | The oldest xid holding back vacuum and who holds it, open transactions, prepared (2PC) ones; WARN on old ones | --limit N, --xact-warn S, --prepared-warn S |
waits | What the sessions doing something wait on, grouped by wait event and state, biggest pile first; idle sessions and background processes only counted | |
slots | Replication slots, inactive ones and the ones keeping the most WAL first; WARN on inactive ones | |
space | Where the space goes: the filesystems holding the data directory, WAL and tablespaces (local runs only), WAL size against max_wal_size and wal_keep_segments, database and tablespace sizes. FAIL when the filesystem holding the data directory or WAL has less free space than one WAL segment; everything else is shown only | |
freeze | How far each database is from transaction ID wraparound, and the oldest tables of this one; WARN past autovacuum_freeze_max_age, FAIL at the stop limit where new transaction IDs are refused | --limit N |
vacuum | The tables with the most dead tuples and where autovacuum’s threshold is for each, what is vacuuming now; WARN when nothing will clean them (autovacuum or track_counts off, or a table past its threshold with autovacuum off for it). Primary only | --limit N |
archive | Whether WAL archiving works: the settings, the last success and failure, WAL waiting to be archived; WARN when the last attempt failed | |
params | The parameters someone set (not at their default) and where: file and line; WARN for each change that waits for a restart | |
repl | Replication from this node’s side: on a primary the synchronous settings and how far each standby is behind; on a standby its upstream, receive and replay. WARN when fewer synchronous standbys stream than asked for, replay is paused, or a standby receives no WAL. Lag is shown, not judged | |
cluster | repmgr’s view (nodes, roles, upstreams, latest events) checked against this node; WARN on two primaries, inactive nodes, a role repmgr has wrong, a standby not attached. Connects to database esrep unless -d is given | |
top-objects | The largest tables (heap, indexes, TOAST) and indexes of this database. Shows only | --limit N |
table <name> | One table: size, rows, vacuum and analyze, freeze age, access, indexes; judged with the freeze and vacuum rules. The name follows SQL rules (unquoted folds to lower case); not found is UNKNOWN | |
top | Cumulative top SQL from sys_stat_statements (since the last reset), with each statement’s share of all execution time; says so when statements are not being collected. Shows only | --limit N, --by time/mean/calls/io/temp |
progress | How far running VACUUM, CREATE INDEX, CLUSTER / VACUUM FULL and CHECKPOINT have got. Shows only | |
checkpoint | The last checkpoint, timed vs requested checkpoints, who writes dirty buffers (checkpointer, bgwriter, backends), and the settings. Shows only | |
wal | Where WAL is, how much sys_wal holds, and what keeps it: max_wal_size, wal_keep_segments, each slot, files waiting to be archived. Shows only | |
seq | Sequences of this database by how much of their range is used; FAIL when one cannot hand out another value | --limit N |
Defaults: idle in transaction 300 s, lock wait 10 s, transaction 300 s, prepared transaction 900 s, all WARN. --limit only trims what is shown; findings always cover every row.
Connection
| Flag | Default |
|---|---|
--host | /tmp (local socket /tmp/.s.KINGBASE.54321); a host name or IP for TCP |
-p, --port | 54321 |
-d, --dbname | test |
-U, --user | system |
--timeout | 10s per query |
--json | print the report as JSON |
The password comes from PGPASSWORD or ~/.pgpass. Every connection is a read-only transaction with a lock_timeout; kbdiag never changes anything. Suggested fixes (such as ROLLBACK PREPARED) are printed, never run.
Output
- First line: command, verdict, and context (version, role, user@location, collection time).
- Findings: an id, a symptom, and a
verifyorfixnext step. - Data: laid out for reading, sizes and durations in readable units;
-is null,?is hidden from this account.--jsongives every probe’s raw table (bytes, seconds) with stable field names.
Exit codes
| Code | Meaning |
|---|---|
| 0 | OK |
| 1 | WARN |
| 2 | FAIL |
| 3 | UNKNOWN: something could not be collected or seen, so kbdiag will not claim OK |
| 64 | Usage error |
| 69 | Cannot connect |
Privileges
Run as system over the local socket for the full picture. An account without a monitoring role cannot see other sessions’ state, timings or SQL; kbdiag lists those fields under redacted and answers UNKNOWN instead of OK, unless what it can see is already WARN or FAIL. Granting sys_monitor lifts this. On a standby, prepared transactions are not_applicable (run txn on the primary); this does not change the verdict.
Requirements
- KingbaseES V8R6 (tested on V008R006C009B0014)
- Linux amd64 or arm64
- repmgr is optional
Who holds the connections and which sessions are doing something; flag long idle-in-transaction ones.
One session: its full SQL, what it waits for, whom it blocks and which locks it holds.
Who blocks whom: the blockers first, then every session waiting for a lock, how long, and why.
Who holds back the vacuum horizon: open transactions, prepared (two-phase) ones, and the oldest of them.
What the working sessions are waiting on right now, biggest pile first.
What this instance is and whether its basics hold: role, replication, connections, database sizes, disk.
List replication slots: who consumes them, how much WAL they keep, and whether they hold back vacuum.
Where the space goes: filesystems, WAL size against its settings, database and tablespace sizes.
How far each database is from transaction ID wraparound, and the oldest tables of this one.
Which tables have the most dead tuples, whether autovacuum will clean them, and what is vacuuming now.
Whether WAL archiving works: settings, last success and failure, WAL waiting to be archived.
Which parameters are not at their default and where they are set; flags changes waiting for a restart.
Replication from this node: each standby’s lag and the synchronous settings on a primary; receive and replay on a standby.
repmgr’s view of the cluster (nodes, roles, upstreams, latest events), checked against this node.
The largest tables (heap, indexes, TOAST) and indexes of this database.
One table: size, rows, vacuum and analyze, freeze age, access, indexes.
Cumulative top SQL from sys_stat_statements; says so when statements are not being collected.
How far running VACUUM, CREATE INDEX, CLUSTER / VACUUM FULL and CHECKPOINT have got.
The last checkpoint, timed vs requested checkpoints, who writes dirty buffers, and the settings.
Where WAL is, how much sys_wal holds, and what keeps it: settings, slots, archiving.
Sequences of this database by how much of their range is used; FAIL when one is exhausted.