mmdb-writer Library

Common errors

• ModuleNotFoundError: No module named 'mmdb_writer'

  cause The `mmdb-writer` package is not installed in the current Python environment or the environment is not activated.
  fix Install the package using `pip install mmdb-writer`.

• Permission denied: 'my_database.mmdb' (or similar OSError)

  cause The Python process does not have the necessary write permissions for the specified output directory or file path where it's attempting to create the `.mmdb` file.
  fix Ensure the user executing the script has write access to the target directory. Consider writing to a user-specific directory (e.g., `~/my_database.mmdb`) or a temporary directory (e.g., `/tmp/my_database.mmdb` on Unix-like systems) if permissions are restricted.

• ValueError: The MaxMind DB file is invalid or corrupt. (Observed when reading with a `maxminddb` reader)

  cause This error most commonly indicates that the database schema is inconsistent. `mmdb-writer` allows flexible data insertion, but if the data types for a given key path differ across various IP ranges (e.g., `data['key']` is a string for one IP and a dictionary for another), the resulting `.mmdb` file violates the MaxMind DB specification.
  fix Carefully review your input data for type consistency. For any specific key or nested key path (e.g., `data['location']['city']`), ensure that the associated data type (string, integer, map, list, etc.) is uniform across all records inserted into the database.

Warnings

• gotcha MaxMind DBs enforce strict data type consistency for any given key path across all records. If you insert `{'location': 'US'}` for one IP and later `{'location': {'country': 'US'}}` for another, official MaxMind readers might fail or produce unexpected results due to schema inconsistency.
  Fix: Ensure your data dictionary/list structure is consistent across all insertions for common keys. Design your data payload carefully so that a specific key path (e.g., `data['key1']['key2']`) always resolves to the same MaxMind DB data type (e.g., always a string, always a map, always an integer).
• gotcha When `ip_version` is set to 6 (to support both IPv4 and IPv6), it is highly recommended to set `store_ipv4_in_ipv6_format=True`. Failing to do so can result in larger database files and potentially slower lookups for mixed-format databases.
  Fix: Always pass `store_ipv4_in_ipv6_format=True` to the `MMDBWriter` constructor when `ip_version` is 6.
• gotcha Choosing an appropriate `record_size` is crucial. It determines the maximum size of data that can be associated with a single IP network. Values like 24, 28, or 32 are common, with higher values supporting larger data payloads but potentially increasing file size and lookup times slightly.
  Fix: Estimate the maximum size of your data dictionary per IP network. Use `record_size=24` for small data (~1.5KB), `record_size=28` for medium (~4.5KB), and `record_size=32` for larger payloads (~6KB). Refer to MaxMind DB documentation for more details on `record_size`.

Install

• pip install mmdb-writer Install mmdb-writer

Imports

• MMDBWriter

  from mmdb_writer import MMDBWriter

Quickstart

This quickstart demonstrates how to initialize `MMDBWriter`, insert IPv4 and IPv6 networks with various data types, and finalize the database creation. It highlights the use of `insert_network` for single entries and `insert_network_list` for multiple, sharing data. Key parameters like `ip_version`, `database_type`, and `record_size` are explained.

import os
from mmdb_writer import MMDBWriter
from netaddr import IPNetwork # Optional, strings also accepted by insert_network

# Define the output database file
output_file = 'my_ip_database.mmdb'

# Initialize the writer
# ip_version: 4 for IPv4 only, 6 for mixed IPv4/IPv6.
# database_type: An arbitrary string to identify your database.
# record_size: Affects max data size per IP entry (e.g., 24 for ~1.5KB, 32 for ~6KB).
writer = MMDBWriter(
    ip_version=6,
    database_type='Custom-Geo-Database',
    languages=['en', 'es'],
    description={'en': 'My custom IP lookup database', 'es': 'Mi base de datos IP personalizada'},
    record_size=24, # Recommended for many common use cases
    store_ipv4_in_ipv6_format=True # Recommended when ip_version is 6
)

# Insert individual networks with associated data
# Data can be a dictionary, list, string, int, float, or boolean.
writer.insert_network('1.1.1.0/24', {'country': 'US', 'city': 'Exampleville', 'latitude': 34.05, 'longitude': -118.25})
writer.insert_network('2.2.2.0/24', {'country': 'CA', 'isp': 'InternetCorp'})

# Insert a list of networks with the same data
# Can use strings directly or netaddr.IPNetwork objects.
networks_for_region = [
    '3.3.3.0/28',
    IPNetwork('3.3.3.16/28') # Both strings and IPNetwork objects are fine here
]
writer.insert_network_list(networks_for_region, {'country': 'UK', 'continent': 'Europe', 'timezone': 'Europe/London'})

# Insert an IPv6 network
writer.insert_network('2001:db8::/32', {'country': 'DE', 'organization': 'TechSolutions GmbH'})

# Close the writer to finalize and write the database file
writer.close(output_file)

print(f"MMDB database '{output_file}' created successfully.")

# Clean up the created file (uncomment if you want to remove it automatically)
# os.remove(output_file)