Alzabo::Driver(3pm)

💖 Alzabo::Driver — the base class tea 💖

okay bestie, welcome to Alzabo::Driver(3pm) from the User Contributed Perl Documentation era ✨ this is the main character base class for every RDBMS driver in Alzabo, and we're gonna walk through it together, no cap 🫶

---

✨ NAME ✨

Alzabo::Driver — the Alzabo base class for RDBMS drivers 💅

---

🌸 SYNOPSIS 🌸

use Alzabo::Driver;

my $driver = Alzabo::Driver->new( rdbms => 'MySQL',
                                  schema => $schema );

---

🦋 DESCRIPTION 🦋

So this is the base class for all Alzabo::Driver modules. If you wanna actually instantiate a driver, you call this class's new() method, okay? And if you're out here wanting to build a driver for your own fave RDBMS, go peek at SUBCLASSING Alzabo::Driver below — it's got the whole blueprint 💖

This class throws several exceptions, and one of them, Alzabo::Exception::Driver, has extra methods that the other exception classes just don't have. For the rundown on those, scroll to "Alzabo::Exception::Driver METHODS" 🎀

---

👑 METHODS 👑

🌈 available

Returns a list of names representing the available Alzabo::Driver subclasses. Any one of these names would be a totally valid choice for the rdbms parameter you pass to the Alzabo::Driver->new method ⭐

💜 new

The constructor. It takes these parameters:

• rdbms => $rdbms_name — the name of the RDBMS being used.
• schema => Alzabo::Schema object — the schema, obviously 🎀

It returns a new Alzabo::Driver object of the appropriate subclass. Slay.

Throws: Alzabo::Exception::Eval

🍓 tables

Returns a list of strings containing the names of the tables in the database. If you want more deets, go read the DBI documentation for the DBI->tables method 💅

Throws: Alzabo::Exception::Driver

🧚 handle ($optional_dbh)

This method takes one optional parameter — a connected DBI handle. If you give it one, then that handle becomes the new handle for the driver. Yes bestie, it's a glow-up for your handle ✨

It returns the active database handle.

Throws: Alzabo::Exception::Params

🔥 Data Retrieval methods

Okay so heads up, some of these methods return lists of data — specifically the rows, rows_hashref, and column methods. And with large result sets? That can eat a lot of memory, because those lists get built in memory before they ever get returned to the caller 😭 To dodge that whole situation, it may be desirable to use the functionality provided by the Alzabo::DriverStatement class, which lets you fetch results one row at a time. one. row. at. a. time. periodt 💅

These methods all accept the following parameters:

• sql => $sql_string
• bind => $bind_value or \@bind_values
• limit => [ $max, optional $offset ] (optional) — the $offset defaults to 0. This parameter has no effect for the methods that return only one row. For the others, it causes the drivers to skip $offset rows and then return only $max rows. This is useful if the RDBMS being used does not support LIMIT clauses 🫶

⭐ rows

Returns an array of array references containing the data requested.

🌸 rows_hashref

Returns an array of hash references containing the data requested. The hash reference keys are the columns being selected. All the key names are in UPPERCASE.

🎀 one_row

Returns an array or scalar containing the data returned — depends on context, iykyk.

💖 one_row_hash

Returns a hash containing the data requested. The hash keys are the columns being selected. All the key names are in UPPERCASE.

🦋 column

Returns an array containing the values for the first column of each row returned.

💅 do

Use this for non-SELECT SQL statements, bestie. Not a select, not its vibe.

Returns the number of rows affected.

Throws: Alzabo::Exception::Driver

🌈 statement

This method returns a new Alzabo::DriverStatement handle, all ready to hand you data via the Alzabo::DriverStatement->next() or Alzabo::DriverStatement->next_as_hash() methods 💜

Throws: Alzabo::Exception::Driver

🧚 rdbms_version

Returns the version string of the database backend currently in use. Fair warning: the form of this string will vary depending on which driver subclass is being used — so don't expect a one-size-fits-all format 👑

🍓 quote (@strings)

This method calls the underlying DBI handle's quote() method on the array of strings you provide, and returns the quoted versions.

⭐ quote_identifier (@strings)

This method calls the underlying DBI handle's quote_identifier() method on the array of strings you provide, and returns the quoted versions.

---

🌸 Alzabo::DriverStatement 🌸

This class is a wrapper around DBI's statement handles 🎀 It finishes automatically as appropriate, so the end user does not need to worry about doing that themselves. We handle it. Main character energy.

💜 next

Use this method in a while loop to fetch all the data from a statement.

Returns an array containing the next row of data for the statement, or an empty list if no more data is available.

Throws: Alzabo::Exception::Driver

✨ next_as_hash

For backwards compatibility, this is also available as next_hash(). Love that for us.

