NAME

Alzabo::Driver - Alzabo base class for RDBMS drivers

SYNOPSIS

  use Alzabo::Driver;

  my $driver = Alzabo::Driver->new( driver => '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 the "SUBCLASSING Alzabo::Driver" section for information on how to make a driver for the RDBMS of your choice.

EXCEPTIONS

Alzabo::Driver::Exception - This is an error in database communications. This exception class has extra methods (see the "Alzabo::Driver::Exception METHODS" section.

VirtualMethodException - A method you called should have been subclassed in the Alzabo::Driver subclass you are using but it wasn't.

EvalException - An attempt to eval a string failed.

METHODS

• available

  Returns a list of strings listing the avaiable Alzabo::Driver subclasses. This is a class method.

• new

  Takes the following parameters:

• -- driver => $string

  A string giving the name of a driver to instantiate. Driver names are the name of the Alzabo::Driver subclass without the leading 'Alzabo::Driver::' part. For example, the driver name of the Alzabo::Driver::MySQL class is 'MySQL'.

• -- schema => Alzabo::Schema object

  This should be an Alzabo::Schema object (either Alzabo::Create::Schema or Alzabo::Runtime::Schema).

  The return value of this method is a new Alzabo::Driver object of the appropriate subclass.

• tables

  Returns a list of strings containing the names of the tables in the database. See the DBI documentation for more details.

Data Retrieval methods

Some of these methods return lists of data (the rows, rows_hashref, and column methods). With large result sets, this will increase memory usage for the list that is created as the return value. 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. This class is documented further on.

The following methods all take the same parameters:

-- sql => $sql_string

-- bind => $bind_value or \@bind_values

* rows

Executes a SQL statement with the given bind value(s) and returns an array of array references containing the data returned.

* rows_hashref

Executes a SQL statement with the given bind value(s) and returns an array of hash references containing the data returned.

* one_row

Executes a SQL statement with the given bind value(s) and returns an array or scalar containing the data returned, depending on context.

* one_row_hash

Executes a SQL statement with the given bind value(s) and returns a hash containing the data returned.

* column

Executes a SQL statement with the given bind value(s) and returns an array containing the values for the first column returned of each row.

* do

Executes a SQL statement with the given bind value(s) and returns the number of rows affected. Use this for non-SELECT SQL statements.

* statement

Returns a new Alzabo::DriverStatement handle, ready to return data via one of its next_row* methods.

Alzabo::DriverStatement

This class is a wrapper around DBI's statement handles. It finishes automatically as appropriate so the end user need not worry about doing this.

• next_row

   while (my @row = $statement->next_row) { ... }

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

• next_row_hash

   while (my %row = $statement->next_row_hash) { ... }

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

• execute (@bound_parameters)

  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.

Alzabo::Driver VIRTUAL METHODS

The following methods are not implemented in Alzabo::Driver itself and must be implemented in its subclasses.

The following two methods take these optional parameters:

-- host => $string

-- user => $string

-- password => $string

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.

* next_sequence_number (Alzabo::Column object)

This method is expected to return the value of the next sequence number based on a column object.

* start_transaction

<parameters not yet determined>

* rollback

Rolls back the current transaction.

* finish_transaction

<parameters not yet determined>

Commits a transaction.

* get_last_id

This returns the last primary key id created via a sequenced column.

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 the section "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:      $self->{prepare_method} = 'prepare';
 9:
 10:     return $self;
 11:  }

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 (which you probably don't).

Line 8 sets an internal hash entry. This is a string that defines which DBI method to use to prepare a statement. For some databases (such as Oracle), it may be advantageous to change this to 'prepare_cached'.

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.

AUTHOR

Dave Rolsky, <dave@urth.org>