Skip to main content

Crate mmdb_writer

Crate mmdb_writer 

Source
Expand description

§mmdb-writer

crates.io docs.rs CI MSRV License

Write MaxMind DB (.mmdb) files in pure, safe Rust.

Build an IP-address-to-data lookup database — the same on-disk format used by GeoIP2 / GeoLite2 — that any MaxMind-compatible reader can consume: the maxminddb crate, mmdbinspect, the official Go and Python readers, and so on.

#![forbid(unsafe_code)]. The only required dependencies are ipnet, thiserror, and bon.

§Quickstart

[dependencies]
mmdb-writer = "0.1"
use ipnet::IpNet;
use mmdb_writer::Writer;
use serde::Serialize;

#[derive(Serialize)]
struct City {
    names: std::collections::BTreeMap<String, String>,
    geoname_id: u32,
}

let mut writer = Writer::new("My-City-DB");

let record = City {
    names: [("en".to_string(), "Example City".to_string())].into(),
    geoname_id: 123,
};
writer.insert("192.0.2.0/24".parse::<IpNet>()?, &record)?;

let bytes: Vec<u8> = writer.to_bytes()?;
std::fs::write("city.mmdb", bytes)?;

Read it back with the maxminddb crate to confirm:

ⓘ
let reader = maxminddb::Reader::open_readfile("city.mmdb")?;
let city: City = reader.lookup("192.0.2.42".parse()?)?.unwrap();
assert_eq!(city.geoname_id, 123);

§Features

FeatureDefaultDescription
serde✅Writer::insert accepts any serde::Serialize; Value is Serialize/Deserialize.
load—Writer::load reads an existing .mmdb (via maxminddb) to extend it. Implies serde.

Disable defaults to build the value-only API with no serde dependency:

mmdb-writer = { version = "0.1", default-features = false }
use ipnet::IpNet;
use mmdb_writer::{Value, Writer};

let mut writer = Writer::new("My-ASN-DB");
let value = Value::map([("autonomous_system_number", Value::from(64_512_u32))]);
writer.insert_value("192.0.2.0/24".parse::<IpNet>()?, value)?;
let _bytes = writer.to_bytes()?;

§Capabilities

  • IPv4 and IPv6 databases (ip_version 4 or 6), with IPv4 automatically reachable from the IPv4-mapped, 6to4, and Teredo ranges via tree aliasing.
  • All MMDB data types: map, array, string, bytes, double, float, boolean, and unsigned integers up to 128-bit plus signed 32-bit.
  • Insert strategies: last-write-wins replace (default), custom read-modify-write via insert_with, and top-level / deep map merges.
  • insert_range for arbitrary start–end IP ranges (decomposed into CIDR blocks).
  • Automatic record sizing (24 / 28 / 32-bit) and pointer-based data deduplication for compact output, with a deterministic byte layout for reproducible builds.

§How this compares

maxminddb-writer is the other Rust writer; it is minimal and low-level. mmdb-writer aims for parity with the official Go mmdbwriter: a typed Value model, insert strategies, IPv4/IPv6 support, reserved-network handling, and thorough documentation.

§Minimum supported Rust version

The MSRV is 1.85 (required by edition 2024). Raising it is a minor-version change.

§License

Licensed under either of

at your option.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Re-exports§

pub use ipnet;

Structs§

Writer
Builds a MaxMind DB and serializes it.
WriterBuilder
Use builder syntax to set the inputs and finish with build().

Enums§

Error
Errors returned while building or writing a database.
IpVersion
Which IP version a database indexes.
Ipv4Aliasing
Whether to install IPv4 aliases in an IpVersion::V6 database.
MergeStrategy
How Writer::insert_merged combines a new value with the value already covering a network.
MetadataPointers
Whether the metadata section may use data-section pointers.
RecordSize
Width, in bits, of a single child record inside a search-tree node.
ReservedNetworks
Whether reserved (private, documentation, multicast, …) networks are writable.
Value
One MMDB data-section value.

Type Aliases§

Result
A convenient result type alias for fallible operations in this crate.