Ima::DBI(3)

💖 NAME 💖

Ima::DBI — yes, bestie, this is the Ima::DBI(3) manpage — is literally database connection caching and organization. Periodt. ✨

✨ SYNOPSIS ✨

package Foo;
use base 'Ima::DBI';

# Class-wide methods.
Foo->set_db($db_name, $data_source, $user, $password);
Foo->set_db($db_name, $data_source, $user, $password, \%attr);

my @database_names   = Foo->db_names;
my @database_handles = Foo->db_handles;

Foo->set_sql($sql_name, $statement, $db_name);
Foo->set_sql($sql_name, $statement, $db_name, $cache);

my @statement_names   = Foo->sql_names;

# Object methods.
$dbh = $obj->db_*;      # Where * is the name of the db connection.
$sth = $obj->sql_*;     # Where * is the name of the sql statement.
$sth = $obj->sql_*(@sql_pieces);

$obj->DBIwarn($what, $doing);

my $rc = $obj->commit;
my $rc = $obj->commit(@db_names);

my $rc = $obj->rollback;
my $rc = $obj->rollback(@db_names);

🌸 DESCRIPTION 🌸

Okay so Ima::DBI is out here trying to organize and facilitate caching and more efficient use of database connections and statement handles by storing DBI and SQL information with your class (instead of as a bunch of separate objects). The whole point? You can pass around just one object and not worry about a trail of DBI handles following behind it. Iconic. 💅

The origin story is lowkey relatable: writing large programs with DBI meant making sure you didn’t have duplicate database handles open. Also annoying? The somewhat wasteful nature of the prepare/execute/finish route you’d tend to go through in your subroutines. The new DBI->connect_cached and DBI->prepare_cached helped a lot, but you still had to throw around global datasource, username and password information. 😭

So, after a while, a small library of DBI helper routines and techniques grew. Ima::DBI is the culmination of all this, put into a nice(?), clean(?) class to be inherited from. 🎀

🦋 Why should I use this thing? 🦋

Ima::DBI is a little odd, and it’s kinda hard to explain. So lemme explain why you’d want to use this thing...

• Consolidation of all SQL statements and database information — No matter what, embedding one language into another is messy. DBI alleviates this somewhat, but there’s a tendency to have that scatter the SQL around inside the Perl code. Ima::DBI allows you to easily group the SQL statements in one place where they’re easier to maintain (especially if one developer is writing the SQL, another writing the Perl). Alternatively, you can place your SQL statement alongside the code which uses it. Whatever floats your boat. 🛶
  • Database connection information (data source, username, password, attributes, etc...) can also be consolidated together and tracked. 👀
  • Both the SQL and the connection info are probably going to change a lot, so having them well organized and easy to find in the code is a Big Help. Big. Help. 💖
• Holds off opening a database connection until necessary — While Ima::DBI is informed of all your database connections and SQL statements at compile-time, it will not connect to the database until you actually prepare a statement on that connection. No cap. ✨
  • This is obviously very good for programs that sometimes never touch the database. It’s also good for code that has lots of possible connections and statements, but which typically only use a few. Kinda like an autoloader. 🔥
• Easy integration of the DBI handles into your class — Ima::DBI causes each database handle to be associated with your class, allowing you to pull handles from an instance of your object, as well as making many oft-used DBI methods available directly from your instance. 🫶
  • This gives you a cleaner OO design, since you can now just throw around the object as usual and it will carry its associated DBI baggage with it. Main character energy. 👑
• Honors taint mode — It always struck me as a design deficiency that tainted SQL statements could be passed to $sth->prepare(). For example:

# $user is from an untrusted source and is tainted.
$user = get_user_data_from_the_outside_world;
$sth = $dbh->prepare('DELETE FROM Users WHERE User = $user');

Looks innocent enough... but what if $user was the string "1 OR User LIKE '%'". You just blew away all your users. Hope you have backups. 😭💀

Ima::DBI turns on the DBI->connect Taint attribute so that all DBI methods (except execute()) will no longer accept tainted data. See "Taint" in DBI for details. 🔒

