Provided by: libalzabo-perl_0.92-6_all 
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, <dave@urth.org>