maxminddb-golang

maxminddb-golang is a Go reader for the MaxMind DB binary file format, the format used by MaxMind’s GeoIP2 and GeoLite2 geolocation databases as well as compatible third-party databases from providers like DB-IP and IPinfo. It memory-maps the .mmdb file, walks its embedded binary search tree to resolve an IP address to a data pointer, and decodes the associated record into a Go struct, map, or any value using either reflection or a generated zero-reflection decoder.

Version 2 of the library modernizes the API around netip.Addr instead of net.IP, adds a CursorUnmarshaler interface and companion maxminddb-gen code-generation tool for allocation-light custom decoding, introduces range-over-func iterators (Networks(), NetworksWithin()) for streaming every network in a database, and adds integrity verification via Reader.Verify(). It is not an official MaxMind product, but is widely used as the de facto Go client for reading .mmdb files directly, as an alternative to shelling out to MaxMind’s own tooling.

What You Get

• A simple Open/OpenBytes + Lookup(ip).Decode(&struct) API for reading any .mmdb file, including GeoLite2, GeoIP2, DB-IP, and IPinfo databases
• A netip.Addr-based v2 API with DecodePath for pulling a single nested field (e.g. country.iso_code) without decoding the whole record
• Thread-safe, concurrent lookups against a single shared Reader instance backed by an mmap’d file
• Networks() and NetworksWithin() iterators for streaming every network/prefix in a database, e.g. for bulk export or reindexing
• The maxminddb-gen code-generation tool plus a hand-written CursorUnmarshaler interface for reflection-free, high-throughput decoding
• Built-in database integrity checking via Reader.Verify() and metadata helpers like Metadata.BuildTime()

Common Use Cases

• Resolving visitor IP addresses to country/city/region for request-time personalization or analytics in a Go web service
• Bulk-tagging log lines or datasets with geolocation, ASN, or connection-type data offline
• Building fraud-detection or access-control rules on top of GeoIP2 Anonymous IP or Enterprise databases
• Exporting or re-indexing an entire MaxMind DB file into another store by iterating all networks with Networks()
• High-throughput services that generate custom zero-reflection decoders with maxminddb-gen to avoid decode-path allocations

Under The Hood

Architecture The public surface in reader.go memory-maps the target .mmdb file (platform-specific mmap syscalls live in mmap_unix.go/mmap_windows.go, with a non-mmap mmap_stub.go fallback for js/wasip1/plan9/appengine build targets) and walks the format’s embedded binary search tree via traverseTree24/traverseTree28/traverseTree32 to resolve an IP to a data-section offset. Decoding is delegated to the internal internal/decoder package (data_decoder.go, reflection.go, cursor.go), which either reflects into the caller’s struct or, when a type implements mmdbdata.CursorUnmarshaler (defined in the public mmdbdata package), decodes without reflection using an opaque Cursor that lets nested decoders resume without rescanning. Error construction and context (“decoding a record for path X failed because Y”) is centralized in internal/mmdberrors, and traverse.go/verifier.go reuse the same tree-walk and decode paths to power full-database iteration and integrity verification, respectively. Because every operation funnels through the same tree-traversal and decode primitives, a change to the search-tree walk or the reflection engine has blast radius across lookups, iteration, and verification alike. Tech Stack The module targets Go 1.25 and keeps its dependency footprint deliberately small: golang.org/x/sys for the raw mmap/munmap syscalls, golang.org/x/tools and golang.org/x/mod/golang.org/x/sync (indirect) to power the maxminddb-gen code-generation tool, and stretchr/testify for test assertions only. There is no web framework, ORM, or database driver involved — this is a pure, low-dependency Go library distributed as a standard Go module (versioned /v2 for the major bump), with platform selection handled entirely through Go build tags rather than runtime branching. Code Quality Testing is extensive and layered: root-level suites (reader_test.go at over 1,800 lines, traverse_test.go, verifier_test.go, bad_data_test.go, result_test.go) sit alongside native Go fuzz tests (fuzz_test.go) that exercise the decoder against malformed database bytes, and each internal package (internal/decoder, mmdbdata) carries its own focused unit tests down to individual concerns like tag validation, map-key unmarshaling, and string caching. Errors are typed and wrapped through internal/mmdberrors rather than swallowed, and an extensive .golangci.yml enables a broad set of linters enforced in CI alongside a dedicated Go test workflow and CodeQL security scanning on every push and pull request. No test-coverage gaps are apparent from the file layout — decoding, tree traversal, and verification all have dedicated test files. API Design The common path is intentionally small: maxminddb.Open(path) then db.Lookup(ip).Decode(&record), with DecodePath available when only one nested field is needed and struct tags (`maxminddb:"iso_code"`) mapping directly onto database field names. A dedicated MIGRATION.md and extensive example_test.go/example_uint_test.go runnable examples smooth the v1-to-v2 transition and document usage patterns (basic lookup, custom struct decoding, network iteration, path-based decoding) directly as compilable code rather than prose alone. The escape hatch for high-throughput use — implementing CursorUnmarshaler by hand or generating it with maxminddb-gen — is opt-in and only needed once reflection-based decoding becomes a bottleneck, so newcomers are not forced to understand the code-generation story to get a first lookup working.