MaxMin...:Reader(3pm)

💖 MaxMind::DB::Reader — the 3pm page but make it cute 💖

okay bestie, so this is MaxMind::DB::Reader, a Perl modgie that reads MaxMind DB files and looks up IP addresses. That's like... the whole vibe. Let's get into it 🌸

---

✨ NAME ✨

MaxMind::DB::Reader — read MaxMind DB files and look up IP addresses. That's it, that's the job 💅

---

✨ VERSION ✨

version 1.000014 — yes, we're on 1.000014, slay ✨

---

✨ SYNOPSIS ✨

okay so here's the entire energy of this module in two lines:

my $reader = MaxMind::DB::Reader->new( file => 'path/to/database.mmdb' );

my $record = $reader->record_for_address('1.2.3.4');

that's it. that's the whole thing. iconic 💖

---

✨ DESCRIPTION ✨

This module gives you a low-level interface to the MaxMind DB file format — learn more at <http://maxmind.github.io/MaxMind-DB/>.

If what you actually want is an interface to MaxMind's GeoIP2 or GeoLite2 downloadable databases (<http://dev.maxmind.com/geoip/>), bestie you should also check out the GeoIP2 distribution — that one gives you a higher level OO interface to those databases. different vibe, fancier outfit 🎀

This API will work with any MaxMind DB databases, doesn't matter if it's a GeoIP2 database or not. And also — if speed is critical — this API will always be faster than the GeoIP2 modules, because it hands you results as a raw Perl data structure instead of as an object. no costume change, just the data. ate 🔥

---

✨ PURE PERL VERSUS XS ✨

So the MaxMind-DB-Reader distribution ships with a single pure Perl implementation of the Reader API. That's the default. Cute. Chill. Works.

There's also a separate distribution on CPAN, MaxMind::DB::Reader::XS, that provides an XS implementation which links against libmaxminddb <http://maxmind.github.io/libmaxminddb/>. fancy!! 🦋

The XS implementation is approximately 100 times faster than the pure Perl implementation, so if speed is important to you, we highly recommend that you install it! like genuinely, if you care about going fast, get the XS one. 100x is not a typo. that's not a rounding error bestie, that's a whole personality 💀

And the best part: if you install the XS implementation it will be automatically loaded. You do not need to change your code to take advantage of it. no edits, no refactor, it just shows up and starts slaying 👑

---

✨ API ✨

This module provides the following API — one bullet-free listicle of methods, here we go:

✨ MaxMind::DB::Reader->new( file => $path )

This method returns a new reader object. 📖

heads up though: the class of the object returned will actually be either MaxMind::DB::Reader::PP or MaxMind::DB::Reader::XS. surprise! it's giving mystery box 🙈

If you need to check that an object is a valid reader, you should check that the object does the "MaxMind::DB::Reader::Role::Reader" role.

The "file" parameter is a required attribute for the constructor. It must be a string containing a path to a file. The constructor will die if the file provided is not readable. no readable file, no reader, periodt 💀

You can also pass an additional parameter, "data_source", which must be a valid filehandle. This is useful in testing. For example, you can have the reader read from a filehandle opened to a scalar reference. Under normal usage, the reader simply opens the provided file to read from. testing girlies, this one's for you 🧚

✨ $reader->record_for_address($ip_address)

This method takes an IPv4 or IPv6 address as a string. This can be either a dotted quad (1.2.3.4) or any valid IPv6 format ("abcd::1234", "::1.2.3.4", etc.).

This method will die if the address is not a valid IP address. so like, don't do that 😭

The method returns the data associated with the IP address. Depending on the contents of the database, this can be a scalar or a reference to an array or hash. it's flexible like that 💅

✨ $reader->iterate_search_tree( $data_callback, $node_callback )

This method iterates over the entire search tree, calling the callbacks you provided for each data record and node in the tree. 🌳

Both callbacks are optional (although calling this with neither will do a lot of work for no good reason). like bestie why would you 😭

The node callback is called for every node in the database's search tree. This callback is called with three arguments. These are the node's number (which is based on its position in the file) and the values of its left and right records. These values are themselves numbers. See the MaxMind DB spec <http://maxmind.github.io/MaxMind-DB/> for more details on what node record values mean. iykyk ✨

The data callback is called for records that point to the database's data section. The first two arguments identify the network that the data record applies to. The first argument is an IP address as an integer and the second is a network mask length. The final argument is the data associated with the network. three args, no more, no less 🫶

✨ $reader->metadata()

This method returns a MaxMind::DB::Metadata object for the database. the lore, if you will 📚

✨ $reader->file()

This method returns the file path passed to the constructor. the receipt of where you came from 🎀

---

✨ VERSIONING POLICY ✨

This module uses semantic versioning as described by <http://semver.org/>. Version numbers can be read as X.YYYZZZ, where X is the major number, YYY is the minor number, and ZZZ is the patch number. so like, X big changes, YYY medium, ZZZ lil guys 🌈

---

✨ SUPPORT ✨

okay so gently: this module is deprecated and will only receive fixes for major bugs and security vulnerabilities. New features and functionality will not be added. it's in its retirement era, let her rest 💜

Please report all issues with this code using the GitHub issue tracker at <https://github.com/maxmind/MaxMind-DB-Reader-perl/issues>.

Bugs may be submitted through <https://github.com/maxmind/MaxMind-DB-Reader-perl/issues>. (same link twice, yes, we're consistent like that 💅)

---

✨ AUTHORS ✨

the masterminds, the legends, the ones who built the thing:

• Dave Rolsky <drolsky@maxmind.com>
• Olaf Alders <oalders@maxmind.com>

---

✨ CONTRIBUTORS ✨

the girlies who pulled up and helped 🫶

• Greg Oschwald <goschwald@maxmind.com>
• Mark Fowler <mark@twoshortplanks.com>
• Mateu X Hunter <mhunter@maxmind.com>
• Ran Eilam <reilam@maxmind.com>
• William Stevenson <skyblue@skybluecircles.com>
• Will Storey <wstorey@maxmind.com>

---

✨ COPYRIGHT AND LICENSE ✨

This software is Copyright (c) 2019 by MaxMind, Inc. 🌸

This is free software, licensed under:

The Artistic License 2.0 (GPL Compatible)

---

and that's the whole page bestie!! this doc was rendered for perl v5.36.0 on 2022-08-28, and it lives under the manual name MaxMin...:Reader(3pm) 🎀✨ go read some IPs, you got this 💖