czdb 0.2.0

A pure Rust library for parsing CZDB-format IP databases.
Documentation

CZDB Database Library

A Rust library for parsing and searching CZDB-format IP geolocation databases.

Highlights

  • Three modes: disk (CzdbDisk), mmap (CzdbMmap), and in-memory (CzdbMemory).
  • Disk mode prioritizes low memory, mmap balances memory and speed, memory mode is fastest.
  • IPv4/IPv6 supported; aligned with official reference behaviors.
  • Batch search APIs for small and large batches.

Modes

  • Disk (CzdbDisk): lowest memory, higher latency; good for low QPS or constrained environments.
  • Mmap (CzdbMmap, feature mmap): OS page cache, good throughput with low memory footprint.
  • Memory (CzdbMemory): prebuilt index + string pool, best latency/QPS; highest memory usage.

Quick Start

Disk mode

use czdb::CzdbDisk;
use std::net::IpAddr;

let mut db = CzdbDisk::open("path/to/your.czdb", "your_base64_key")?;
let ip: IpAddr = "8.8.8.8".parse().unwrap();
let res = db.search(ip);

Mmap mode

use czdb::CzdbMmap;
use std::net::IpAddr;

let db = CzdbMmap::open("path/to/your.czdb", "your_base64_key")?;
let ip: IpAddr = "8.8.8.8".parse().unwrap();
let res = db.search(ip);

Memory mode

use czdb::CzdbMemory;
use std::net::IpAddr;

let db = CzdbMemory::open("path/to/your.czdb", "your_base64_key")?;
let ip: IpAddr = "8.8.8.8".parse().unwrap();
let res = db.search(ip);

Batch Searches

Small batches (binary search)

use czdb::CzdbMemory;
use std::net::IpAddr;

let db = CzdbMemory::open("path/to/your.czdb", "your_base64_key")?;
let ips: Vec<IpAddr> = vec!["1.1.1.1".parse().unwrap(), "8.8.8.8".parse().unwrap()];
let res = db.search_many(&ips);

Large batches (sort + scan)

use czdb::CzdbMemory;
use std::net::IpAddr;

let db = CzdbMemory::open("path/to/your.czdb", "your_base64_key")?;
let ips: Vec<IpAddr> = (0..10000)
    .map(|i| IpAddr::from([1, 1, 1, (i % 255) as u8]))
    .collect();
let res = db.search_many_scan(&ips);

Features

  • mmap: enable CzdbMmap

Docs

  • docs.rs builds with all features enabled by default.
  • Local build: cargo doc --all-features.

Notes

CZDB 数据库解析库

这是一个用于解析与查询 CZDB 格式 IP 地理位置数据库的 Rust 库。

核心特性

  • 三种模式：磁盘（CzdbDisk）、mmap（CzdbMmap）、内存（CzdbMemory）。
  • 磁盘模式最省内存，mmap 兼顾内存与速度，内存模式速度最高。
  • 支持 IPv4/IPv6，并对齐官方参考实现行为。
  • 提供小批量与大批量查询 API。

模式对比

  • 磁盘模式（CzdbDisk）：内存占用最低，延迟较高；适合低 QPS。
  • mmap 模式（CzdbMmap，mmap feature）：利用系统页缓存，吞吐较好且内存占用低。
  • 内存模式（CzdbMemory）：预构建索引 + 字符串池，延迟最低；内存占用最高。

快速开始

磁盘模式

use czdb::CzdbDisk;
use std::net::IpAddr;

let mut db = CzdbDisk::open("path/to/your.czdb", "your_base64_key")?;
let ip: IpAddr = "8.8.8.8".parse().unwrap();
let res = db.search(ip);

mmap 模式

use czdb::CzdbMmap;
use std::net::IpAddr;

let db = CzdbMmap::open("path/to/your.czdb", "your_base64_key")?;
let ip: IpAddr = "8.8.8.8".parse().unwrap();
let res = db.search(ip);

内存模式

use czdb::CzdbMemory;
use std::net::IpAddr;

let db = CzdbMemory::open("path/to/your.czdb", "your_base64_key")?;
let ip: IpAddr = "8.8.8.8".parse().unwrap();
let res = db.search(ip);

批量查询

小批量（二分）

use czdb::CzdbMemory;
use std::net::IpAddr;

let db = CzdbMemory::open("path/to/your.czdb", "your_base64_key")?;
let ips: Vec<IpAddr> = vec!["1.1.1.1".parse().unwrap(), "8.8.8.8".parse().unwrap()];
let res = db.search_many(&ips);

大批量（排序 + 扫描）

use czdb::CzdbMemory;
use std::net::IpAddr;

let db = CzdbMemory::open("path/to/your.czdb", "your_base64_key")?;
let ips: Vec<IpAddr> = (0..10000)
    .map(|i| IpAddr::from([1, 1, 1, (i % 255) as u8]))
    .collect();
let res = db.search_many_scan(&ips);

功能开关

  • mmap：启用 CzdbMmap

文档

  • docs.rs 默认开启全部 feature。
  • 本地构建：cargo doc --all-features。

注意事项