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.

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

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 2) 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.

Format 2 includes user/channel send policies and their versions. Format 1 and nonempty unregistered data directories are rejected before opening stores; this change does not migrate old data. Use matching server/CLI binaries and new or explicitly imported compatible directories. Do not change the marker to bypass the check. Preserve the marker in full directory backups; restoring an archive keeps the target node's creation identity. Older binaries cannot use this marker to guarantee safe rollback.

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.

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.

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.

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.

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.

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.