maxminddb Rust Library

To use this library in your Rust project, add maxminddb to your Cargo.toml dependencies.

[dependencies]
maxminddb = "0.32"

The names fields in GeoIP2 structures have transitioned from a BTreeMap to a dedicated Names struct. This allows for direct access to common languages.

Before (0.26):

let name = city.city
    .as_ref()
    .and_then(|c| c.names.as_ref())
    .and_then(|n| n.get("en"));

After (0.27):

let name = city.city.names.english;

Supported language fields:

• german
• english
• spanish
• french
• japanese
• brazilian_portuguese
• russian
• simplified_chinese

Starting in version 0.27, the lookup() method returns a LookupResult instead of an Option<T>. This enables lazy decoding, allowing you to inspect the result without fully decoding the data.

Key features of LookupResult:

• result.has_data(): Check if data exists without decoding.
• result.network()?: Get the network for the IP (returns IpNetwork).
• result.decode::<T>()?: Decode the result into a specific type.
• result.decode_path(&[...])?: Decode only specific fields.

Before (0.26):

let city: Option<geoip2::City> = reader.lookup(ip)?;
if let Some(city) = city {
    println!("{:?}", city.city);
}

After (0.27):

let result = reader.lookup(ip)?;
if let Some(city) = result.decode::<geoip2::City>()? {
    println!("{:?}", city.city);
}

In version 0.29, the metadata field on the Reader struct was made private. You must now use the metadata() method to access validated metadata via a shared reference.

Before (0.28):

let database_type = &reader.metadata.database_type;

After (0.29):

let database_type = &reader.metadata().database_type;

In version 0.29, Metadata::build_time() now returns a Result<SystemTime, MaxMindDbError>. You must handle the potential error using the ? operator or similar error handling.

Before (0.28):

let build_time = reader.metadata.build_time();

After (0.29):

let build_time = reader.metadata().build_time()?;

Error variants in MaxMindDbError now use structured fields instead of simple strings. When matching errors, you must use struct patterns.

Before (0.26):

match error {
    MaxMindDbError::InvalidDatabase(msg) => {
        println!("Invalid database: {}", msg);
    }
    // ...
}

After (0.27):

match error {
    MaxMindDbError::InvalidDatabase { message, offset } => {
        println!("Invalid database: {} at {:?}", message, offset);
    }
    MaxMindDbError::InvalidInput { message } => {
        println!("Invalid input: {}", message);
    }
    // ...
}

Note: The InvalidInput variant is used for user errors, such as attempting to look up an IPv6 address in an IPv4-only database.

The lookup_prefix() method has been removed. To achieve the same result, use lookup() followed by network() on the returned LookupResult.

Before (0.26):

let (city, prefix_len) = reader.lookup_prefix(ip)?;

After (0.27):

let result = reader.lookup(ip)?;
let city = result.decode::<geoip2::City>()?;
let network = result.network()?;  // Returns IpNetwork with prefix

In version 0.27, nested struct fields are now non-optional and use Default instead of requiring .as_ref() chains. Note that leaf values (strings, numbers, bools) remain Option<T>.

Before (0.26):

let iso_code = city.country
    .as_ref()
    .and_then(|c| c.iso_code.as_ref());

let subdivisions = city.subdivisions
    .as_ref()
    .map(|v| v.iter())
    .into_iter()
    .flatten();

After (0.27):

let iso_code = city.country.iso_code;

for subdivision in &city.subdivisions {
    // ...
}

You can enable specific features in your Cargo.toml to optimize performance:

• mmap: Enables memory-mapped file access, which is recommended for long-running applications.
• unsafe-str-decode: Skips UTF-8 validation when deserializing trusted database strings into Rust str or String values. Use this with caution; cross-runtime format adapters should prefer deserialize_any_with_raw_strings() and validate strings during construction instead.

[dependencies]
maxminddb = { version = "0.32", features = ["mmap"] }