maxminddb

• Added deserialize_any_with_raw_strings() for Serde-based format adapters
  to validate MMDB strings while constructing another runtime's native string
  type, avoiding duplicate UTF-8 validation without unsafe Rust. Adapters
  remain responsible for strict UTF-8 validation.
• Fixed network iteration on cyclic or over-deep corrupt search trees so it
  returns an error instead of looping indefinitely.
• Fixed decode_path() error rendering for extreme negative indexes and
  reduced path traversal header parsing.
• Removed decoder logging checks from hot deserialization paths.
• Fixed verify() to validate shared data-section pointer targets once, reject
  pointer cycles, invalid scalar encodings, and impossible container sizes.

• Added deserialize_any_with_raw_strings() for Serde-based format adapters to validate MMDB strings while constructing another runtime's native string type, avoiding duplicate UTF-8 validation without unsafe Rust. Adapters remain responsible for strict UTF-8 validation.
• Fixed network iteration on cyclic or over-deep corrupt search trees so it returns an error instead of looping indefinitely.
• Fixed decode_path() error rendering for extreme negative indexes and reduced path traversal header parsing.
• Removed decoder logging checks from hot deserialization paths.
• Fixed verify() to validate shared data-section pointer targets once, reject pointer cycles, invalid scalar encodings, and impossible container sizes.

• Breaking: Metadata::build_time() now returns
  Result<SystemTime, MaxMindDbError> instead of panicking on
  unrepresentable timestamps, and databases whose build_epoch cannot be
  represented as SystemTime are rejected as invalid during open and verify.
• Breaking: Reader::metadata is now private. Use Reader::metadata() to
  access validated metadata by shared reference.
• Breaking: Opening a database now rejects unsupported major format versions,
  unsupported IP versions, and zero-node search trees. Minor format versions
  are still accepted for forward compatibility.
• Fixed: within() and networks() now handle IPv6 databases without an
  IPv4 subtree without reading terminal data nodes as tree nodes or
  panicking while formatting low IPv6 networks.
• Fixed: Skipping ignored or unknown fields now enforces data-section
  bounds and the maximum nesting depth instead of accepting truncated
  values or overflowing the stack on deeply nested corrupt data.
• Internal: Added focused benchmarks for network iteration and serde
  unknown-field skipping, plus metadata build-time conversion, to guard
  performance-sensitive fixes.
• Documentation: Fixed intra-doc links so docs build with warnings denied,
  and added a CI check to keep them passing.

• Breaking: Metadata::build_time() now returns Result<SystemTime, MaxMindDbError> instead of panicking on unrepresentable timestamps, and databases whose build_epoch cannot be represented as SystemTime are rejected as invalid during open and verify.
• Breaking: Reader::metadata is now private. Use Reader::metadata() to access validated metadata by shared reference.
• Breaking: Opening a database now rejects unsupported major format versions, unsupported IP versions, and zero-node search trees. Minor format versions are still accepted for forward compatibility.
• Fixed: within() and networks() now handle IPv6 databases without an IPv4 subtree without reading terminal data nodes as tree nodes or panicking while formatting low IPv6 networks.
• Fixed: Skipping ignored or unknown fields now enforces data-section bounds and the maximum nesting depth instead of accepting truncated values or overflowing the stack on deeply nested corrupt data.
• Internal: Added focused benchmarks for network iteration and serde unknown-field skipping, plus metadata build-time conversion, to guard performance-sensitive fixes.
• Documentation: Fixed intra-doc links so docs build with warnings denied, and added a CI check to keep them passing.

• Fixed: Databases with an impossible declared search tree size are now
  rejected during open/verify instead of causing runaway allocation
  during validation.
• Fixed: within() now rejects IPv6 CIDRs on IPv4-only databases instead
  of yielding unrelated networks.
• Fixed: Verification now rejects truncated scalar/string payloads instead
  of skipping past them and reporting the database as valid.
• Fixed: LookupResult::network() now uses the reader's measured IPv4
  subtree depth instead of assuming it always begins at bit 96.

