rdb: a Redis RDB parser in Go for memory analysis

What rdb is: an offline reader for the RDB file format

rdb is described as a Go implemented Redis RDB parser for secondary development and memory analysis, and the homepage of the project is a long Chinese-language article introducing the RDB file format itself, which tells you that the author intends the tool to be understood rather than merely used.

The abilities the README lists are the tool's real scope. It generates a memory report for an RDB file. It converts RDB files to JSON. It converts RDB files to the Redis Serialization Protocol, in other words to an AOF file. It finds the biggest N keys in an RDB file. It finds the hottest N keys by LFU frequency. It draws a flame graph to analyse which kind of keys occupied most memory. It lets you customise data usage, and it can generate an RDB file.

That list covers both directions. Reading a dump for analysis is the common case, and writing one is the capability that makes the parser usable as a library rather than only as a report tool.

The format support is explicit: RDB version 1 and above up to version 12, which corresponds to Redis 7.2. A parser that only handled one format version would be useless in practice, and this one spans a decade of Redis releases, which is the reason to prefer a dedicated parser over a quick script.

The code is credited in part to sripathikrishnan's redis-rdb-tools, and the project is listed in Awesome Go. It is released under the permissive Apache 2.0 licence named on the project page, and the repository also ships a Chinese README.

Installing and the shape of the command

If Go is installed, the README says the install is a single command:

go install github.com/hdt3213/rdb@latest

Homebrew users have a formula:

$ brew install rdb

And the third option is to download an executable binary from the releases page and put its path on the PATH environment variable.

Once installed, running rdb with no arguments prints the manual, and the options are worth reading as a description of the analysis surface. The command selector is -c, with the choices json, memory, aof, bigkey, hotkey, prefix and flamegraph. Output goes to a file with -o, and the number of results is set with -n, which applies to the bigkey, hotkey and prefix commands.

Two options are specific enough to be worth singling out. The -sep flag sets the separator used by the flame graph, where rdb will separate key by it, with a default value of a colon, and it supports multiple separators. The -prefix-sep flag is for the prefix analysis in flat-map mode, which uses separator-based analysis instead of a radix tree, and it also supports multiple separators.

That distinction is a real design decision rather than a naming quirk. The radix tree gives a hierarchical prefix view, and the flat-map mode is described as constant memory, which is what lets you run the prefix analysis on a dump with millions of keys without the tree becoming the bottleneck.

There are also filters. The -regex option filters keys with a regular expression, and -expire and -size filter by expiration time and by size respectively.

The analysis commands: memory, bigkey, hotkey and prefix

The examples in the README show the shape of each analysis, and the shapes are the point.

A memory report is one command:

  rdb -c memory -o memory.csv dump.rdb

The biggest keys take a count:

  rdb -c bigkey [-o dump.aof] [-n 10] dump.rdb

Note the optional -o on the bigkey command, which writes the selected keys out as an AOF file. That is a practical bridge between the two halves of the tool: you analyse a dump, then extract the interesting keys into a file you can load into a scratch instance.

The prefix analysis reports the number of keys and the memory size per prefix, with an optional maximum depth and an optional CSV output:

  rdb -c prefix [-n 10] [-max-depth 3] [-o prefix-report.csv] dump.rdb

and the constant-memory variant selects the separator-based analysis:

  rdb -c prefix [-n 10] [-max-depth 3] -prefix-sep : [-o prefix-report.csv] dump.rdb

The hottest keys are a different question. The README lists the command and, importantly, its precondition:

  rdb -c hotkey [-o hotkey.csv] [-n 50] dump.rdb

The hotkey command works by LFU frequency and requires the maxmemory-policy allkeys-lfu or volatile-lfu. That is a property of the data, not a bug: Redis only maintains the least-frequently-used counters when an LFU eviction policy is configured, so a dump taken under a different policy simply does not carry the information the command needs. It is a good example of a tool being honest about what it can and cannot see.

The filter options are equally specific. The -expire option accepts a range such as 1751731200~1751817600 to get keys expiring within that window, and understands the magic values now and inf, plus the special forms noexpire for keys without an expiration and anyexpire for all keys that have one. The -size option filters by size with units from B through EB, accepting ranges such as 1KB~1MB and understanding inf.

Flame graphs and the JSON output format

The flame graph command is the most unusual of the set, because it serves the result over the network rather than writing a file:

  rdb -c flamegraph [-port 16379] [-sep :] dump.rdb

The -port option is the listen port for the flame graph web service, so the analysis is served as a web page you open in a browser. The separator option applies here too, since the point of the visualisation is to attribute memory to key patterns, and the default is a colon, which is what most Redis key naming schemes use.

The JSON conversion is the other main output, and it is where the tool's data model is visible:

