Skip to content

Commit 6c76e0a

Browse files
oschwaldoschwald
committed
Update README.md
1 parent b1c15f0 commit 6c76e0a

File tree

2 files changed

+229
-19
lines changed

2 files changed

+229
-19
lines changed

‎CHANGELOG.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,8 +8,8 @@
88
the documentation organization.
99
- Added `Unmarshaler` interface to allow custom decoding implementations for
1010
performance-critical applications. Types implementing
11-
`UnmarshalMaxMindDB(d *Decoder) error` will automatically use custom
12-
decoding logic instead of reflection, following the same pattern as
11+
`UnmarshalMaxMindDB(d *Decoder) error` will automatically use custom decoding
12+
logic instead of reflection, following the same pattern as
1313
`json.Unmarshaler`.
1414
- Added public `Decoder` type with methods for manual decoding including
1515
`DecodeMap()`, `DecodeSlice()`, `DecodeString()`, `DecodeUInt32()`, etc.

‎README.md

Lines changed: 227 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,36 +1,246 @@
1-
# MaxMind DB Reader for Go #
1+
# MaxMind DB Reader for Go
22

33
[![Go Reference](https://pkg.go.dev/badge/github.com/oschwald/maxminddb-golang/v2.svg)](https://pkg.go.dev/github.com/oschwald/maxminddb-golang/v2)
44

55
This is a Go reader for the MaxMind DB format. Although this can be used to
6-
read [GeoLite2](http://dev.maxmind.com/geoip/geoip2/geolite2/) and
7-
[GeoIP2](https://www.maxmind.com/en/geoip2-databases) databases,
8-
[geoip2](https://github.com/oschwald/geoip2-golang) provides a higher-level
9-
API for doing so.
6+
read [GeoLite2](https://dev.maxmind.com/geoip/geolite2-free-geolocation-data)
7+
and [GeoIP2](https://www.maxmind.com/en/geoip2-databases) databases,
8+
[geoip2](https://github.com/oschwald/geoip2-golang) provides a higher-level API
9+
for doing so.
1010

1111
This is not an official MaxMind API.
1212

13-
## Installation ##
13+
## Installation
1414

15-
```
15+
```bash
1616
go get github.com/oschwald/maxminddb-golang/v2
1717
```
1818

19-
## Usage ##
19+
## Version 2.0 Features
20+
21+
Version 2.0 includes significant improvements:
22+
23+
- **Modern API**: Uses `netip.Addr` instead of `net.IP` for better performance
24+
- **Custom Unmarshaling**: Implement `Unmarshaler` interface for
25+
zero-allocation decoding
26+
- **Network Iteration**: Iterate over all networks in a database with
27+
`Networks()` and `NetworksWithin()`
28+
- **Enhanced Performance**: Optimized data structures and decoding paths
29+
- **Go 1.24+ Support**: Takes advantage of modern Go features including
30+
iterators
31+
- **Better Error Handling**: More detailed error types and improved debugging
32+
33+
## Quick Start
34+
35+
```go
36+
package main
37+
38+
import (
39+
"fmt"
40+
"log"
41+
"net/netip"
42+
43+
"github.com/oschwald/maxminddb-golang/v2"
44+
)
45+
46+
func main() {
47+
db, err := maxminddb.Open("GeoLite2-City.mmdb")
48+
if err != nil {
49+
log.Fatal(err)
50+
}
51+
defer db.Close()
52+
53+
ip, err := netip.ParseAddr("81.2.69.142")
54+
if err != nil {
55+
log.Fatal(err)
56+
}
57+
58+
var record struct {
59+
Country struct {
60+
ISOCode string `maxminddb:"iso_code"`
61+
Names map[string]string `maxminddb:"names"`
62+
} `maxminddb:"country"`
63+
City struct {
64+
Names map[string]string `maxminddb:"names"`
65+
} `maxminddb:"city"`
66+
}
67+
68+
err = db.Lookup(ip).Decode(&record)
69+
if err != nil {
70+
log.Fatal(err)
71+
}
72+
73+
fmt.Printf("Country: %s (%s)\n", record.Country.Names["en"], record.Country.ISOCode)
74+
fmt.Printf("City: %s\n", record.City.Names["en"])
75+
}
76+
```
77+
78+
## Usage Patterns
79+
80+
### Basic Lookup
81+
82+
```go
83+
db, err := maxminddb.Open("GeoLite2-City.mmdb")
84+
if err != nil {
85+
log.Fatal(err)
86+
}
87+
defer db.Close()
88+
89+
var record any
90+
ip := netip.MustParseAddr("1.2.3.4")
91+
err = db.Lookup(ip).Decode(&record)
92+
```
93+
94+
### Custom Struct Decoding
95+
96+
```go
97+
type City struct {
98+
Country struct {
99+
ISOCode string `maxminddb:"iso_code"`
100+
Names struct {
101+
English string `maxminddb:"en"`
102+
German string `maxminddb:"de"`
103+
} `maxminddb:"names"`
104+
} `maxminddb:"country"`
105+
}
106+
107+
var city City
108+
err = db.Lookup(ip).Decode(&city)
109+
```
110+
111+
### High-Performance Custom Unmarshaling
112+
113+
```go
114+
type FastCity struct {
115+
CountryISO string
116+
CityName string
117+
}
118+
119+
func (c *FastCity) UnmarshalMaxMindDB(d *maxminddb.Decoder) error {
120+
for key, err := range d.DecodeMap() {
121+
if err != nil {
122+
return err
123+
}
124+
switch string(key) {
125+
case "country":
126+
for countryKey, countryErr := range d.DecodeMap() {
127+
if countryErr != nil {
128+
return countryErr
129+
}
130+
if string(countryKey) == "iso_code" {
131+
c.CountryISO, err = d.DecodeString()
132+
if err != nil {
133+
return err
134+
}
135+
} else {
136+
if err := d.SkipValue(); err != nil {
137+
return err
138+
}
139+
}
140+
}
141+
default:
142+
if err := d.SkipValue(); err != nil {
143+
return err
144+
}
145+
}
146+
}
147+
return nil
148+
}
149+
```
150+
151+
### Network Iteration
152+
153+
```go
154+
// Iterate over all networks in the database
155+
for result := range db.Networks() {
156+
var record struct {
157+
Country struct {
158+
ISOCode string `maxminddb:"iso_code"`
159+
} `maxminddb:"country"`
160+
}
161+
err := result.Decode(&record)
162+
if err != nil {
163+
log.Fatal(err)
164+
}
165+
fmt.Printf("%s: %s\n", result.Prefix(), record.Country.ISOCode)
166+
}
167+
168+
// Iterate over networks within a specific prefix
169+
prefix := netip.MustParsePrefix("192.168.0.0/16")
170+
for result := range db.NetworksWithin(prefix) {
171+
// Process networks within 192.168.0.0/16
172+
}
173+
```
174+
175+
### Path-Based Decoding
176+
177+
```go
178+
var countryCode string
179+
err = db.Lookup(ip).DecodePath(&countryCode, "country", "iso_code")
180+
181+
var cityName string
182+
err = db.Lookup(ip).DecodePath(&cityName, "city", "names", "en")
183+
```
184+
185+
## Supported Database Types
186+
187+
This library supports **all MaxMind DB (.mmdb) format databases**, including:
188+
189+
**MaxMind Official Databases:**
190+
191+
- **GeoLite/GeoIP City**: Comprehensive location data including city, country,
192+
subdivisions
193+
- **GeoLite/GeoIP Country**: Country-level geolocation data
194+
- **GeoLite ASN**: Autonomous System Number and organization data
195+
- **GeoIP Anonymous IP**: Anonymous network and proxy detection
196+
- **GeoIP Enterprise**: Enhanced City data with additional business fields
197+
- **GeoIP ISP**: Internet service provider information
198+
- **GeoIP Domain**: Second-level domain data
199+
- **GeoIP Connection Type**: Connection type identification
200+
201+
**Third-Party Databases:**
202+
203+
- **DB-IP databases**: Compatible with DB-IP's .mmdb format databases
204+
- **IPinfo databases**: Works with IPinfo's MaxMind DB format files
205+
- **Custom databases**: Any database following the MaxMind DB file format
206+
specification
207+
208+
The library is format-agnostic and will work with any valid .mmdb file
209+
regardless of the data provider.
210+
211+
## Performance Tips
212+
213+
1. **Reuse Reader instances**: The `Reader` is thread-safe and should be reused
214+
across goroutines
215+
2. **Use specific structs**: Only decode the fields you need rather than using
216+
`any`
217+
3. **Implement Unmarshaler**: For high-throughput applications, implement
218+
custom unmarshaling
219+
4. **Consider caching**: Use `Result.Offset()` as a cache key for database
220+
records
221+
222+
## Getting Database Files
223+
224+
### Free GeoLite2 Databases
225+
226+
Download from
227+
[MaxMind's GeoLite page](https://dev.maxmind.com/geoip/geolite2-free-geolocation-data).
228+
229+
## Documentation
20230

21-
[See GoDoc](http://godoc.org/github.com/oschwald/maxminddb-golang) for
22-
documentation and examples.
231+
- [Go Reference](https://pkg.go.dev/github.com/oschwald/maxminddb-golang/v2)
232+
- [MaxMind DB File Format Specification](https://maxmind.github.io/MaxMind-DB/)
23233

24-
## Examples ##
234+
## Requirements
25235

26-
See [GoDoc](http://godoc.org/github.com/oschwald/maxminddb-golang) or
27-
`example_test.go` for examples.
236+
- Go 1.23 or later
237+
- MaxMind DB file in .mmdb format
28238

29-
## Contributing ##
239+
## Contributing
30240

31-
Contributions welcome! Please fork the repository and open a pull request
32-
with your changes.
241+
Contributions welcome! Please fork the repository and open a pull request with
242+
your changes.
33243

34-
## License ##
244+
## License
35245

36246
This is free software, licensed under the ISC License.

0 commit comments

Comments
 (0)