• Fixed: Databases with an impossible declared search tree size are now rejected during open/verify instead of causing runaway allocation during validation.
• Fixed: within() now rejects IPv6 CIDRs on IPv4-only databases instead of yielding unrelated networks.
• Fixed: Verification now rejects truncated scalar/string payloads instead of skipping past them and reporting the database as valid.
• Fixed: LookupResult::network() now uses the reader's measured IPv4 subtree depth instead of assuming it always begins at bit 96.

• Performance improvement: Faster search-tree traversal by dispatching
  on the database's record size to monomorphized node readers, replacing
  per-step branching on the record size.
• Performance improvement: Direct deserialization of scalars, sequences,
  maps, and structs through dedicated fast paths instead of routing
  through deserialize_any.
• Performance improvement: IPv4 and IPv6 lookups dispatch to dedicated
  paths, avoiding per-call address-kind checks on the hot path.
• Behavior change: Deserializing a database array into a tuple or
  tuple struct now returns a decoding error when the lengths do not
  match. Previously the mismatch was silently ignored.
• Fixed: A corrupt data pointer that would underflow during resolution
  now returns an InvalidDatabase error instead of panicking.

• Performance improvement: Faster search-tree traversal by dispatching on the database's record size to monomorphized node readers, replacing per-step branching on the record size.
• Performance improvement: Direct deserialization of scalars, sequences, maps, and structs through dedicated fast paths instead of routing through deserialize_any.
• Performance improvement: IPv4 and IPv6 lookups dispatch to dedicated paths, avoiding per-call address-kind checks on the hot path.
• Behavior change: Deserializing a database array into a tuple or tuple struct now returns a decoding error when the lengths do not match. Previously the mismatch was silently ignored.
• Fixed: A corrupt data pointer that would underflow during resolution now returns an InvalidDatabase error instead of panicking.

• Removed the release_max_level_info feature from the log dependency, as
  libraries should not set a global release log-level cap. Pull request by
  monosans. GitHub #110.

• Removed the release_max_level_info feature from the log dependency, as libraries should not set a global release log-level cap. Pull request by monosans. GitHub #110.

• Performance improvement: Faster lookups and record decoding in common paths,
  including control-byte header parsing and integer decoding.
• Performance improvement: Faster string decoding for ASCII-only values by
  using a dedicated ASCII fast path.
• Performance improvement: Reduced release-build overhead by compiling out
  debug/trace logging calls.
• Fixed: Truncated or corrupt data in control-byte headers now returns a
  decoding error instead of panicking.

• Performance improvement: Faster lookups and record decoding in common paths, including control-byte header parsing and integer decoding.
• Performance improvement: Faster string decoding for ASCII-only values by using a dedicated ASCII fast path.
• Performance improvement: Reduced release-build overhead by compiling out debug/trace logging calls.
• Fixed: Truncated or corrupt data in control-byte headers now returns a decoding error instead of panicking.

• Performance improvement: Skipped UTF-8 validation for map keys during
  deserialization. This significantly speeds up full record decoding by
  treating keys as raw bytes when matching against struct fields.
• Performance improvement: Optimized tree traversal by reducing bounds checks
  during node reading.

• Performance improvement: Skipped UTF-8 validation for map keys during deserialization. This significantly speeds up full record decoding by treating keys as raw bytes when matching against struct fields.
• Performance improvement: Optimized tree traversal by reducing bounds checks during node reading.

This release includes significant API changes. See UPGRADING.md
for migration guidance.

Breaking Changes

Lookup API

• lookup() now returns LookupResult instead of Option<T>. The new API
  enables lazy decoding - data is only deserialized when explicitly requested.
• lookup_prefix() has been removed. Use lookup(ip)?.network() instead.

Iteration API

• within() now requires a second WithinOptions parameter. Use
  Default::default() for the previous behavior.
• Within iterator now yields LookupResult instead of WithinItem<T>.

GeoIP2 Structs

• The names fields now use a Names struct instead of BTreeMap<&str, &str>.
  Access names directly via language fields (e.g., names.english).
• Nested struct fields (city, country, location, etc.) are now
  non-optional with Default, simplifying access patterns.
• Removed is_anonymous_proxy and is_satellite_provider from Traits.
  These fields are no longer present in MaxMind databases.

