Alzabo::Driver - Alzabo base class for RDBMS drivers

  use Alzabo::Driver;

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

This is the base class for all Alzabo::Driver modules. To instantiate a driver call this class's CWnew() 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, CWAlzabo::Exception::Driver, has additional methods not present in other exception classes. See Alzabo::Exception::Driver METHODS for a description of these methods.

Returns a list of names representing the available CWAlzabo::Driver subclasses. Any one of these names would be appropriate as the rdbms parameter for the CWAlzabo::Driver->new method.

The constructor takes the following parameters: The name of the RDBMS being used.

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

Throws: CWAlzabo::Exception::Eval

Returns a list of strings containing the names of the tables in the database. See the CWDBI documentation of the CWDBI->tables method for more details.

Throws: CWAlzabo::Exception::Driver

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: CWAlzabo::Exception::Params

Some of these methods return lists of data (the CWrows, CWrows_hashref, and CWcolumn 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 CWAlzabo::DriverStatement class, which allows you to fetch results one row at a time.

These methods all accept the following parameters: The CW$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 CW$offset rows and then return only CW$max rows. This is useful if the RDBMS being used does not support CWLIMIT clauses.

Returns an array of array references containing the data requested.

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.

Returns an array or scalar containing the data returned, depending on context.

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

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

Use this for non-SELECT SQL statements.

Returns the number of rows affected.

Throws: CWAlzabo::Exception::Driver

This methods returns a new CWAlzabo::DriverStatement handle, ready to return data via the CWAlzabo::DriverStatement->next() or CWAlzabo::DriverStatement->next_as_hash() methods.

Throws: CWAlzabo::Exception::Driver

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.

This methods calls the underlying DBI handles CWquote() method on the array of strings provided, and returns the quoted versions.

This methods calls the underlying DBI handles CWquote_identifier() method on the array of strings provided, and returns the quoted versions.

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

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: CWAlzabo::Exception::Driver

For backwards compatibility, this is also available as CWnext_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: CWAlzabo::Exception::Driver

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: CWAlzabo::Exception::Driver

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

Throws: CWAlzabo::Exception::Driver

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 CWfinish() method will be called first.

Throws: CWAlzabo::Exception::Driver

Returns the number of rows returned so far.

In addition to the methods inherited from CWException::Class::Base, objects in this class also contain several methods specific to this subclass.

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

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

To create a subclass of CWAlzabo::Driver for your particular RDBMS is fairly simple. First of all, there must be a CWDBD::* driver for it, as CWAlzabo::Driver is built on top of CWDBI.

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 CWnew method and the methods listed under Virtual Methods. The CWnew 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 CW%p contains any values passed to the CWAlzabo::Driver->new method by its caller.

Lines 1-7 should probably be copied verbatim into your own CWnew method. Line 5 can be deleted if you don't need to look at the parameters.

Look at the included CWAlzabo::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.

The following methods are not implemented in CWAlzabo::Driver itself and must be implemented in a subclass.

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

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 CW$self->{schema}.

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

Note that CWAlzabo::Driver subclasses are not expected to cache connections. If you want to do this please use CWApache::DBI under mod_perl or don't call CWconnect() more than once per process.

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

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

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

Should return a boolean value indicating whether or not the RDBMS supports referential integrity constraints. 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 CWundef. This is accounted for in the Alzabo code that calls this method.

Notify Alzabo that you wish to start a transaction.

Rolls back the current transaction.

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

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

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

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

Dave Rolsky, <dave@urth.org>