--- name: "Alzabo::Driver" section: "3pm" platform: "linux" package: "libalzabo-perl" version: "0.92-6" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/Alzabo::Driver" --- # Alzabo::Driver(3pm) Alzabo base class for RDBMS drivers ## NAME Alzabo::Driver - Alzabo base class for RDBMS drivers ## SYNOPSIS ``` use Alzabo::Driver; my $driver = Alzabo::Driver->new( rdbms => 'MySQL', schema => $schema ); ``` ## DESCRIPTION This is the base class for all Alzabo::Driver modules. To instantiate a driver call this class's `"new()"` method. See SUBCLASSING Alzabo::Driver for information on how to make a driver for the RDBMS of your choice. This class throws several, exceptions, one of which, `"Alzabo::Exception::Driver"`, has additional methods not present in other exception classes. See "Alzabo::Exception::Driver METHODS" for a description of these methods. ## METHODS ### available Returns a list of names representing the available `"Alzabo::Driver"` subclasses. Any one of these names would be appropriate as the "rdbms" parameter for the `"Alzabo::Driver->new"` method. ### new The constructor takes the following parameters: - • rdbms =\> `$rdbms_name` The name of the RDBMS being used. - • schema =\> `"Alzabo::Schema"` object It returns a new `"Alzabo::Driver"` object of the appropriate subclass. Throws: `"Alzabo::Exception::Eval"` ### tables Returns a list of strings containing the names of the tables in the database. See the `"DBI"` documentation of the `"DBI->tables"` method for more details. Throws: `"Alzabo::Exception::Driver"` ### handle ($optional\_dbh) This method takes one optional parameter, a connected DBI handle. If this is given, then this handle is the new handle for the driver. It returns the active database handle. Throws: `"Alzabo::Exception::Params"` ### Data Retrieval methods Some of these methods return lists of data (the `"rows"`, `"rows_hashref"`, and `"column"` methods). With large result sets, this can use a lot memory as these lists are created in memory before being returned to the caller. To avoid this, it may be desirable to use the functionality provided by the `"Alzabo::DriverStatement"` class, which allows you to fetch results one row at a time. 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, depending on context. ### 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. Returns the number of rows affected. Throws: `"Alzabo::Exception::Driver"` ### statement This methods returns a new `"Alzabo::DriverStatement"` handle, ready to return 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. The form of this string will vary depending on which driver subclass is being used. ### quote (@strings) This methods calls the underlying DBI handles `"quote()"` method on the array of strings provided, and returns the quoted versions. ### quote\_identifier (@strings) This methods calls the underlying DBI handles `"quote_identifier()"` method on the array of strings provided, 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 need not worry about doing this. ### 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 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()"`. Returns a hash containing the next row of data for 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 is 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 (it was previously executed and has more data left) then its `"finish()"` method will be called first. Throws: `"Alzabo::Exception::Driver"` ### count Returns the number of rows returned so far. ## Alzabo::Exception::Driver METHODS In addition to the methods inherited from `"Exception::Class::Base"`, objects in this class also contain several methods specific to this subclass. ### sql Returns the SQL statement in use at the time the error occurred, if any. ### bind Returns an array reference contaning the bound parameters for the SQL statement, if any. ## SUBCLASSING Alzabo::Driver To create a subclass of `"Alzabo::Driver"` for your particular RDBMS is fairly simple. First of all, there must be a `"DBD::*"` driver for it, as `"Alzabo::Driver"` is built on top of `"DBI"`. 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); ``` The next step is to implement a `"new"` method and the methods listed under "Virtual Methods". The `"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. Look at the included `"Alzabo::Driver"` subclasses for examples. Feel free to contact me for further help if you get stuck. Please tell me what database you're attempting to implement, what its DBD::\* driver is, and include the code you've written so far. ### Virtual Methods The following methods are not implemented in `"Alzabo::Driver"` itself and must be implemented in a subclass. *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 don't call `"connect()"` more than once per process. ### 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. ### 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. ### 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. ### 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, \