Bio::D...handle(3pm)

💖 Bio::D...handle — the manual page, but make it make sense 💖

okay bestie, gather round, because this is User Contributed Perl Documentation for Bio::DB::GFF::Adaptor::dbi::caching_handle and it is genuinely so much cooler than the name makes it sound. the name is long enough to be a whole government form, but the vibe? immaculate. ✨

---

🌸 NAME 🌸

Bio::DB::GFF::Adaptor::dbi::caching_handle — it's a cache for database handles. that's it, that's the job. 👑

---

✨ SYNOPSIS ✨

here's the whole thing in like four lines, she's efficient:

use Bio::DB::GFF::Adaptor::dbi::caching_handle;
$db  = Bio::DB::GFF::Adaptor::dbi::caching_handle->new('dbi:mysql:test');
$sth = $db->prepare('select * from foo');
@h   = $sth->fetch_rowarray;
$sth->finish

look at her go. no notes. 💅

---

🦋 DESCRIPTION 🦋

so what's the tea. this module manages a pool of database handles. the whole reason it exists is the MYSQL driver's {mysql_use_result} attribute — which, real talk, dramatically improves query speed and memory usage, but it also forbids additional query statements from being evaluated while an existing one is in use. iconic behaviour honestly. very "i'm busy, don't talk to me" energy.

the fix: this module is a plug-in replacement for vanilla DBI. it automatically turns on the {mysql_use_result} attribute for the mysql driver, but it dodges the whole multiple-active-statement-handlers mess by creating new database handles as needed. slay. no cap. 🫶

---

🌈 USAGE 🌈

the object constructor is Bio::DB::GFF::Adaptor::dbi::caching_handle->new(). you call it exactly like DBI->connect() and it takes the same arguments. and the object you get back looks and acts like a conventional database handle. bestie it's literally just a dbh with extra sauce.

in addition to all the standard DBI handle methods, this package adds the following, and yes we're doing all of them, no skipping:

💜 dbi_quote

• Title: dbi_quote
• Usage: $string = $db->dbi_quote($sql,@args)
• Function: perform bind variable substitution
• Returns: query string
• Args: the query string and bind arguments
• Status: public

this method takes the bind variable "?" in a SQL statement and swaps in appropriately quoted bind arguments. it's used internally to handle drivers that don't support argument binding. so if your driver is being difficult, this is the friend who translates. 😌

🎀 do_query

• Title: do_query
• Usage: $sth = $db->do_query($query,@args)
• Function: perform a DBI query
• Returns: a statement handler
• Args: query string and list of bind arguments
• Status: Public

this one does a DBI prepare() and execute(), and hands you back a statement handle. you'll typically call fetch() or fetchrow_array() on that statement handle. and here's the cute part — the parsed statement handle is cached for later use. reusing, recycling, sustainable queen. ♻️

🔥 debug

• Title: debug
• Usage: $debug = $db->debug([$debug])
• Function: activate debugging messages
• Returns: current state of flag
• Args: optional new setting of flag
• Status: public

turns the debugging messages on. pass a new setting if you want to change it, don't if you just wanna peek. 👀

⭐ attribute

• Title: attribute
• Usage: $value = $db->attribute(AttributeName , [$newvalue])
• Function: get/set DBI::db handle attribute
• Returns: current state of the attribute
• Args: name of the attribute and optional new setting of attribute
• Status: public

okay this is the one you actually need to remember, so listen up. under Bio::DB::GFF::Adaptor::dbi::caching_handle, the DBI::db attributes that you'd usually set using hashref calls are unavailable. gone. not invited. use attribute() instead. 💀

so instead of:

$dbh->{AutoCommit} = 0;

use:

$dbh->attribute(AutoCommit=>0);

that's it, that's the swap. write it on your hand. 🙈

---

😭 BUGS 😭

report to the author. (yes that's really all it says. short and devastating.)

---

🌸 SEE ALSO 🌸

• DBI
• Bio::DB::GFF
• bioperl

go read those, they're the extended universe. iykyk. 📚

---

👑 AUTHOR 👑

Lincoln Stein <lstein@cshl.org>.

Copyright (c) 2001 Cold Spring Harbor Laboratory.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

---

💖 and that's the whole page bestie. perl v5.30.0, dated 2020-01-13 — vintage, but still hits. go forth and cache those handles. periodt. ✨🦋🎀