• Taints returned data — Databases should be like any other system call. It’s the scary Outside World, thus it should be tainted. Simple. Ima::DBI turns on DBI’s Taint attribute on each connection. This feature is overridable by passing your own Taint attribute to set_db as normal for DBI. See "Taint" in DBI for details. 🦋
• Encapsulation of some of the more repetitive bits of everyday DBI usage — I get lazy a lot and I forget to do things I really should, like using bind_cols(), or rigorous error checking. Ima::DBI does some of this stuff automatically, other times it just makes it more convenient. 😅
• Encapsulation of DBI’s cache system — DBI’s automatic handle caching system is relatively new, and some people aren’t aware of its use. Ima::DBI uses it automatically, so you don’t have to worry about it. (It even makes it a bit more efficient.) ⚡
• Sharing of database and sql information amongst inherited classes — Any SQL statements and connections created by a class are available to its children via normal method inheritance. 🌈
• Guarantees one connection per program. — One program, one database connection (per database user). One program, one prepared statement handle (per statement, per database user). That’s what Ima::DBI enforces. Extremely handy in persistant environments (servers, daemons, mod_perl, FastCGI, etc...) 👑
• Encourages use of bind parameters and columns — Bind parameters are safer and more efficient than embedding the column information straight into the SQL statement. Bind columns are more efficient than normal fetching. Ima::DBI pretty much requires the usage of the former, and eases the use of the latter. 💅

💀 Why shouldn't I use this thing. 💀

• It’s all about OO — Although it is possible to use Ima::DBI as a stand-alone module as part of a function-oriented design, it’s generally not to be used unless integrated into an object-oriented design. 🫠
• Overkill for small programs — yeah, no extra detail, it’s just overkill. 😬
• Overkill for programs with only one or two SQL statements — It’s up to you whether the trouble of setting up a class and jumping through the necessary Ima::DBI hoops is worth it for small programs. To me, it takes just as much time to set up an Ima::DBI subclass as it would to access DBI without it... but then again I wrote the module. YMMV. 🤷
• Overkill for programs that only use their SQL statements once — Ima::DBI’s caching might prove to be an unnecessary performance hog if you never use the same SQL statement twice. Not sure, I haven’t looked into it. 🙈

🎀 USAGE 🎀

The basic steps to "DBIing" a class are:

1. Inherit from Ima::DBI
2. Set up and name all your database connections via set_db()
3. Set up and name all your SQL statements via set_sql()
4. Use sql_* to retrieve your statement handles ($sth) as needed and db_* to retrieve database handles ($dbh).

Have a look at EXAMPLE below. 💖

🧚 TAINTING 🧚

Ima::DBI, by default, uses DBI’s Taint flag on all connections. 🔒

This means that Ima::DBI methods do not accept tainted data, and that all data fetched from the database will be tainted. This may be different from the DBI behavior you’re used to. See "Taint" in DBI for details. 💜

💖 CLASS METHODS 💖

✨ set_db ✨

Foo->set_db($db_name, $data_source, $user, $password);
Foo->set_db($db_name, $data_source, $user, $password, \%attr);

Okay so bestie, this is literally the method you use instead of DBI->connect to make your database handles. It sets up a shiny new DBI database handle tied to $db_name, and every other argument gets passed straight through to DBI->connect_cached. No cap, it's just a little wrapper with ✨personality✨.

A brand-new method gets created for every db you set up, and that method is called "db_$db_name"… so like, Foo->set_db("foo", ...) will create a method called "db_foo()". (Spaces in $db_name get translated into underscores: '_' — she keeps it tidy like that 💅.)

%attr gets combined with a set of defaults — and those defaults are RaiseError => 1, AutoCommit => 0, PrintError => 0, Taint => 1. This is a better default IMHO, but lowkey it does give databases without transactions (such as MySQL when used with the default MyISAM table type) a hard time 😭. So be sure to turn AutoCommit back on if your database doesn't support transactions. Fr fr, don't skip that.

The actual database handle creation — and therefore the actual database connection — is held off until a prepare is attempted with this handle. So it's giving very "we'll get there when we get there" 🦋.

✨ set_sql ✨

Foo->set_sql($sql_name, $statement, $db_name);
Foo->set_sql($sql_name, $statement, $db_name, $cache);

This one is used in place of DBI->prepare to create your statement handles. It sets up a new statement handle associated to $sql_name, using the database connection associated with $db_name. Then $statement gets passed through to either DBI->prepare or DBI->prepare_cached (depending on $cache) to create the statement handle. Iconic behavior, honestly.

If $cache is true or isn't given at all, then prepare_cached() will be used to prepare the statement handle and it will be cached 🎀. If $cache is false, then a normal prepare() gets used and the statement handle will be recompiled on every sql_*() call. So if you have a statement which changes a lot or is used very infrequently, you might not want it cached. Know your vibes 💜.

A new method gets created for each statement you set up, and it's called "sql_$sql_name"… so, as with set_db(), Foo->set_sql("bar", ..., "foo"); will create a method called "sql_bar()" which uses the database connection from "db_foo()". Again, spaces in $sql_name get translated into underscores ('_').

The actual statement handle creation is held off until sql_* is first called on this name. Delayed gratification, we love to see it 🌸.