Error Types

• InvalidDatabase and Decoding variants now use structured fields instead
  of a single string. Pattern matching must be updated.
• New InvalidInput variant for user input errors (e.g., IPv6 lookup in
  IPv4-only database).

Memory Mapping

• Reader::open_mmap is now unsafe. The caller must ensure the database
  file is not modified or truncated while the Reader exists. This fixes a
  soundness issue. Reported by paolobarbolini. GitHub #86.

Added

• LookupResult type with lazy decoding support:
  • has_data() - Check if data exists for this IP
  • network() - Get the network containing the IP
  • offset() - Get data offset for caching/deduplication
  • decode() - Deserialize full record
  • decode_path() - Selectively decode specific fields by path
• PathElement enum and path! macro for navigating nested structures.
• WithinOptions to control network iteration behavior:
  • include_aliased_networks() - Include IPv4 via IPv6 aliases
  • include_networks_without_data() - Include networks without data records
  • skip_empty_values() - Skip empty maps/arrays
• networks() method for iterating over all networks in the database.
• verify() method for comprehensive database validation.
• Metadata::build_time() to convert build_epoch to SystemTime.
• PartialEq and Eq implementations for Metadata and WithinOptions.

Changed

• Error messages now include byte offsets when available.
• decode_path() errors include path context showing where navigation failed.
• Added recursion depth limit (512) matching libmaxminddb and Go reader.
• Serde deserializer improvements: size hints, is_human_readable() returns
  false, deserialize_ignored_any, and deserialize_enum support.
• MaxMindDbError is now #[non_exhaustive].

This release includes significant API changes. See UPGRADING.md for migration guidance.

Breaking Changes

Lookup API

• lookup() now returns LookupResult instead of Option<T>. The new API enables lazy decoding - data is only deserialized when explicitly requested.
• lookup_prefix() has been removed. Use lookup(ip)?.network() instead.

Iteration API

• within() now requires a second WithinOptions parameter. Use Default::default() for the previous behavior.
• Within iterator now yields LookupResult instead of WithinItem<T>.

GeoIP2 Structs

• The names fields now use a Names struct instead of BTreeMap<&str, &str>. Access names directly via language fields (e.g., names.english).
• Nested struct fields (city, country, location, etc.) are now non-optional with Default, simplifying access patterns.
• Removed is_anonymous_proxy and is_satellite_provider from Traits. These fields are no longer present in MaxMind databases.

Error Types

• InvalidDatabase and Decoding variants now use structured fields instead of a single string. Pattern matching must be updated.
• New InvalidInput variant for user input errors (e.g., IPv6 lookup in IPv4-only database).

Memory Mapping

• Reader::open_mmap is now unsafe. The caller must ensure the database file is not modified or truncated while the Reader exists. This fixes a soundness issue. Reported by paolobarbolini. GitHub #86.

Added

• LookupResult type with lazy decoding support:
  • has_data() - Check if data exists for this IP
  • network() - Get the network containing the IP
  • offset() - Get data offset for caching/deduplication
  • decode() - Deserialize full record
  • decode_path() - Selectively decode specific fields by path
• PathElement enum and path! macro for navigating nested structures.
• WithinOptions to control network iteration behavior:
  • include_aliased_networks() - Include IPv4 via IPv6 aliases
  • include_networks_without_data() - Include networks without data records
  • skip_empty_values() - Skip empty maps/arrays
• networks() method for iterating over all networks in the database.
• verify() method for comprehensive database validation.
• Metadata::build_time() to convert build_epoch to SystemTime.
• PartialEq and Eq implementations for Metadata and WithinOptions.

Changed

• Error messages now include byte offsets when available.
• decode_path() errors include path context showing where navigation failed.
• Added recursion depth limit (512) matching libmaxminddb and Go reader.
• Serde deserializer improvements: size hints, is_human_readable() returns false, deserialize_ignored_any, and deserialize_enum support.
• MaxMindDbError is now #[non_exhaustive].

