# User manual

LLMS index: [llms.txt](/kbdiag-docs/llms.txt)

---

Snapshot of the [kbdiag README](https://github.com/Kevin-wenyu/kbdiag#readme) at generation time.

Command pages:[`status`](/kbdiag-docs/docs/reference/status/) · [`sessions`](/kbdiag-docs/docs/reference/sessions/) · [`session`](/kbdiag-docs/docs/reference/session/) · [`locks`](/kbdiag-docs/docs/reference/locks/) · [`txn`](/kbdiag-docs/docs/reference/txn/) · [`waits`](/kbdiag-docs/docs/reference/waits/) · [`slots`](/kbdiag-docs/docs/reference/slots/) · [`space`](/kbdiag-docs/docs/reference/space/) · [`freeze`](/kbdiag-docs/docs/reference/freeze/) · [`vacuum`](/kbdiag-docs/docs/reference/vacuum/) · [`archive`](/kbdiag-docs/docs/reference/archive/) · [`params`](/kbdiag-docs/docs/reference/params/) · [`repl`](/kbdiag-docs/docs/reference/repl/) · [`cluster`](/kbdiag-docs/docs/reference/cluster/) · [`top-objects`](/kbdiag-docs/docs/reference/top-objects/) · [`table`](/kbdiag-docs/docs/reference/table/) · [`top`](/kbdiag-docs/docs/reference/top/) · [`progress`](/kbdiag-docs/docs/reference/progress/) · [`checkpoint`](/kbdiag-docs/docs/reference/checkpoint/) · [`wal`](/kbdiag-docs/docs/reference/wal/) · [`seq`](/kbdiag-docs/docs/reference/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`](https://github.com/Kevin-wenyu/kbdiag/releases/tag/v1.0.0) if you need it.

## Install

Build a static Linux binary (Go from `go.mod`), then copy it to the database host:

```bash
GOOS=linux GOARCH=amd64 CGO_ENABLED=0 go build -trimpath -ldflags "-s -w -X main.version=$(git describe --tags --match 'v2*' --always)" -o kbdiag ./cmd/kbdiag
scp kbdiag kingbase@db-host:~/kbdiag
```

Use `GOARCH=arm64` for ARM hosts. The binary has no runtime dependencies.

## Quick start

```bash
sudo -iu kingbase        # run as the database OS user
~/kbdiag status          # what is this instance
~/kbdiag sessions        # who is connected, who is idle in transaction
~/kbdiag locks           # who waits for a lock, and who blocks them
echo $?                  # 0 OK, 1 WARN, 2 FAIL, 3 UNKNOWN
```

## 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

```text
locks  WARN  (KingbaseES V008R006C009B0014, primary, system@local, 2026-09-26T19:41:41+08:00)

[WARN] lock.waiting  session 803890 has waited 14s for AccessShareLock on public.kbdiag_inj_lock, blocked by 803881
  verify: kbdiag session 803881  # what the blocking session is doing

blockers: 1
  pid     blocks  holds
  803881  1       public.kbdiag_inj_lock AccessExclusiveLock

waiting: 1
  pid     object                  wants            waited  blocked by
  803890  public.kbdiag_inj_lock  AccessShareLock  14s     803881
```

- First line: command, verdict, and context (version, role, user@location, collection time).
- Findings: an id, a symptom, and a `verify` or `fix` next step.
- Data: laid out for reading, sizes and durations in readable units; `-` is null, `?` is hidden from this account. `--json` gives 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

---

Section pages:

- [sessions: list sessions](/kbdiag-docs/docs/reference/sessions/): Who holds the connections and which sessions are doing something; flag long idle-in-transaction ones.
- [session: one session](/kbdiag-docs/docs/reference/session/): One session: its full SQL, what it waits for, whom it blocks and which locks it holds.
- [locks: lock waits](/kbdiag-docs/docs/reference/locks/): Who blocks whom: the blockers first, then every session waiting for a lock, how long, and why.
- [txn: transactions](/kbdiag-docs/docs/reference/txn/): Who holds back the vacuum horizon: open transactions, prepared (two-phase) ones, and the oldest of them.
- [waits: wait events](/kbdiag-docs/docs/reference/waits/): What the working sessions are waiting on right now, biggest pile first.
- [status: instance overview](/kbdiag-docs/docs/reference/status/): What this instance is and whether its basics hold: role, replication, connections, database sizes, disk.
- [slots: replication slots](/kbdiag-docs/docs/reference/slots/): List replication slots: who consumes them, how much WAL they keep, and whether they hold back vacuum.
- [space: disk, WAL, databases](/kbdiag-docs/docs/reference/space/): Where the space goes: filesystems, WAL size against its settings, database and tablespace sizes.
- [freeze: wraparound distance](/kbdiag-docs/docs/reference/freeze/): How far each database is from transaction ID wraparound, and the oldest tables of this one.
- [vacuum: dead tuples and autovacuum](/kbdiag-docs/docs/reference/vacuum/): Which tables have the most dead tuples, whether autovacuum will clean them, and what is vacuuming now.
- [archive: WAL archiving](/kbdiag-docs/docs/reference/archive/): Whether WAL archiving works: settings, last success and failure, WAL waiting to be archived.
- [params: changed parameters](/kbdiag-docs/docs/reference/params/): Which parameters are not at their default and where they are set; flags changes waiting for a restart.
- [repl: replication from this node](/kbdiag-docs/docs/reference/repl/): Replication from this node: each standby's lag and the synchronous settings on a primary; receive and replay on a standby.
- [cluster: repmgr's view](/kbdiag-docs/docs/reference/cluster/): repmgr's view of the cluster (nodes, roles, upstreams, latest events), checked against this node.
- [top-objects: largest tables and indexes](/kbdiag-docs/docs/reference/top-objects/): The largest tables (heap, indexes, TOAST) and indexes of this database.
- [table: one table](/kbdiag-docs/docs/reference/table/): One table: size, rows, vacuum and analyze, freeze age, access, indexes.
- [top: cumulative top SQL](/kbdiag-docs/docs/reference/top/): Cumulative top SQL from sys_stat_statements; says so when statements are not being collected.
- [progress: long operations](/kbdiag-docs/docs/reference/progress/): How far running VACUUM, CREATE INDEX, CLUSTER / VACUUM FULL and CHECKPOINT have got.
- [checkpoint: checkpoint activity](/kbdiag-docs/docs/reference/checkpoint/): The last checkpoint, timed vs requested checkpoints, who writes dirty buffers, and the settings.
- [wal: WAL position and what keeps it](/kbdiag-docs/docs/reference/wal/): Where WAL is, how much sys_wal holds, and what keeps it: settings, slots, archiving.
- [seq: sequences](/kbdiag-docs/docs/reference/seq/): Sequences of this database by how much of their range is used; FAIL when one is exhausted.