✨ transform_sql ✨

To make up for the limitations of bind parameters, $statement can contain sprintf() style formatting (ie. %s and such) to allow dynamically generated SQL statements (so to get a real percent sign, use '%%').

The translation of the SQL happens in transform_sql(), which can be overridden to do more complex transformations. See Class::DBI for an example. 👑

✨ db_names / db_handles ✨

my @database_names   = Foo->db_names;
my @database_handles = Foo->db_handles;
my @database_handles = Foo->db_handles(@db_names);

Returns a list of the database handles set up for this class using set_db(). And yes, that includes all inherited handles — the whole family tree 👯‍♀️.

db_names() simply returns the name of the handle, from which it is possible to access it by converting it to a method name and calling that db method…

my @db_names = Foo->db_names;
my $db_meth = 'db_'.$db_names[0];
my $dbh = $foo->$db_meth;

Icky, eh? 😬 Fortunately, db_handles() does this for you and returns a list of database handles in the same order as db_names(). Use this sparingly, though — because it will connect you to the database if you weren't already connected. Like, it will just go ahead and do that 🙈.

If given @db_names, db_handles() will return only the handles for those connections. Picky, but make it fashion.

These both work as either class or object methods. Flexible queen behavior 💅.

✨ sql_names ✨

my @statement_names   = Foo->sql_names;

Similar to db_names(), this returns the names of all SQL statements set up for this class using set_sql(), inherited or otherwise.

There is no corresponding sql_handles() because we can't know what arguments to pass in. We're not psychic, bestie 🔮😭.

---

🌈 OBJECT METHODS 🌈

✨ db_* ✨

$dbh = $obj->db_*;

This is how you directly access a database handle you set up with set_db. The actual particular method name is derived from what you told set_db — iykyk.

db_* will handle all the issues of making sure you're already connected to the database, so you can just vibe and grab your handle 🫶.

✨ sql_* ✨

$sth = $obj->sql_*;
$sth = $obj->sql_*(@sql_pieces);

sql_*() is a catch-all name for the methods you set up with set_sql(). For instance, if you did:

Foo->set_sql('GetAllFoo', 'Select * From Foo', 'SomeDb');

you'd run that statement with sql_GetAllFoo().

