mmkv-go — a cgo-free, read-only MMKV reader in pure Go (zero-alloc, ~10–75× faster reads)

[catundercar]

mmkv-go is a small, cgo-free, read-only decoder for MMKV files, written in pure Go. It parses MMKV's on-disk format directly, so the read path never crosses the cgo boundary.

Why

In a Go service with one writer + many reader processes, every read through the official Go binding pays the cgo boundary cost (~65 ns/call here) plus a C→Go copy. For read-heavy, multi-process workloads that adds up. mmkv-go keeps writes on the official library and accelerates only the reads — entirely in Go, with no C toolchain needed on the reader side.

What it does

• Reads real MMKV files: plaintext, AES-CFB-128/256 encrypted, and key-expiration files.
• Transparent freshness, like MMKV C++ — it mmaps .crc and, on each read, compares the writer's change canary (crcDigest / actualSize / sequence), reloading under a shared flock only when something changed. Safe for single-writer (cgo, MMKV_MULTI_PROCESS) + multi-reader (pure Go).
• Zero-copy reads — GetBytes/GetString return views into the parsed buffer (0 alloc); *Copy variants when you need an independent slice/string.
• Namespaces, special-character mmapIDs, and a pure-Go consistent BackupOne.

Performance

Reading the same file in one process (Apple Silicon, arm64):

read	official cgo binding	mmkv-go (pure Go)
int32	~91 ns	~9 ns, 0 alloc
bytes 4 KB (copy)	~780 ns, 4 KB/op	~10 ns, 0 alloc
bytes 4 KB (zero-copy buffer)	~220 ns	~10 ns, 0 alloc
string	~150 ns	~10 ns, 0 alloc

The file is parsed once into a map at Open; each read is then a lock-free snapshot lookup. The gap is the cgo boundary tax + the Go-heap copy — both gone. (Relative ratios are the point; absolutes vary by machine.)

How it stays correct

It's a clean-room reader of MMKV's on-disk format, so the format is the contract — and CI guards it hard:

• A cgo.Get(k) == purego.Get(k) differential runs on files written by the official library, across MMKV's major release lines (v1.2.16 … v2.4.0) × {amd64, arm64} on native runners. Any format change that breaks the pure-Go reader turns the build red.
• AES decryption is checked against NIST CFB known-answer vectors; encryption + expiration are checked against the official library.
• A daily job watches Tencent/MMKV releases and opens a compatibility-tracking issue when a new version ships.

Scope & honesty

• Read-only by design — writes (and backup restore) stay on the official cgo library.
• POSIX (Linux/macOS), Go 1.21+.
• Best for read-heavy, long-lived readers (the one-time parse is amortized) — not for open-read-once-close.
• Returned views are valid until the next reload; use the *Copy variants otherwise.

Huge thanks to the MMKV team — it's a pleasure of a format to read. Repo: mmkv-go.

Feedback very welcome, especially on any on-disk format edge cases I may have missed.

[lingol]

That benchmark looks impressive. Good for you.