ip2region

The library requires an .xdb file to function. You can either:

1. Download pre-generated files from the official repository.
2. Generate your own using the maker tool.

To query IP addresses, you must match the version to the specific .xdb file being used. Using a version that does not match the db_path file will cause an error during execution.

• For IPv4: Use an IPv4 .xdb file and set the version to util.IPv4.
• For IPv6: Use an IPv6 .xdb file and set the version to util.IPv6.

import ip2region.util as util

# IPv4 configuration
db_path = "../../data/ip2region_v4.xdb"
version = util.IPv4

# IPv6 configuration
db_path = "../../data/ip2region_v6.xdb"
version = util.IPv6

For maximum performance, you can load the entire .xdb file into memory. This allows for completely memory-based queries.

Workflow:

1. Load content using xdb.load_content(db_path).
2. Create a searcher using xdb.new_with_buffer(version, content).

Concurrency Note: Unlike the file-based approach, query objects created with the entire xdb cache can be safely used concurrently. It is recommended to create a single global searcher object at startup and use it globally.

local xdb = require("xdb_searcher")

-- Load entire file into memory once
local content = xdb.load_content(db_path)

-- Create a global searcher for concurrent use
local searcher, err = xdb.new_with_buffer(xdb.IPv4, content)

-- ... query ...
searcher:close()
xdb.cleanup()

To achieve maximum performance, you can load the entire .xdb file into memory using LongByteArray. This allows for a fully memory-based query. Unlike the VectorIndex method, a Searcher created with the entire buffer can be safely used as a global object for cross-thread access (concurrency-safe).

// 1. Load entire content into memory
LongByteArray cBuff = Searcher.loadContentFromFile(dbPath);

// 2. Create a fully memory-based query object
Searcher searcher = Searcher.newWithBuffer(Version.IPv4, cBuff);

// 3. Query (this searcher can be shared globally across threads)
String region = searcher.search("1.2.3.4");

// Note: Do not close if shared globally; close when the service shuts down

If your environment supports it, you can load the VectorIndex into a global variable. This reduces fixed IO operations and accelerates queries. In concurrent environments, each thread or coroutine should create its own Searcher object, but they can all share the same read-only global vIndex.

use \ip2region\xdb\Util;
use \ip2region\xdb\Searcher;

// 1. Load VectorIndex cache
$vIndex = Util::loadVectorIndexFromFile($dbFile);

// 2. Create searcher with cache
$searcher = Searcher::newWithVectorIndex($version, $dbFile, $vIndex);

// 3. Query
$region = $searcher->search('1.2.3.4');
$searcher->close();

When initializing a searcher, you must ensure the dbPath matches the IP version specified by the version constant. Mismatched versions will cause errors during query execution.

• IPv4: Use an IPv4 .xdb file and xdb.IPv4.
• IPv6: Use an IPv6 .xdb file and xdb.IPv6.

local xdb = require("xdb_searcher")

-- IPv4 Setup
local dbPathV4  = "../../data/ip2region_v4.xdb"
local versionV4 = xdb.IPv4

-- IPv6 Setup
local dbPathV6  = "../../data/ip2region_v6.xdb"
local versionV6 = xdb.IPv6

For maximum performance, you can load the entire .xdb file content into a memory buffer. This enables queries that are entirely memory-resident, similar to the legacy memory search mode.

Workflow:

1. Load the file content using Util::loadContentFromFile($dbFile) into a global buffer.
2. Create a Searcher using Searcher::newWithBuffer($version, $cBuff).

Concurrency Note: Searcher objects created with a buffer are safe for concurrent use. You can keep the Searcher open for the duration of the service life.

// 1. Load entire xdb into memory
$cBuff = Util::loadContentFromFile($dbFile);

// 2. Create searcher using the buffer
try {
    $searcher = Searcher::newWithBuffer($version, $cBuff);
    $region = $searcher->search('1.2.3.4');
    // $searcher->close(); // Safe to keep open for concurrent use
} catch (Exception $e) {
    // handle error
}

You can load the entire .xdb file into memory to perform queries entirely from RAM. This is similar to the legacy memory search implementation.

Pattern: The cBuff (content buffer) can be shared globally. Searchers created from the same buffer are safe for concurrent use.

// 1. Load entire xdb into memory
cBuff, err := xdb.LoadContentFromFile(dbPath)
if err != nil {
    return err
}

// 2. Create searchers using the global buffer
searcher, err := xdb.NewWithBuffer(version, cBuff)