XDB file generation

1. Choose a maker

You can find all the maker implementations via Github/maker or Gitee/maker, then work with the client written in the language you are most familiar with. It is recommended that you prefer the Golang or Java implementation: first, new features and optimization details land in these two versions first; second, any problems you run into during use get a relatively quick response and support.

1. Java: Github-xdb-java-maker or Gitee-xdb-java-maker

2. Golang: Github-xdb-golang-maker or Gitee-xdb-golang-maker

2. Compile the maker

Every maker implementation in the repository comes with detailed compilation documentation. Here we only take Java and Golang as examples to describe the compilation process for reference:

1. Clone the code:

➜  ~ git clone git@gitee.com:lionsoul/ip2region.git
Cloning into 'ip2region'...
remote: Enumerating objects: 5184, done.
remote: Counting objects: 100% (83/83), done.
remote: Compressing objects: 100% (53/53), done.
remote: Total 5184 (delta 23), reused 14 (delta 5), pack-reused 5101 (from 1)
Receiving objects: 100% (5184/5184), 68.13 MiB | 2.05 MiB/s, done.
Resolving deltas: 100% (2792/2792), done.

// Or via Github:
// git clone git@github.com:lionsoul2014/ip2region.git

2. Compile the maker

Java:

➜  ~ cd ip2region/maker/java
➜  java git:(master) mvn clean compile package
...
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  5.628 s
[INFO] Finished at: 2025-09-29T12:17:35+08:00
[INFO] ------------------------------------------------------------------------

The resulting runnable jar file is ./target/ip2region-maker-3.0.0.jar

Golang:

➜  ~ cd ip2region/maker/golang
➜  golang git:(master) make
go build -o xdb_maker

The resulting runnable binary is ./xdb_maker

3. Generate the XDB file

Extract the source file downloaded from the community's "Offline services" and you will get a .txt file and a .csv file. The makers below only need the .txt file. Taking the v4-Base as an example, the file name is ipv4_base.txt; for IPv6 generation you only need to specify --version=ipv6 and the rest of the operation is exactly the same.

Java generation:

The generation command and its corresponding optional parameters are as follows:

➜  java git:(master) java -jar ./target/ip2region-maker-3.0.0.jar
ip2region xdb maker
java -jar ip2region-maker-{version}.jar [command options]
options:
 --src string           source ip text file path
 --dst string           destination binary xdb file path
 --version string       IP version, options: ipv4/ipv6, specify this flag so you don't get confused
 --field-list string    field index list imploded with ',' eg: 0,1,2,3-6,7
 --log-level string     set the log level, options: debug/info/warn/error

--src: the source ipv4_base.txt file obtained by extracting the archive above; either an absolute or a relative path works.

--dst: the path of the destination xdb file to generate; either an absolute or a relative path works.

--version: the IP version of the source ipv4_base.txt file; set it to ipv4 for v4 and to ipv6 for v6.

--field-list: custom field selection; no need to set it by default. If you need custom fields, refer to the description of custom data fields below.

--log-level: the log level of the output during the run; it defaults to info, which skips all debug output.

The v4-Base XDB generation process on my local machine is as follows:

java -jar ./target/ip2region-maker-3.0.0.jar --src=/home/lionsoul/ipv4_base.txt --dst=/home/lionsoul/base_full_v4.xdb --version=ipv4 --log-level=info
2025-09-29 12:32:14 INFO  org.lionsoul.ip2region.MakerApp Generating xdb with src=/home/lionsoul/ipv4_base.txt, dst=/home/lionsoul/base_full_v4.xdb, logLevel=info
2025-09-29 12:32:14 INFO  org.lionsoul.ip2region.xdb.Maker try to init the db header ...
2025-09-29 12:32:14 INFO  org.lionsoul.ip2region.xdb.Maker try to load the segments ...
2025-09-29 12:33:18 INFO  org.lionsoul.ip2region.xdb.Maker all segments loaded, length: 16961584, elapsed: 63800 ms
2025-09-29 12:33:18 INFO  org.lionsoul.ip2region.xdb.Maker try to write the data block ...
2025-09-29 12:33:22 INFO  org.lionsoul.ip2region.xdb.Maker try to write the segment index block ...
2025-09-29 12:34:43 INFO  org.lionsoul.ip2region.xdb.Maker try to write the vector index block ...
2025-09-29 12:34:43 INFO  org.lionsoul.ip2region.xdb.Maker try to write the segment index ptr ...
2025-09-29 12:34:43 INFO  org.lionsoul.ip2region.xdb.Maker write done, dataBlocks: 398547, indexBlocks: (16961584, 16986028), indexPtr: (40755878, 278560256)
2025-09-29 12:34:43 INFO  org.lionsoul.ip2region.MakerApp Done, elapsed: 148 s

