Crate maxminddb 

MaxMind DB Reader

This library reads the MaxMind DB format, including the GeoIP2 and GeoLite2 databases.

Features

This crate provides several optional features for performance and functionality:

• mmap (default: disabled): Enable memory-mapped file access for better performance in long-running applications
• unsafe-str-decode (default: disabled): Skip UTF-8 validation when deserializing trusted database strings into Rust str or String values. Cross-runtime format adapters should prefer deserialize_any_with_raw_strings() and validate while constructing the target runtime’s string type.

Database Compatibility

This library supports all MaxMind DB format databases:

• GeoIP2 databases (City, Country, Enterprise, ISP, etc.)
• GeoLite2 databases (free versions)
• Custom MaxMind DB format databases

Thread Safety

Reader<S> is Send when S is Send, and Sync when S is Sync. Reader<Vec<u8>>, returned by Reader::open_readfile, implements both:

fn assert_send_sync<T: Send + Sync>() {}
assert_send_sync::<maxminddb::Reader<Vec<u8>>>();

Custom sources passed to Reader::from_source determine these traits. For example, a source of type std::rc::Rc<[u8]> makes the reader neither Send nor Sync.

Quick Start

use maxminddb::{Reader, geoip2};
use std::net::IpAddr;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Open database file
    let reader = Reader::open_readfile("/path/to/GeoIP2-City.mmdb")?;

    // Look up an IP address
    let ip: IpAddr = "89.160.20.128".parse()?;
    let result = reader.lookup(ip)?;

    if let Some(city) = result.decode::<geoip2::City>()? {
        // Access nested structs directly - no Option unwrapping needed
        println!("Country: {}", city.country.iso_code.unwrap_or("Unknown"));
    }

    Ok(())
}

Selective Field Access

Use decode_path to extract specific fields without deserializing the entire record:

use maxminddb::{path, Reader};
use std::net::IpAddr;

let reader = Reader::open_readfile("test-data/test-data/GeoIP2-City-Test.mmdb").unwrap();
let ip: IpAddr = "89.160.20.128".parse().unwrap();

let result = reader.lookup(ip).unwrap();
let country_code: Option<String> = result.decode_path(&path!["country", "iso_code"]).unwrap();

println!("Country: {:?}", country_code);

Modules

geoip2

GeoIP2 and GeoLite2 database record structures

Macros

path

Creates a path for use with LookupResult::decode_path().

Structs

LookupResult

The result of looking up an IP address in a MaxMind DB.

Metadata

Metadata about the MaxMind DB file.

Mmap

A handle to an immutable memory mapped buffer.

Reader

A reader for the MaxMind DB format. The lifetime 'data is tied to the lifetime of the underlying buffer holding the contents of the database file.

Within

Iterator over database networks matching a CIDR range.

WithinOptions

Options for network iteration.

Enums

MaxMindDbError

Error returned by MaxMind DB operations.

PathElement

A path element for navigating into nested data structures.

Functions

deserialize_any_with_raw_strings

Deserializes any MaxMind DB value while exposing strings as raw bytes.