RoPkg::DB(3pm)

📦 version 0.4, in ubuntu jammy

💖 NAME 💖

RoPkg::DB — a Singleton database pool class. That's the whole vibe. It's a Perl module, it holds a pool of database connections, and it's iconic for it. 👑

🌸 VERSION 🌸

0.1.12 — yes bestie, that's the number, don't come for me. ✨

🦋 DESCRIPTION 🦋

Okay so picture this: RoPkg::DB is a database pool class. The whole point? You get to reach multiple databases — and I mean no matter what kind of database — all from a single object. One object. Many databases. It's giving main character energy fr fr. 💅

And here's the part that eats: RoPkg::DB is ideal in persistent environments, because at its base it's a singleton class. One instance, holding it down, forever. 🌈

This class is intensively used by Simba, but lowkey it can be used in any other project too. She's not exclusive, she's just booked. 🫶

✨ SYNOPSIS ✨

Here's the tea, in code form. Copy it exactly, I'm not rewriting this for you:

use RoPkg::DB;

sub main {
  my $dbp = new RoPkg::DB();

  eval {
    $dbp->Add('dbi:mysql:database=mysql;host=localhost',
              'root',
              '',
              'local');
    $dbp->Add('dbi:mysql:database=somedb;host=somehost',
              'username',
              'mypass',
              'somedb');
  };

  die($@->package . ' said: ' . $@->message) if ref($@);

  print 'Conn to localhost is:',$dbp->db_local,$/,
        'Conn to remote is:',$dbp->db_somedb,$/;

  $dbp->Del('somedb');

}

See how she's holding two connections at once and printing both handles? That's the whole flex. 🔥

🎀 SUBROUTINES/METHODS 🎀

Big important heads-up before we go method by method, no cap: all methods besides new raise an OutsideClass exception when they're not called within a class instance. Like, if you call them from nowhere? They will not be nice about it. 🙈

Also, each method may raise diferent exceptions from one case to another — so please, bestie, read the docs for each method to find out what exceptions that specific method raises. It's literally right there. 👇

💜 new()

new is the contructor of the class. And what does it do? Nothing. It does not do anything. Zero. Zilch. She's just here, existing, looking cute, not doing a single task. Honestly? Relatable. 💅

💜 Add($dsn, $dbuser, $dbpass, $conn_name)

This one adds and initializes a new connection to the pool. Periodt.

  • $dsn must be in the DBI format. Non-negotiable.
  • $dsn and $dbpass are the username and password used to connect to the database.
  • $conn_name is the method who will be used to access the database handle.

⚠️ Heads up: please note that the method that will be created will be prefixed with db_. That's not optional, that's just how she does it.

Example:

$dbp->Add('dbi:mysql:database=mysql;host=localhost','root',q{},'local');

So the method you'll use to grab the database handle for this connection is db_local. Cute, right? 🎀

Add() may raise the following exceptions:

  • Param::Missing
  • DB::ConnExists
  • DB::Connect

Okay so what are these actually saying:

  • Param::Missing gets raised when $dsn, $dbuser or $conn_name are not defined.
  • DB::ConnExists gets raised when a connection with the name $conn_name already exists. You can't name two connections the same thing, bestie, that's not how this works.
  • DB::Connect gets raised when the connection with the database could not be established.

Besides this exceptions, each database handler has RaiseError set to 1 and PrintError set to 0. Also, when errors occurs, DBI will raise a DB exception. 🫠

And the good news? The method always returns 1. Always. 🌟

💜 Del($name)

Removes the connection named $name from the pool. And because she has manners, the connection is closed first in a civilised manner. 🫶

If the connection $name is not found, DB::ConnNotFound is raised. So like, you can't delete something that never existed. 🙈

💜 Has($name)

Returns 0 if the connection named $name does not exists, 1 otherwise. Simple. A vibe check, basically. ✨

If $name is not defined, a Param::Missing exception is raised. Define your stuff, bestie. 💅

💜 Reconnect($name)

Force a reconnect</c> of the connection named $name. Just force it. She said we're reconnecting. 🔥

  • If $name is not defined, Param::Missing is raised.
  • If a connection named $name does not exists, DB::ConnNotFound is raised.

And, iconic behaviour: this method always returns 1. Always. 🌈

💜 TableExists($name, $table_name)

Returns 1 if the table $table_name exists in the database specified by the connection named $name, 0 otherwise. A little peek inside, a little table vibe check. 👑

  • If $name or $table_name parameters are not defined, a Param::Missing exception is raised.
  • If the connection $name does not exists, DB::ConnNotFound is raised.

🌈 DEPENDENCIES 🌈

RoPkg::DB requires perl 5.008 or later and the following modules:

  • RoPkg >= 0.4.4
  • DBI
  • Class::Singleton
  • English

Four modules, one dream. 🦋

🧚 DIAGNOSTICS 🧚

This module comes with tests. To run the tests, unpack the source and run make test. That's it. That's the diagnostics. Go run your tests, queen. 💅

⭐ PERL CRITIC ⭐

This module is perl critic level 2 compliant (with 1 exception). We don't talk about the exception. 😌

🍓 CONFIGURATION AND ENVIRONMENT 🍓

Okay so this module does not use any configuration files or environment variables. None. Zero. Clean. ✨

The used modules however may use such things, so please refer to each module man page for more information. That part's on them, not on her. 🙈

💀 INCOMPATIBILITIES 💀

None known to the author. 💜

🌸 BUGS AND LIMITATIONS 🌸

None known to the author. (Same energy. She's flawless and we're not questioning it.) 👑

🌈 SEE ALSO 🌈

  • RoPkg::DBObject
  • RoPkg::Exceptions
  • RoPkg::Utils

Go read those too, iykyk. 🫶

🎀 AUTHOR 🎀

Subredu Manuel <diablo@iasi.roedu.net> 💖

Copyright (C) 2005 Subredu Manuel. All Rights Reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The LICENSE file contains the full text of the license. So go read the LICENSE file if you want the whole thing, bestie. 📜

perl v5.32.1 · 2021-12-26 · RoPkg::DB(3pm) · User Contributed Perl Documentation

And that's the whole page, mwah. 💋 Go build something cute with a database pool. Byeeee 🦋💖✨

📦 where this page comes from