maxminddb

README

MaxMind DB Reader for Go

This is a Go reader for the MaxMind DB format. Although this can be used to read GeoLite2 and GeoIP2 databases, geoip2 provides a higher-level API for doing so.

This is not an official MaxMind API.

Installation

go get github.com/oschwald/maxminddb-golang

Usage

See GoDoc for documentation and examples.

Examples

See GoDoc or example_test.go for examples.

Contributing

Contributions welcome! Please fork the repository and open a pull request with your changes.

License

This is free software, licensed under the ISC License.

Documentation

Overview

Package maxminddb provides a reader for the MaxMind DB file format.

Index

• func IncludeAliasedNetworks(networks *networkOptions)
• type InvalidDatabaseError
  • func (e InvalidDatabaseError) Error() string
• type Metadata
• type NetworksOption
• type Reader
  • func FromBytes(buffer []byte) (*Reader, error)
  • func Open(file fs.File) (*Reader, error)
  • func (r *Reader) Close() error
  • func (r *Reader) Lookup(ip netip.Addr) Result
  • func (r *Reader) LookupOffset(offset uintptr) Result
  • func (r *Reader) Networks(options ...NetworksOption) iter.Seq[Result]
  • func (r *Reader) NetworksWithin(prefix netip.Prefix, options ...NetworksOption) iter.Seq[Result]
  • func (r *Reader) Verify() error
• type Result
  • func (r Result) Decode(v any) error
  • func (r Result) DecodePath(v any, path ...any) error
  • func (r Result) Err() error
  • func (r Result) Found() bool
  • func (r Result) Offset() uintptr
  • func (r Result) Prefix() netip.Prefix
• type UnmarshalTypeError
  • func (e UnmarshalTypeError) Error() string

Functions

func IncludeAliasedNetworks

func IncludeAliasedNetworks(networks *networkOptions)

IncludeAliasedNetworks is an option for Networks and NetworksWithin that makes them iterate over aliases of the IPv4 subtree in an IPv6 database, e.g., ::ffff:0:0/96, 2001::/32, and 2002::/16.

Types

type InvalidDatabaseError

type InvalidDatabaseError struct {
	// contains filtered or unexported fields
}

InvalidDatabaseError is returned when the database contains invalid data and cannot be parsed.

func (InvalidDatabaseError) Error

func (e InvalidDatabaseError) Error() string

type Metadata

type Metadata struct {
	Description              map[string]string `maxminddb:"description"`
	DatabaseType             string            `maxminddb:"database_type"`
	Languages                []string          `maxminddb:"languages"`
	BinaryFormatMajorVersion uint              `maxminddb:"binary_format_major_version"`
	BinaryFormatMinorVersion uint              `maxminddb:"binary_format_minor_version"`
	BuildEpoch               uint              `maxminddb:"build_epoch"`
	IPVersion                uint              `maxminddb:"ip_version"`
	NodeCount                uint              `maxminddb:"node_count"`
	RecordSize               uint              `maxminddb:"record_size"`
}

Metadata holds the metadata decoded from the MaxMind DB file. In particular it has the format version, the build time as Unix epoch time, the database type and description, the IP version supported, and a slice of the natural languages included.

type NetworksOption

type NetworksOption func(*networkOptions)

NetworksOption are options for Networks and NetworksWithin.

type Reader

type Reader struct {
	Metadata Metadata
	// contains filtered or unexported fields
}

Reader holds the data corresponding to the MaxMind DB file. Its only public field is Metadata, which contains the metadata from the MaxMind DB file.

All of the methods on Reader are thread-safe. The struct may be safely shared across goroutines.

func FromBytes

func FromBytes(buffer []byte) (*Reader, error)

FromBytes takes a byte slice corresponding to a MaxMind DB file and returns a Reader structure or an error.

func Open

func Open(file fs.File) (*Reader, error)

Open takes a string path to a MaxMind DB file and returns a Reader structure or an error. The database file is opened using a memory map on supported platforms. On platforms without memory map support, such as WebAssembly or Google App Engine, the database is loaded into memory. Use the Close method on the Reader object to return the resources to the system.

func (*Reader) Close

func (r *Reader) Close() error

Close returns the resources used by the database to the system.