The source file is ipv4_base.txt, the generated file is base_full_v4.xdb, the log level is set to info, and the generation took 148s.

Golang generation:

The generation command and its corresponding optional parameters are as follows:

➜  golang git:(master) ./xdb_maker gen
./xdb_maker gen [command options]
options:
 --src string           source ip text file path
 --dst string           destination binary xdb file path
 --version string       IP version, options: ipv4/ipv6, specify this flag so you don't get confused
 --field-list string    field index list imploded with ',' eg: 0,1,2,3-6,7
 --log-level string     set the log level, options: debug/info/warn/error

--src: the source ipv4_base.txt file obtained by extracting the archive above; either an absolute or a relative path works.

--dst: the path of the destination xdb file to generate; either an absolute or a relative path works.

--version: the IP version of the source ipv4_base.txt file; set it to ipv4 for v4 and to ipv6 for v6.

--field-list: custom field selection; no need to set it by default. If you need custom fields, refer to the description of custom data fields below.

--log-level: the log level of the output during the run; it defaults to info, which skips all debug output.

The Base variant XDB generation process on my local machine is as follows:

./xdb_maker gen --src=/home/lionsoul/ipv4_base.txt --dst=/home/lionsoul/base_full_v4.xdb --version=ipv4 --log-level=info
2025/09/29 13:05:51 main.go:231: INFO Generating xdb with src=/home/lionsoul/ipv4_base.txt dst=/home/lionsoul/base_full_v4.xdb logLevel=info
2025/09/29 13:05:51 maker.go:119: INFO try to init the db header ...
2025/09/29 13:05:51 maker.go:159: INFO try to load the segments ...
2025/09/29 13:06:20 maker.go:187: INFO all segments loaded length=16961584 elapsed=29.343612836s
2025/09/29 13:06:20 maker.go:234: INFO try to write the data block ...
2025/09/29 13:06:24 maker.go:269: INFO try to write the segment index block ...
2025/09/29 13:07:56 maker.go:332: INFO try to write the vector index block ...
2025/09/29 13:07:56 maker.go:343: INFO try to write the segment index ptr ...
2025/09/29 13:07:56 maker.go:356: INFO write done dataBlocks=398547 indexBlocks=16961584 counter=16986028 startIndexPtr=40755878 endIndexPtr=278560256
2025/09/29 13:07:56 main.go:249: INFO make done elapsed=2m5.249004628s

The source file is ipv4_base.txt, the generated file is base_full_v4.xdb, the log level is set to info, and the generation took 3m10s.

4. Custom data fields

For example, one line of the sample source data of the Base variant is as follows:

223.246.178.235|223.246.178.235|亚洲|中国|广东|深圳|宝安|电信|113.88311|22.55371|440306|0755|518100|Asia/Shanghai|CNY|11|CHXX0120

After removing the leading start IP and end IP, it becomes:

亚洲|中国|广东|深圳|宝安|电信|113.88311|22.55371|440306|0755|518100|Asia/Shanghai|CNY|11|CHXX0120

The information above is the region data defined by XDB. It is written as-is into the data area of the XDB file. Duplicated region data is written only once, and different indexes share the same data pointer; this sharing makes the resulting XDB file much smaller than the source file. The fields above and their corresponding indexes are as follows:

Essentially these are the array indexes of the data above after splitting it by |. For example, if we want to keep only the field set [1,2,3,4,5], we do it by setting --field-list=1-5. The generation command is:

java -jar ./target/ip2region-maker-3.0.0.jar --src=/home/lionsoul/ipv4_base.txt --dst=/home/lionsoul/base_full_v4.xdb --version=ipv4 --field-list=1-5 --log-level=info

The three XDB file variants provided under "Data services" in your personal center are all sized between (65M,270M) (this changes with the source data, for reference only). The field settings are as follows:

1. The region data of the Full variant is as follows:

亚洲|中国|广东|深圳|宝安|电信|113.88311|22.55371|440306|0755|518100|Asia/Shanghai|CNY|11|CHXX0120

It keeps all valid fields; no setting is needed — all fields are kept by default.

2. The region data of the Standard variant is as follows:

中国|广东|深圳|宝安|电信

That is, only the region info down to the district is kept. Referring to the mapping table above, the field setting is: --field-list=1-5

3. The region data of the Simplified variant is as follows:

中国|广东|深圳|电信

That is, only the region info down to the city is kept, which is identical to the free data fields of the Ip2Region repository. Referring to the mapping table above, the field setting is: --field-list=1-3,5

Here are a few more example field settings:

1. Region info down to the province only: --field-list=1,2 or --field-list=1-2

2. Region info down to the city + longitude/latitude: --field-list=1-3,6-7 or --field-list=1-3,6,7

3. Region info down to the district + longitude/latitude + time zone: --field-list=1-4,6-7,11 or --field-list=1-4,6,7,11