Your first check

Build the binary, install it on the database host, connect, and read the verdict and exit code.

Build kbdiag once, copy it to the KingbaseES host, and run status and sessions. Then decide what needs a closer look.

1. Prepare

A running KingbaseES V8R6 instance (tested on V008R006C009B0014).
Access to the kingbase OS user on the database host.
A machine with Go (the version in the repository’s go.mod) and git, to build the binary. It can be your laptop; the database host needs nothing but the binary.

2. Build and install

On the build machine:

git clone https://github.com/Kevin-wenyu/kbdiag.git
cd kbdiag
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 result is one static file with no runtime dependencies, so an offline host only needs the file copied over.

On the database host:

sudo -iu kingbase
chmod +x ~/kbdiag
~/kbdiag --version

3. Connect

By default kbdiag connects over the local socket /tmp/.s.KINGBASE.54321 to database test as user system, the way ksql test system does. Change the target with flags:

Flag	Default
`--host`	`/tmp` (socket directory); a host name or IP for TCP
`-p, --port`	`54321`
`-d, --dbname`	`test`
`-U, --user`	`system`
`--timeout`	`10s` per query

The password comes from PGPASSWORD or ~/.pgpass. If kbdiag cannot connect, it prints the error and exits with 69; check the port, socket directory and sys_hba.conf before anything else.

An account without a monitoring role cannot see other sessions’ state, timings or SQL. kbdiag lists those fields under redacted and answers UNKNOWN rather than OK; grant sys_monitor or use system for the full picture.

4. Run your first checks

~/kbdiag status
echo "exit code: $?"
~/kbdiag sessions
echo "exit code: $?"

Read $? right after the command; the next command replaces it. status tells you what the instance is and whether its basics hold: connections, replication, disk. sessions shows who holds the connections and which sessions are doing something, and warns about sessions left idle in transaction.

5. Read the verdict and exit code

The first line of every report carries the verdict, and the exit code says the same thing:

Exit code	Verdict	Next step
`0`	OK	Nothing crossed a threshold in this sample
`1`	WARN	Nothing is broken yet, but it will be if left alone: read each finding and run its `verify` command
`2`	FAIL	Same, now: the application is already affected
`3`	UNKNOWN	Something could not be collected or seen; check privileges and the `redacted` list
`64`	Usage error	Check the command and flags
`69`	Cannot connect	Check the connection first; nothing was looked at

A WARN or FAIL finding wins over UNKNOWN: if kbdiag found a problem in what it could see, it says so.

Read a real result line by line

6. Follow the evidence

You see	Next command	Look for
A lock wait	`~/kbdiag session <blocker pid>`	What the blocker is doing and how long its transaction has been open
Idle in transaction	`~/kbdiag session <pid>`	The locks it holds and whether it blocks anyone
An old or prepared transaction	`~/kbdiag txn`	The oldest xid and who holds it, transaction age, the prepared transaction’s gid and owner
Many sessions waiting	`~/kbdiag waits`	Which wait event they share
Connections used up	`~/kbdiag sessions`	The summary at the top: a pile-up by user, database, application or client
An inactive slot	`~/kbdiag status` on the slot’s downstream node	Whether it answers, whether `inst.upstream` is `streaming`, and whether `last_msg` keeps growing

Each finding already prints the right one of these as its verify line.

Done

You have built and installed kbdiag, connected to the right instance, run status and sessions, and know what their exit codes mean.

Explore capabilities · Look up command options

Read a real result

Real lab output of a WARN, line by line, in text and JSON.