• BREAKING CHANGE: The lookup and lookup_prefix methods now return
  Ok(None) or Ok((None, prefix_len)) respectively when an IP address is
  valid but not found in the database (or has no associated data record),
  instead of returning an Err(MaxMindDbError::AddressNotFoundError).
  Code previously matching on AddressNotFoundError must be updated to
  handle the Ok(None) / Ok((None, prefix_len)) variants.
• BREAKING CHANGE: The MaxMindDBError enum has been renamed
  MaxMindDbError and variants have been renamed and refactored. For
  example, IoError is now Io, InvalidDatabaseError is now
  InvalidDatabase, DecodingError is now Decoding,
  InvalidNetworkError is now InvalidNetwork. The MapError variant has
  been replaced by Mmap (under the mmap feature flag). Code explicitly
  matching on the old variant names must be updated.
• BREAKING CHANGE: MaxMindDbError no longer implements PartialEq.
  This is because underlying error types like std::io::Error (now
  wrapped by the Io and Mmap variants) do not implement PartialEq.
  Code comparing errors directly using == or assert_eq! must be
  updated, typically by using matches! or by matching on the error
  kind and potentially its contents.
• Refactored MaxMindDbError handling using the thiserror crate.
  Variants like Io, Mmap, and InvalidNetwork now directly wrap
  the underlying error types (std::io::Error, ipnetwork::IpNetworkError).
• Errors wrapping underlying types (Io, Mmap, InvalidNetwork) now
  correctly implement std::error::Error::source(), allowing inspection
  of the original cause.
• The Display implementation for MaxMindDbError has been refined to
  generally show only the specific error details, often including the
  message from the source error, rather than prefixing with the variant
  name.
• lookup_prefix now returns the prefix length of the entry even when the
  value is not found.
• Fixed an internal bounds checking error when resolving data pointers.
  The previous logic could cause a panic on a corrupt database.

• BREAKING CHANGE: The lookup and lookup_prefix methods now return Ok(None) or Ok((None, prefix_len)) respectively when an IP address is valid but not found in the database (or has no associated data record), instead of returning an Err(MaxMindDbError::AddressNotFoundError). Code previously matching on AddressNotFoundError must be updated to handle the Ok(None) / Ok((None, prefix_len)) variants.
• BREAKING CHANGE: The MaxMindDBError enum has been renamed MaxMindDbError and variants have been renamed and refactored. For example, IoError is now Io, InvalidDatabaseError is now InvalidDatabase, DecodingError is now Decoding, InvalidNetworkError is now InvalidNetwork. The MapError variant has been replaced by Mmap (under the mmap feature flag). Code explicitly matching on the old variant names must be updated.
• BREAKING CHANGE: MaxMindDbError no longer implements PartialEq. This is because underlying error types like std::io::Error (now wrapped by the Io and Mmap variants) do not implement PartialEq. Code comparing errors directly using == or assert_eq! must be updated, typically by using matches! or by matching on the error kind and potentially its contents.
• Refactored MaxMindDbError handling using the thiserror crate. Variants like Io, Mmap, and InvalidNetwork now directly wrap the underlying error types (std::io::Error, ipnetwork::IpNetworkError).
• Errors wrapping underlying types (Io, Mmap, InvalidNetwork) now correctly implement std::error::Error::source(), allowing inspection of the original cause.
• The Display implementation for MaxMindDbError has been refined to generally show only the specific error details, often including the message from the source error, rather than prefixing with the variant name.
• lookup_prefix now returns the prefix length of the entry even when the value is not found.
• Fixed an internal bounds checking error when resolving data pointers. The previous logic could cause a panic on a corrupt database.

• Serde will now skip serialization of the GeoIP2 struct fields
  when Option is none. Pull request by Stefan Sundin. GitHub #79.
• Serialize and Clone were added to the Metadata struct. Pull
  request by Stefan Sundin. GitHub #80.
• Added feature to use simdutf8 as a faster alternative when
  unsafe-str-decode is too risky. Pull request by Jakub Onderka.
  GitHub #88.
• Minor internal refactoring and performance improvements.