sql_* will handle all the issues of making sure the database is already connected, and the statement handle is prepared. It returns a prepared statement handle for you to use. (You're expected to execute() it — the rest is on you, bestie 😌).

If sql_*() is given a list of @sql_pieces it will use them to fill in your statement, assuming you have sprintf() formatting tags in your statement. For example:

Foo->set_sql('GetTable', 'Select * From %s', 'Things');

# Assuming we have created an object... this will prepare the
# statement 'Select * From Bar'
$sth = $obj->sql_Search('Bar');

⚠️ Be very careful with what you feed this function. It cannot do any quoting or escaping for you, so it is totally up to you to take care of that. Fortunately if you have tainting on you will be spared the worst. 🙏

It is recommended you only use this in cases where bind parameters will not work. Like, it's a last resort, not a lifestyle ✨.

✨ DBIwarn ✨

$obj->DBIwarn($what, $doing);

Produces a useful error for exceptions with DBI.

I'm not particularly happy with this interface 😅 — that's a direct quote from the author's soul, we respect it.

Most useful like this:

eval {
    $self->sql_Something->execute($self->{ID}, @stuff);
};
if($@) {
    $self->DBIwarn($self->{ID}, 'Something');
            return;
}

---

🦋 MODIFIED DATABASE HANDLE METHODS 🦋

Ima::DBI makes some of the methods available to your object that are normally only available via the database handle. And in addition, it spices up the API a bit 🌶️✨.

✨ commit ✨

$rc = $obj->commit;
$rc = $obj->commit(@db_names);

Derived from $dbh->commit() and basically does the same thing.

If called with no arguments, it causes commit() to be called on all database handles associated with $obj. Otherwise it commits all database handles whose names are listed in @db_names.

Alternatively, you may like to do: $rc = $obj->db_Name->commit; 💅

If all the commits succeeded it returns true, false otherwise.

✨ rollback ✨

$rc = $obj->rollback;
$rc = $obj->rollback(@db_names);

Derived from $dbh->rollback, this acts just like Ima::DBI->commit, except that it calls rollback(). Same energy, opposite direction 🌀.

Alternatively, you may like to do: $rc = $obj->db_Name->rollback;

If all the rollbacks succeeded it returns true, false otherwise.

---

🔥 EXAMPLE 🔥

package Foo;
use base qw(Ima::DBI);

# Set up database connections (but don't connect yet)
Foo->set_db('Users', 'dbi:Oracle:Foo', 'admin', 'passwd');
Foo->set_db('Customers', 'dbi:Oracle:Foo', 'Staff', 'passwd');

# Set up SQL statements to be used through out the program.
Foo->set_sql('FindUser', <<"SQL", 'Users');
    SELECT  *
    FROM    Users
    WHERE   Name LIKE ?
SQL

Foo->set_sql('ChangeLanguage', <<"SQL", 'Customers');
    UPDATE  Customers
    SET     Language = ?
    WHERE   Country = ?
SQL

# rest of the class as usual.

package main;

$obj = Foo->new;

eval {
    # Does connect & prepare
    my $sth = $obj->sql_FindUser;
    # bind_params, execute & bind_columns
    $sth->execute(['Likmi%'], [\($name)]);
    while( $sth->fetch ) {
        print $name;
    }

    # Uses cached database and statement handles
    $sth = $obj->sql_FindUser;
    # bind_params & execute.
    $sth->execute('%Hock');
    @names = $sth->fetchall;

    # connects, prepares
    $rows_altered = $obj->sql_ChangeLanguage->execute(qw(es_MX mx));
};
unless ($@) {
    # Everything went okay, commit the changes to the customers.
    $obj->commit('Customers');
}
else {
    $obj->rollback('Customers');
    warn "DBI failure:  $@";
}

---

🧚 USE WITH MOD_PERL, FASTCGI, ETC. 🧚

To help with use in forking environments, Ima::DBI database handles keep track of the PID of the process they were openend under. If they notice a change (because you forked a new process), a new handle will be opened in the new process. This prevents a common problem seen in environments like mod_perl where people would open a handle in the parent process and then run into trouble when they try to use it from a child process. Fork-safe queen 🫶

Because Ima::DBI handles keeping database connections persistent and prevents problems with handles openend before forking, it is not necessary to use Apache::DBI when using Ima::DBI. However, there is one feature of Apache::DBI which you will need in a mod_perl or FastCGI environment, and that's the automatic rollback it does at the end of each request. This rollback provides safety from transactions left hanging when some perl code dies — a serious problem which could grind your database to a halt with stale locks. 💀

To replace this feature on your own under mod_perl, you can add something like this in a handler at any phase of the request:

$r->push_handlers(PerlCleanupHandler => sub {
    MyImaDBI->rollback();
});

Here "MyImaDBI" is your subclass of Ima::DBI. You could also make this into an actual module and set the PerlCleanupHandler from your httpd.conf. A similar approach should work in any long-running environment which has a hook for running some code at the end of each request. Slay ✨

---

💀 TODO, CAVEAT, BUGS, ETC.... 💀

• I seriously doubt that it's thread safe. You can bet cupcackes to sno-cones that much havoc will be wrought if Ima::DBI is used in a threaded Perl. Like, absolutely not, do not do this 🙈.
• Should make use of private_* handle method to store information That's the todo. It's giving "noted, bestie" 📝
• The docs stink. The docs were originally written when I didn't have a good handle on the module and how it will be used in practical cases. I need to rewrite the docs from the ground up. (Author's words, and honestly? Vulnerable. Respect 🫶)
• Need to add debugging hooks. The thing which immediately comes to mind is a Verbose flag to print out SQL statements as they are made as well as mention when database connections are made, etc…

---

👑 MAINTAINERS 👑

Tony Bowden <tony@tmtm.com> and Perrin Harkins <perrin@elem.com>

---

🌸 ORIGINAL AUTHOR 🌸

Michael G Schwern <schwern@pobox.com>

---

🎀 LICENSE 🎀

This module is free software. You may distribute under the same terms as Perl itself. IT COMES WITHOUT WARRANTY OF ANY KIND. 🫶

💖 THANKS MUCHLY 💖

okay so real talk, this module did not appear out of thin air and we are absolutely giving credit where it's due 🫶

• Tim Bunce — for enduring many DBI questions (ngl, a true saint 😭) and for adding the Taint, prepare_cached and connect_cached methods to DBI, which simplified this whole thing greatly! like, genuinely iconic behaviour.
• Arena Networks — for effectively paying for Mike to write most of this module. yes bestie, that's called sponsorship and it ate 💅

---

🌈 SEE ALSO 🌈

• DBI.
• You may also choose to check out Class::DBI, which hides most of this from view. lowkey the "don't look behind the curtain" option 👀🦋

---

and that's the whole page, bestie — you made it to the end, main character energy fr fr 👑✨

this one's from perl v5.42.0, dated 2011-04-08, and it's the Ima::DBI(3) manpage 🎀 go forth and connect_cached responsibly 💅💖