maxminddb-golang

Install the MaxMind DB reader for Go using go get:

go get github.com/oschwald/maxminddb-golang/v2

To optimize performance when using this library:

1. Reuse Reader instances: Lookups, decoding, and iteration are safe to run concurrently. Call Close only when all readers are finished.
2. Use specific structs: Avoid decoding into any; define structs with only the fields you need.
3. Implement Unmarshaler: Use the Unmarshaler interface for high-throughput requirements to minimize allocations.
4. Consider caching: Use Result.Offset() as a cache key to store and retrieve database records efficiently.

When upgrading to v2, update your import path to include the /v2 suffix.

// Old v1 import
import "github.com/oschwald/maxminddb-golang"

// New v2 import
import "github.com/oschwald/maxminddb-golang/v2"

For high-performance requirements, you can implement the mmdbdata.Unmarshaler interface on your custom types. This allows you to bypass reflection and use fine-grained decoding methods like d.ReadMap() or d.ReadString() directly.

type FastCity struct {
	CountryISO string
	CityName   string
}

func (c *FastCity) UnmarshalMaxMindDB(d *mmdbdata.Decoder) error {
	// Custom decoding logic using d.ReadMap(), d.ReadString(), etc.
	return nil
}

When iterating over networks using Networks or NetworksWithin, each step yields a Result object. A Result contains the following fields (accessible via methods or fields depending on the implementation):

• IP: The netip.Addr of the network.
• Offset: The uint offset in the database where the data starts.
• PrefixLen: The uint8 length of the network prefix.
• Err: An error if the iteration failed or if the specific network encountered an issue.
• Reader: A reference to the *Reader used for the iteration.

In v2, Reader.Networks() and Reader.NetworksWithin() yield iterators compatible with Go 1.23+ range syntax. This replaces the old Next()/Network() pattern. The Decode method on the yielded result handles errors, which are returned by the range loop.

Options for iteration (like SkipAliasedNetworks) now use an options pattern passed to the method.

for result := range reader.Networks() {
	var record struct {
		ConnectionType string `maxminddb:"connection_type"` 
	}

	if err := result.Decode(&record); err != nil {
		return err
	}
	fmt.Println(result.Prefix(), record.ConnectionType)
}

You can map database fields to Go struct fields using the maxminddb struct tag. This allows you to extract only the specific data you need from the database record.

type City struct {
	Country struct {
		ISOCode string `maxminddb:"iso_code"`
		Names   struct {
			English string `maxminddb:"en"`
			German  string `maxminddb:"de"`
		} `maxminddb:"names"`
	} `maxminddb:"country"`
}

var city City
err = db.Lookup(ip).Decode(&city)

If you only need a single value from a deep path in the database, use DecodePath. This avoids the need to define complex nested structs for simple lookups.

var countryCode string
err = db.Lookup(ip).DecodePath(&countryCode, "country", "iso_code")

var cityName string
err = db.Lookup(ip).DecodePath(&cityName, "city", "names", "en")

The Lookup method signature has changed. Instead of passing a destination pointer directly to Lookup, you now call Lookup with a netip.Addr and chain the .Decode() or .DecodePath() method to the returned Result object.

Migration steps:

1. Replace net.IP inputs with net/netip.Addr (use netip.ParseAddr or addr.AsSlice() for interoperability).
2. Change reader.Lookup(ip, &result) to reader.Lookup(addr).Decode(&result).

// v1 pattern
err := reader.Lookup(net.IP, &result)

// v2 pattern
err := reader.Lookup(netip.Addr).Decode(&result)

The Result.DecodePath method supports negative indices for arrays, allowing you to access elements from the end of a slice, similar to standard Go slice behavior.

Example: result.DecodePath(&value, "array", -1) fetches the last element of the array.