Returns a hash containing the next row of data for the statement, or an empty list if no more data is available. All the keys of the hash will be lowercased.

Throws: Alzabo::Exception::Driver

🦋 all_rows

If the select for which this statement was the cursor was for a single column (or aggregate value), then this method returns an array containing each remaining value from the database.

Otherwise, it returns an array of array references, each one containing a returned row from the database.

Throws: Alzabo::Exception::Driver

🎀 all_rows_hash

Returns an array of hashes, each hash representing a single row returned from the database. The hash keys are all in lowercase.

Throws: Alzabo::Exception::Driver

🔥 execute (@bind_values)

Executes the associated statement handle with the given bound parameters. If the statement handle is still active (meaning it was previously executed and still has more data left), then its finish() method will be called first. Cleaning up before we move on, as we should 💅

Throws: Alzabo::Exception::Driver

🌈 count

Returns the number of rows returned so far.

---

💖 Alzabo::Exception::Driver METHODS 💖

On top of the methods inherited from Exception::Class::Base, objects in this class also contain several methods specific to this subclass. Extra. Special. Iconic.

💜 sql

Returns the SQL statement in use at the time the error occurred, if any.

🧚 bind

Returns an array reference containing the bound parameters for the SQL statement, if any.

---

👑 SUBCLASSING Alzabo::Driver 👑

Okay so making a subclass of Alzabo::Driver for your particular RDBMS is fairly simple, fr fr. First of all, there has to be a DBD::* driver for it, because Alzabo::Driver is built on top of DBI. No DBD, no driver, that's just the rules 🫶

Here's a sample header to the module using a fictional RDBMS called FooDB:

package Alzabo::Driver::FooDB;

use strict;
use vars qw($VERSION);

use Alzabo::Driver;

use DBI;
use DBD::FooDB;

use base qw(Alzabo::Driver);

Next step: implement a new method plus all the methods listed under "Virtual Methods". Your new method should look a bit like this:

1:  sub new
2:  {
3:      my $proto = shift;
4:      my $class = ref $proto || $proto;
5:      my %p = @_;
6:
7:      my $self = bless {}, $class;
8:
9:      return $self;
10:  }

The hash %p contains any values passed to the Alzabo::Driver->new method by its caller.

Lines 1-7 should probably be copied verbatim into your own new method. Line 5 can be deleted if you don't need to look at the parameters. We keep it simple, we keep it cute 🎀

Go look at the included Alzabo::Driver subclasses for examples. And feel free to contact the author for further help if you get stuck! Please tell them what database you're attempting to implement, what its DBD::* driver is, and include the code you've written so far. They wanna help you, bestie 💖

⭐ Virtual Methods

The following methods are not implemented in Alzabo::Driver itself and must be implemented in a subclass. That's on you, babes.

🌸 Parameters for connect(), create_database(), and drop_database()

• user => $db_username
• password => $db_pw
• host => $hostname
• port => $port

All of these default to undef. See the appropriate DBD driver documentation for more details.

After the driver is created, it will have access to its associated schema object in $self->{schema} 💅

🦋 connect

Some drivers may accept or require more arguments than specified above.

Note that Alzabo::Driver subclasses are not expected to cache connections. If you want to do this, please use Apache::DBI under mod_perl, or just don't call connect() more than once per process. Simple as that 🫶

💜 create_database

Attempts to create a new database for the schema attached to the driver. Some drivers may accept or require more arguments than specified above.

🎀 drop_database

Attempts to drop the database for the schema attached to the driver. bye bye database 👋

🌈 schemas

Returns a list of schemas in the specified RDBMS. This method may accept some or all of the parameters which can be given to connect().

🧚 supports_referential_integrity

Should return a boolean value indicating whether or not the RDBMS supports referential integrity constraints. yes/no, true/false, iconic 🦋

🔥 next_sequence_number (Alzabo::Column object)

This method is expected to return the value of the next sequence number based on a column object. For some databases (MySQL, for example), the appropriate value is undef. This is accounted for in the Alzabo code that calls this method, so don't stress ✨

⭐ begin_work

Notify Alzabo that you wish to start a transaction.

💅 rollback

Rolls back the current transaction.

🌸 commit

Notify Alzabo that you wish to finish a transaction. This is basically the equivalent of calling commit.

🍓 get_last_id

Returns the last primary key id created via a sequenced column.

👑 rdbms_version

Returns the version of the server to which the driver is connected.

💜 driver_id

Returns the driver's name. This should be something that can be passed to Alzabo::Driver->new() as a name parameter.

---

🎀 AUTHOR 🎀

Dave Rolsky, <dave@urth.org> 💖

---

and that's the whole page, bestie!! this beauty shipped as part of perl v5.34.0 back on 2022-06-14 — yes we're citing our sources, we're nothing if not thorough 💅✨💖