• Serde will now skip serialization of the GeoIP2 struct fields when Option is none. Pull request by Stefan Sundin. GitHub #79.
• Serialize and Clone were added to the Metadata struct. Pull request by Stefan Sundin. GitHub #80.
• Added feature to use simdutf8 as a faster alternative when unsafe-str-decode is too risky. Pull request by Jakub Onderka. GitHub #88.
• Minor internal refactoring and performance improvements.

• Added the is_anycast field to the Traits struct. Pull request by Skye. GitHub #73.

• Added lookup_prefix to return the prefix length for the network associated with the IP address. Pull request by Marek Vavruša. GitHub #26.

• A within method has been added to the reader to allow iterating over all records in the database. Pull request by Ross McFarland. Github #50.
• Database structs in maxminddb::geoip2 have been updated. Most noticeably, an Enterprise struct has been added and the model module has been replaced by city and country modules. Also, several missing fields have been added.
• Mmap is now re-exported for convenience. Pull request by zhuhaow. GitHub #54.
• Upgraded memmap2 dependency.

• Reduce the amount of code generated by shrinking generic methods. Pull request by Markus Westerlind. GitHub #49.

• Use try_into when decoding floating point values. Pull request by Sebastian Mayr. GitHub #47.

• Switch from memmap to memmap2. Pull request by Gleb Pomykalov. GitHub #46.

• The memchr crate is now used to improve the performance of finding the metadata start. Pull request by Markus Westerlind. GitHub #44.

• Correct handling of pointers in the database metadata section. This bug caused the latest GeoIP2 ISP database from MaxMind to fail to load with an InvalidDatabaseError due to an invalid data type. Reported by Marwes-Imperva. GitHub #45.

• Minor cleanup.

• Restore compatibility with targets that don't support 128-bit integers. Pull request by Filip. GitHub #41.

• Unsigned 128-bit integers are now decoded to a u128 rather than a [u8]. Pull request by moschroe. GitHub #40.

• This release includes major performance improvements and code cleanup. Pull request by Sebastian Mayr. GitHub #37.

• Remove crate options leftover from before Rust 1.0. In particular, this crate no longer specifies crate_type. This should allow you to compile it with panic = "abort". Reported by ye2020. GitHub #33.

• BREAKING CHANGE: All Strings in the geoip2 structs are not returned as references. This was done to provide a significant performance improvement when ownership is not needed. Pull request by Matthew Wynn. GitHub #31.
• A new opt-in feature, unsafe-str-decode, has been added that will skip UTF-8 validation when decoding strings. You should only use this when you trust that the MaxMind DB is valid and contains valid UTF-8 strings. This provides a modest performance improvement. Pull request by Matthew Wynn. GitHub #31.
• Many other internal improvements to reduce the number of allocations.

• Missing models for DensityIncome, Domain, and Asn were added and the missing is_in_european_union field was added to the Country model. Pull request by Sebastian Nadorp. GitHub #19.
• More details are now included in the Display implementation for MaxMindDBError. Pull request by Mike Cooper. GitHub #20.

• Reader::open has been removed. You should use Reader::open_readfile or Reader::open_mmap. Pull request by kpcyrd. GitHub #17 & #18.
• Reader::open_readfile no longer depends on unsafe. Pull request by kpcyrd. GitHub #17 & #18.

• An optional mmap cfg feature flag has been added. When set, open will use the memmap crate to memory map the database file rather than reading it from file. In addition to open, open_readfile and open_mmap are available. PR by moschroe. GitHub #16.
• Reader::open now takes an AsRef<Path>. Also, #16.
• Reader::from_buf allows using an existing buffer instead of specifying a database file. PR by kpcyrd. GitHub #15.

• Derive Serialize for GeoIP2 models. Pull request by Bryan Gilbert. GitHub #11.

• Update logger to 0.4 and env_logger to 0.5.

• Implement unimplemented deserialize methods.

• API CHANGE: Switch to Serde for deserialization. Data structures being deserialized to must implement the Deserialize trait. Pull request by Wesley Moore. GitHub #5.

• Update log to 0.3.7 and rustc-serialize to 0.3.23.

• Update rustc-serialize to 0.3.21.

• API CHANGE: lookup takes an IpAddr again instead of a SocketAddr. We previously switched to SocketAddr after IpAddr had been deprecated, but it has since been re-added.