CPANDB(3pm)

📦

version 0.19 · 3 versions

0.19 · debian trixie, ubuntu noble, ubuntu resolute, ubuntu stonking (latest)
0.18 · ubuntu jammy
0.18 · debian bookworm

, in debian trixie, ubuntu noble, ubuntu resolute, ubuntu stonking

💖 CPANDB(3pm) 💖

okay so bestie, welcome to the group chat 🫶 this is CPANDB (the 3pm manual, iykyk) and no cap it's about to be your new fave. buckle up 🎀

🌸 NAME 🌸

CPANDB — a unified database of CPAN metadata information ✨

🌈 DESCRIPTION 🌈

So CPANDB is a module for accessing CPAN metadata, right? And the way it does it is iconic: it merges info from many different CPAN websites into one single object model 🧚 it downloads automatically, and there is zero configuration needed. like, no setup, no config file, nothing — it just gets the data for you 💅

👑 METHODS 👑

`dsn`

my $string = CPANDB->dsn;

The dsn accessor is giving "here's the receipt" energy 🧾 it returns the DBI connection string used to connect to the SQLite database — as a string.

`dbh`

my $handle = CPANDB->dbh;

Okay so this one matters, listen up 📢 To reliably prevent potential SQLite deadlocks that happen when you've got multiple connections chillin' in a single process, each ORLite package will only ever maintain a single connection to the database. One connection. That's it. monogamy 💍

During a transaction, this will be the same (cached) database handle.

Although in most situations you should not need a direct DBI connection handle, the dbh method provides a way to get a direct connection that's compatible with how connection management works in ORLite.

Heads up bestie 🙈 these connections should be short-lived — you should never hold onto a connection beyond your immediate scope. no being clingy, okay?

The transaction system in ORLite is specifically designed so that code using the database should never have to know whether or not it is in a transation. So because of that:

you should never call the ->disconnect method on the database handles yourself 😭 because the handle may be that of a currently running transaction. awkward.
Further, you should do your own transaction management on a handle provided by the <dbh> method.

And in cases where there are extreme needs, and you absolutely have to violate these connection handling rules (bold move 💀), you should create your own completely manual DBI->connect call to the database, using the connect string provided by the dsn method.

The dbh method returns a DBI::db object, or throws an exception on error.

`begin`

CPANDB->begin;

begin is the "start of a transaction" method 🎬

In the same way that ORLite allows only a single connection, likewise it allows only a single application-wide transaction. one at a time, bestie.

No indication is given as to whether you are currently in a transaction or not, so all code should be written neutrally so that it works either way or doesn't need to care.

Returns true or throws an exception on error ✨

`rollback`

rollback rolls back the current transaction. And if you call it outside of a current transaction? It's accepted and treated as a null operation, no drama 😌

Once the rollback has been completed, the database connection falls back into auto-commit state. If you wish to immediately start another transaction, you will need to issue a separate ->begin call.

Also, if a transaction exists at END-time as the process exits, it will be automatically rolled back. it cleans up after itself, iconic.

Returns true or throws an exception on error.

`do`

CPANDB->do(
    'insert into table ( foo, bar ) values ( ?, ? )', {},
    \$foo_value,
    \$bar_value,
);

The do method is a direct wrapper around the equivalent DBI method, but applied to the appropriate locally-provided connection or transaction.