wkcli db

wkcli db is a local offline tool for one WuKongIM node data directory. It never connects to cluster nodes and does not read global Controller, Raft, or runtime state. Begin with read-only inspection; only import writes WKDB storage.

Install wkcli before using these examples. Database flags belong after wkcli db and before the operation.

Operation classes

Global flags must precede the command; command-specific flags follow it.

Inspect the data version

This feature is available starting with v3.0.0-beta.13. Use matching server and tool versions.

wkcli db --data-dir ./node-1 info
wkcli db --data-dir ./node-1 --format json info
wkcli db --config ./wukongim.toml info

Every fresh empty node directory receives DATA-FORMAT.json. Migration targets receive it too, with the migration tool as their creator. format (currently wukongim-v3) and format_version (currently 1) identify data compatibility. created_by records the program, version, commit, and build source; created_at records creation time. Ordinary software upgrades and repeated imports preserve these fields.

info opens no database or database lock, creates no directory, and writes nothing. It can run while a node is online. Missing paths and corrupt markers fail; a successful read is not verification of business data. Supply the node root or config, without --meta-path, --message-path, or --hash-slot-count.

Existing nonempty directories, including external Controller state, are not automatically registered and retain existing storage checks. Preserve the file in full directory backups, snapshots, and migration distribution. Logical bundles and cluster backups use their own format versions; restoration retains the target node's creation record. Older servers unaware of this marker cannot guarantee safe rollback based on it.

Locate storage

wkcli db --data-dir ./node-1 --hash-slot-count 256 query "show tables"
wkcli db --config ./wukongim.toml query "select * from meta.user limit 20"

• --data-dir derives slotmeta and messages from the current node layout.
• --meta-path and --message-path explicitly override those paths.
• --config reads paths and hash-slot count from TOML; WK_ environment variables still override file values.
• --hash-slot-count must match the cluster that produced the data. WuKongIM uses 256 physical hash slots.

Record node ID, cluster ID, copy/snapshot time, server version, and directory checksums so the wrong targets are not compared.

Read-only queries

wkcli db --data-dir ./node-1 --hash-slot-count 256 \
  query "select * from meta.user where uid='u1'"

wkcli db --data-dir ./node-1 \
  query "select * from message.channels limit 20"

wkcli db --data-dir ./node-1 \
  query "select * from message.message where channel_key='g1:2' limit 50"

With a partition key such as uid or channel_id, the tool derives its hash slot. Without a partition key it performs a bounded scan over this node's files. limit is the total result size, not a per-slot limit. Continue a large result with the returned cursor; offset is unsupported:

wkcli db --data-dir ./node-1 --hash-slot-count 256 \
  query "select * from meta.user limit 100 cursor '<next_cursor>'"

Select --format table|json|jsonl. JSONL emits data rows followed by a final stats object containing has_more and next_cursor.

Export a bundle

wkcli db --data-dir ./node-1 --hash-slot-count 256 \
  export --output ./wkdb-dump

export opens the source read-only and writes only the output directory. WKDB Import Bundle v1 contains a manifest plus JSONL files for supported user, device, Channel, subscriber, ordinary membership, CMD membership, latest-sequence, and message data, with file row counts and SHA-256 digests.

It does not aggregate other nodes, create an online-consistent snapshot, export increments, include Controller/Raft/runtime state, or produce a Manager backup archive. Before adding --overwrite, resolve and verify the existing output path.

Import a bundle

First validate without opening a writable target:

wkcli db --data-dir ./node-new --hash-slot-count 256 \
  import --input ./wkdb-dump --dry-run

After validation, use a new or deliberately empty offline target:

wkcli db --data-dir ./node-new --hash-slot-count 256 \
  import --input ./wkdb-dump --require-empty

import is the sole command that writes WKDB storage. It does not join a cluster, migrate Controller or Raft state, or turn a one-node bundle into a complete cluster. Preserve the target, confirm bundle version and hash-slot count, use --require-empty to avoid accidental merging, and run an offline diff before starting any node.

Compare two offline directories

wkcli db --hash-slot-count 256 diff \
  --source-data-dir ./node-old \
  --target-data-dir ./node-new

wkcli db --hash-slot-count 256 diff \
  --source-data-dir ./node-old \
  --target-data-dir ./node-new \
  --mode full

The default summary mode compares rows and payload checksums; full also hashes message payload bytes. Equal data exits 0 and a verified mismatch exits 2. Retain stderr with the exit code so a configuration or read error is not mistaken for a data mismatch.

Cluster-restore boundary

A wkcli db bundle is for node-local offline inspection and controlled transfer; it does not replace Manager Backup & Restore. Cluster restore must also verify cluster identity, archives, tasks, and all 256 physical hash slots, then use the maintenance-mode atomic switch or rollback procedure.