Go MaxMind DB Writer

This is a Go writer for the MaxMind DB format.

This is still a work in progress and does not support all of the features of the Perl writer. The API is subject to change.


See the examples folder for examples of how to use this library.

This software is Copyright (c) 2020 by MaxMind, Inc.

This is free software, licensed under the Apache License, Version 2.0 or the MIT License, at your option.

Expand ▾ Collapse ▴



Package mmdbwriter provides the tools to create and write MaxMind DB files.



This section is empty.


This section is empty.


This section is empty.


type Options

type Options struct {

	// BuildEpoch is the database build timestamp as a Unix epoch value. It
	// defaults to the epoch of when New was called.
	BuildEpoch int64

	// DatabaseType is a string that indicates the structure of each data record
	// associated with an IP address. The actual definition of these structures
	// is left up to the database creator.
	DatabaseType string

	// Description is a map where the key is a language code and the value is
	// the description of the database in that language.
	Description map[string]string

	// DisableIPv4Aliasing will disable the IPv4 aliasing in IPv6 trees. This
	// aliasing maps some IPv6 networks to the IPv4 network, e.g.,
	// ::ffff:0:0/96.
	DisableIPv4Aliasing bool

	// IncludeReservedNetworks will allow reserved networks to be added to the
	// database.
	// If this is false, any attempt to insert into these networks will result
	// in an error and inserting a network that contains a reserved network will
	// result in the reserved portion of the network being excluded. Reserved
	// networks that are globally routable to an individual device, such as
	// Teredo, may still be added.
	IncludeReservedNetworks bool

	// IPVersion indicates whether an IPv4 or IPv6 database should be built. An
	// IPv6 database supports both IPv4 and IPv6 lookups. The default value is
	// "6" for IPv6.
	IPVersion int

	// Languages is a slice of strings, each of which is a locale code. A given
	// record may contain data items that have been localized to some or all of
	// these locales. Records should not contain localized data for locales not
	// included in this slice.
	Languages []string

	// RecordSize indicates the number of bits in a record in the search tree.
	// The supported values are 24, 28, and 32. A smaller size will result in a
	// smaller database, but it will limit the maximum size of the database.
	// The default is 28.
	RecordSize int

Options holds configuration parameters for the writer

type Tree

type Tree struct {
	// contains filtered or unexported fields

Tree represents an MaxMind DB search tree.

func Load

func Load(path string, opts Options) (*Tree, error)

Load an existing database into the writer.

func New

func New(opts Options) (*Tree, error)

New creates a new Tree.

func (*Tree) Get

func (t *Tree) Get(ip net.IP) (*net.IPNet, mmdbtype.DataType)

Get the value for the given IP address from the tree. If the nil interface is returned, that means the tree does not have a value for the IP.

func (*Tree) Insert

func (t *Tree) Insert(network *net.IPNet, value mmdbtype.DataType) error

Insert a data value into the tree.

This is not safe to call from multiple threads.

func (*Tree) InsertFunc

func (t *Tree) InsertFunc(
	network *net.IPNet,
	inserter func(value mmdbtype.DataType) (mmdbtype.DataType, error),
) error

InsertFunc will insert the output of the function passed to it. The argument passed to the function is the existing value in the record. The function should return the mmdbtype.DataType to be inserted. In both cases, a nil value means an empty record.

You must never modify the argument passed to the function as the value may be shared with other records. If you want a copy of the mmdbtype.DataType to modify, call the Copy method on it, which will make a deep copy. This isn't done automatically before calling the function as not all functions will require the record to be copied and there is a non-trivial performance impact.

The function will be called multiple times per insert when the network has multiple preexisting records associated with it.

This is not safe to call from multiple threads.

func (*Tree) WriteTo

func (t *Tree) WriteTo(w io.Writer) (int64, error)

WriteTo writes the tree to the provided Writer.


Path Synopsis
examples/asn-writer asn-writer is an example of how to create an ASN MaxMind DB file from the GeoLite2 ASN CSVs.
inserter Package inserter provides some common inserter functions for mmdbwriter.InsertFunc.
mmdbtype Package mmdbtype provides types used within the MaxMind DB format.