func (*Reader) Lookup

func (r *Reader) Lookup(ip netip.Addr) Result

Lookup retrieves the database record for ip and returns Result, which can be used to decode the data..

func (*Reader) LookupOffset

func (r *Reader) LookupOffset(offset uintptr) Result

LookupOffset returns the Result for the specified offset. Note that netip.Prefix returned by Networks will be invalid when using LookupOffset.

func (*Reader) Networks

func (r *Reader) Networks(options ...NetworksOption) iter.Seq[Result]

Networks returns an iterator that can be used to traverse all networks in the database.

Please note that a MaxMind DB may map IPv4 networks into several locations in an IPv6 database. This iterator will only iterate over these once by default. To iterate over all the IPv4 network locations, use the IncludeAliasedNetworks option.

func (*Reader) NetworksWithin

func (r *Reader) NetworksWithin(prefix netip.Prefix, options ...NetworksOption) iter.Seq[Result]

NetworksWithin returns an iterator that can be used to traverse all networks in the database which are contained in a given prefix.

Please note that a MaxMind DB may map IPv4 networks into several locations in an IPv6 database. This iterator will iterate over all of these locations separately. To only iterate over the IPv4 networks once, use the SkipAliasedNetworks option.

If the provided prefix is contained within a network in the database, the iterator will iterate over exactly one network, the containing network.

func (*Reader) Verify

func (r *Reader) Verify() error

Verify checks that the database is valid. It validates the search tree, the data section, and the metadata section. This verifier is stricter than the specification and may return errors on databases that are readable.

type Result

type Result struct {
	// contains filtered or unexported fields
}

func (Result) Decode

func (r Result) Decode(v any) error

Decode unmarshals the data from the data section into the value pointed to by v. If v is nil or not a pointer, an error is returned. If the data in the database record cannot be stored in v because of type differences, an UnmarshalTypeError is returned. If the database is invalid or otherwise cannot be read, an InvalidDatabaseError is returned.

An error will also be returned if there was an error during the Reader.Lookup call.

If the Reader.Lookup call did not find a value for the IP address, no error will be returned and v will be unchanged.

func (Result) DecodePath

func (r Result) DecodePath(v any, path ...any) error

DecodePath unmarshals a value from data section into v, following the specified path.

The v parameter should be a pointer to the value where the decoded data will be stored. If v is nil or not a pointer, an error is returned. If the data in the database record cannot be stored in v because of type differences, an UnmarshalTypeError is returned.

The path is a variadic list of keys (strings) and/or indices (ints) that describe the nested structure to traverse in the data to reach the desired value.

For maps, string path elements are used as keys. For arrays, int path elements are used as indices.

If the path is empty, the entire data structure is decoded into v.

Returns an error if:

• the path is invalid
• the data cannot be decoded into the type of v
• v is not a pointer or the database record cannot be stored in v due to type mismatch
• the Result does not contain valid data

Example usage:

var city string
err := result.DecodePath(&city, "location", "city", "names", "en")

var geonameID int
err := result.DecodePath(&geonameID, "subdivisions", 0, "geoname_id")

func (Result) Err

func (r Result) Err() error

Err provides a way to check whether there was an error during the lookup without calling Result.Decode. If there was an error, it will also be returned from Result.Decode.

func (Result) Found

func (r Result) Found() bool

Found will return true if the IP was found in the search tree. It will return false if the IP was not found or if there was an error.

func (Result) Offset

func (r Result) Offset() uintptr

Offset returns the offset of the record in the database. This can be passed to (*Reader).LookupOffset. It can also be used as a unique identifier for the data record in the particular database to cache the data record across lookups. Note that while the offset uniquely identifies the data record, other data in Result may differ between lookups. The offset is only valid for the current database version. If you update the database file, you must invalidate any cache associated with the previous version.

func (Result) Prefix

func (r Result) Prefix() netip.Prefix

Prefix returns the netip.Prefix representing the network associated with the data record in the database.

type UnmarshalTypeError

type UnmarshalTypeError struct {
	Type  reflect.Type
	Value string
}

UnmarshalTypeError is returned when the value in the database cannot be assigned to the specified data type.

func (UnmarshalTypeError) Error

func (e UnmarshalTypeError) Error() string