Alzabo::Driver - 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

Parameters

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)

Parameters

This method takes one optional parameter, a connected DBI handle. If this is given, then this handle is the new handle for the driver.

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.

Parameters (for all methods below)

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

Parameters

$offset defaults to 0.

Returns

A new Alzabo::DriverStatement handle, ready to return data via the Alzabo::DriverStatement->next_row or Alzabo::DriverStatement->next_row_hash methods.

Throws

Alzabo::Exception::Driver


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_row

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

Throws

Alzabo::Exception::Driver

Returns

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

next_row_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 are in uppercase.

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


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

A list of the 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 the connect, create_database, and drop_database

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

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.

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 Alzabo code that calls this method.

start_transaction

Notify Alzabo that you wish to start a transaction.

Parameters

Not yet determined.

rollback

Rolls back the current transaction.

finish_transaction

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

Parameters

Not yet determined.

get_last_id

Returns

The last primary key id created via a sequenced column.


AUTHOR

Dave Rolsky, <dave@urth.org>

 Alzabo::Driver - Alzabo base class for RDBMS drivers