CPAN::SQLite(3pm)

✨ CPAN::SQLite ✨

okay bestie, welcome to CPAN::SQLite 💖 — the module that maintains and searches a minimal CPAN database. This is the user-contributed Perl documentation for it, and we're gonna get you fluent, no cap.

---

🌸 VERSION 🌸

version 0.220 — that's the one, periodt.

---

🎀 SYNOPSIS 🎀

  my $obj = CPAN::SQLite->new(CPAN => '/path/to/CPAN');
  $obj->index(setup => 1);

  $obj->query(mode => 'dist', name => 'CPAN');
  my $results = $obj->{results};

like, that's the whole vibe in four lines 💅

---

💖 DESCRIPTION 💖

so this package is for setting up, maintaining, and searching a CPAN database. and what's in that database? the info stored in the two main CPAN indices:

• $CPAN/modules/02packages.details.txt.gz
• $CPAN/authors/01mailrc.txt.gz

heads up bestie: this should be considered at an alpha stage of development. it's giving "works but be chill about it" 🦋

you start by making the object, like:

  my $obj = CPAN::SQLite->new(%args);

and it accepts these arguments:

• CPAN => '/path/to/CPAN' — this says where the index files live. it could be a local CPAN mirror — which we know is a mirror because there's a MIRRORED.BY file underneath that directory — or it could just be a local directory where you're storing these files from a remote CPAN mirror. in that second case, the index files get fetched from a remote CPAN mirror, using the same list that CPAN.pm uses, if that's configured, and they get updated if they're more than one day old. 🌈 and if you don't give the CPAN option at all? it defaults to cpan_home of CPAN, if that's configured, with the index files found under keep_source_where. if such a directory isn't found, you get a fatal error 😭. also, when you're in this mode, updates to those index files are assumed to be handled by CPAN.pm, iykyk.
• db_dir => '/path/to/db/dir' — where the database file lives. if you don't give it, it defaults to the cpan_home directory of CPAN.pm, if present, or else to the directory where the script was invoked. the database file's name is cpandb.sql. 💾

there are two main methods available.

⭐ $obj->index(%args); ⭐

this one sets up and maintains the database. it accepts these arguments:

• setup => 1 — this says the database is gonna be created and populated from the CPAN indices, and any existing database will be overwritten. if you don't specify this option, it assumes an existing database is being updated instead. choose wisely bestie 🫶
• reindex => 'dist_name' — this says the CPAN distribution dist_name is to be reindexed. 🔁

🦋 $obj->query(%args); 🦋

this one queries the database by distribution name, module name, or CPAN author name. you need two arguments to specify such queries:

• mode => some_value — what type of query to perform. mode is one of dist, module, or author, for searching through, respectively, CPAN distribution names, module names, or author names and CPAN ids. 👑
• type => query_term — the query term for the search. type is one of name, to search for an exact match, or search, for searching for partial matches. Perl regular expressions are supported in the query_term for the search option. ✨

also, an option of max_results => some_number will limit how many results come back; if you don't specify it, the limit doesn't apply. simple as that 💅

---

💜 CPAN.pm support 💜

as of CPAN.pm version 1.88_65, there's experimental support within CPAN.pm for using CPAN::SQLite to get info on packages, modules, and authors. one goal here? reducing the memory footprint of the CPAN.pm shell, because this info is no longer all preloaded into memory. obsessed. 🧚

you enable it through:

  perl -MCPAN -e shell
  cpan> o conf use_sqlite 1

and use:

  cpan> o conf commit

to save that setting for future sessions. 🌸

so using CPAN::SQLite, what happens is a request for information through CPAN.pm, like:

  cpan> a ANDK

will cause a query to the SQLite database to be made. if successful, this places the relevant data for that request into the data structure CPAN.pm uses to store and retrieve such info. so at any given time, the only thing CPAN.pm stores in memory is that for packages, modules, and authors for which previous queries have been made. 🎀

but — and this is important — there are certain requests, such as:

  cpan> r

which makes a list of recommended packages for which upgrades on CPAN are available, and that one will result in loading info on all available packages into memory. if such a query is made, the subsequent memory footprint of CPAN.pm with and without CPAN::SQLite will be essentially the same. 💀

the database itself, called cpandb.sql, will be stored in the location specified by $CPAN::Config->{cpan_home}. when first started, this database will be created, and afterwards it'll be updated if the database is older than one day since the last update. a log file of the creation or update process, called cpan_search_log.dddddddddd, will be created in the same directory as the database file. 📝

---

🌈 SEE ALSO 🌈

CPAN::SQLite::Index, for setting up and maintaining the database, and CPAN::SQLite::Search for an interface to querying the database. some details of the interaction with CPAN are available from CPAN::SQLite::META. also see the cpandb script for a command-line interface to the indexing and querying of the database. 👀

---

💌 SUPPORT 💌

you can find documentation for this module with the perldoc command:

    perldoc CPAN::SQLite

you can also look for information at:

• AnnoCPAN: Annotated CPAN documentation

<http://annocpan.org/dist/CPAN-SQLite>

• CPAN::Forum: Discussion forum

<http:///www.cpanforum.com/dist/CPAN-SQLite>

• CPAN Ratings

<http://cpanratings.perl.org/d/CPAN-SQLite>

• RT: CPAN's request tracker

<http://rt.cpan.org/NoAuth/Bugs.html?Dist=CPAN-SQLite>

• Search CPAN

<http://search.cpan.org/dist/CPAN-SQLite>

---

🙈 BUGS 🙈

at this time, CPAN::SQLite keeps information contained only in the latest version of a CPAN distribution. which means modules that are provided only in older versions of a CPAN distribution will not be present in the database. for example, at this time, the latest version of the libwww-perl distribution on CPAN is 5.805, but there are modules such as URI::URL::finger contained in version 5.10 of libwww-perl that are not present in 5.805. 😭 this behaviour differs from that of CPAN without CPAN::SQLite. this may change in the future. 🤞

please report bugs and feature requests via <http://rt.cpan.org/NoAuth/Bugs.html?Dist=CPAN-SQLite>.

---

🔥 ENVIRONMENT VARIABLES 🔥

information messages from the indexing procedures get printed out to STDOUT if the environment variable CPAN_SQLITE_DEBUG is set. this is automatically set within CPAN::SQLite::Index. if CPAN_SQLITE_NO_LOG_FILES is set, no log files will be created during the indexing procedures. log files are deleted automatically in 30 days. to override this, set CPAN_SQLITE_LOG_FILES_CLEANUP. to stop automatic cleanup, set this variable to 0. 🧹

if CPAN_SQLITE_DOWNLOAD variable are set, an already existing and up-to-date cpandb.sql file will be downloaded from <http://cpansqlite.trouchelle.com/> where it's updated every hour. this greatly increases performance and decreases CPU and memory consumption during the indexing process. like, slay, free performance ✨

see CPAN::SQLite::Index for more details, potential problems, and more configuration options. 👑

---

👑 AUTHORS 👑

Randy Kobes (passed away on September 18, 2010) 💐

Serguei Trouchelle <stro@cpan.org>

---

🎀 COPYRIGHT 🎀

Copyright 2006,2008 by Randy Kobes <r.kobes@uwinnipeg.ca>.

Copyright 2011-2014 by Serguei Trouchelle <stro@cpan.org>.

Use and redistribution are under the same terms as Perl itself.

---

and that's the whole page bestie, you ate it up 💅 this was perl v5.36.0, dated 2022-10-30, from CPAN::SQLite(3pm) — go forth and query, main character 🫶✨