[
    {"db":0,"key":"hash","size":64,"type":"hash","hash":{"ca32mbn2k3tp41iu":"ca32mbn2k3tp41iu","mddbhxnzsbklyp8c":"mddbhxnzsbklyp8c"}},
    {"db":0,"key":"string","size":10,"type":"string","value":"aaaaaaa"},
    {"db":0,"key":"expiration","expiration":"2022-02-18T06:15:29.18+08:00","size":8,"type":"string","value":"zxcvb"},
    {"db":0,"key":"list","expiration":"2022-02-18T06:15:29.18+08:00","size":66,"type":"list","values":["7fbn7xhcnu","lmproj6c2e","e5lom29act","yy3ux925do"]},
    {"db":0,"key":"zset","expiration":"2022-02-18T06:15:29.18+08:00","size":57,"type":"zset","entries":[{"member":"zn4ejjo4ths63irg","score":1},{"member":"1ik4jifkg6olxf5n","score":2}]},
    {"db":0,"key":"set","expiration":"2022-02-18T06:15:29.18+08:00","size":39,"type":"set","members":["2hzm5rnmkmwb3zqd","tdje6bk22c6ddlrw"]}
]

Each record carries a database index, the key name, an estimated memory size in bytes, the Redis type, and optionally the expiration time in RFC3339 format and the encoding used internally by Redis. The JSON conversion is concurrent, and the -concurrent option changes the number of concurrent converters, four by default.

The global metadata of the file is available separately, through the -show-global-meta flag, which surfaces the Redis version, the creation time, the used memory and the functions defined in the dump. The README shows those as auxiliary records with a type of aux, and the functions entry carries the Lua source of the function library.

Inside the repository: parser, encoder, model and a Go 1.18 baseline

The top level listing describes the architecture. There is a core/ directory, a parser/, an encoder/, a model/ that holds the data types, a helper/, and several directories named after what they do: bytefmt/ for byte formatting, lzf/ for the LZF compression Redis uses, crc64jones/ for the checksum variant Redis employs, d3flame/ for the flame graph generation, and memprofiler/ for the memory accounting.

The lzf and crc64jones directories are the tell. Those are the two pieces of the RDB format that a partial implementation skips, because they are compression and integrity rather than structure, and their presence suggests a parser that reads the format as Redis writes it rather than an approximation of it.

The examples/ directory is split into decode/ and encode/, which mirrors the reading and writing halves of the tool, and the cases/ directory holds sample RDB files used for testing, which the README points at for people who want to try the JSON conversion against a known input.

The module declares Go 1.18 and a single direct dependency, github.com/bytedance/sonic at 1.15.0, which is a fast JSON library, with the rest of the requirements marked indirect. The test and build tooling is visible in the badges: a GitHub Actions build workflow, a Coveralls coverage status, a Go Report Card entry, and a .travis.yml in the tree. build.sh and cmd.go are the entry points, and tree.csv sits at the root as a data file.

Because the parser is a library as well as a command, the README's framing of it as being for secondary development is the practical point: a Go program can import github.com/hdt3213/rdb and walk the parsed model directly instead of shelling out to the CLI and parsing JSON.

Maintenance, and where rdb is the wrong tool

The release history shows a steady cadence with a recent gap. Version 1.3.0 came on 2025-08-18, v1.3.1 on 2025-12-31 and v1.3.2 on 2026-04-19, which is also the date of the last push to the repository. The project is not archived, but since that date there has been no new release, and a dump written by a newer Redis than 7.2 will carry an RDB version this parser does not claim to support.

That is the central practical limitation, and it is a format limitation rather than a bug. Redis 7.2 introduced RDB version 12, and each later release may add opcodes, so a dump from a newer server is exactly the case where you would most want an offline analyser and exactly the case this tool may not cover.

The first wrong use is inspecting a live server. rdb works on files, so for a running instance the redis-cli MEMORY USAGE and the server's own INFO output are the direct route, and this tool becomes useful once you have taken a snapshot.

The second wrong use is a deployment with an LFU policy assumption. If you expect hotkey to rank by popularity and the counters are not in the file, the answer will not be wrong so much as empty, and it is worth checking the eviction policy of the instance that produced the dump.

The third is a case where you only need to load a dump into a scratch server, since Redis itself can do that and does it faster than a parser and an AOF round trip.

The realistic alternative is redis-rdb-tools, the Python project this one credits, and the difference in approach is the one that matters for a Go shop: the Go implementation gives you a typed model you can import and traverse in the same process as your own tooling, with the JSON converter built on a fast JSON library, whereas the Python project is the one this tool credits as its inspiration.

Editorial conclusion

rdb earns its place for anyone who has a dump file and a question about it: the memory report, the prefix breakdown and the flame graph answer questions that redis-cli cannot answer on a stopped instance, and the JSON and AOF conversions make a dump portable to other tooling. It is the wrong choice if you need to inspect a live server's state, since it works on files rather than on a running instance, and it is the wrong choice if you need RDB versions beyond 12, since version 12 is where its support ends. Verify first which RDB version your dump was written with, that the LFU counters you want for hotkey are actually present because they require an LFU eviction policy, and that the Go version you build with matches the module's declared baseline.

Frequently asked questions

Official sources

1. HDT3213/rdb on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases