.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Alzabo::Driver 3pm"
.TH Alzabo::Driver 3pm "2021-01-08" "perl v5.32.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Alzabo::Driver \- Alzabo base class for RDBMS drivers
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Alzabo::Driver;
\&
\&  my $driver = Alzabo::Driver\->new( rdbms => \*(AqMySQL\*(Aq,
\&                                    schema => $schema );
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This is the base class for all Alzabo::Driver modules.  To instantiate
a driver call this class's \f(CW\*(C`new()\*(C'\fR method.  See \s-1SUBCLASSING\s0
Alzabo::Driver for information on how to make a driver for the \s-1RDBMS\s0
of your choice.
.PP
This class throws several, exceptions, one of which,
\&\f(CW\*(C`Alzabo::Exception::Driver\*(C'\fR, has additional methods not present in
other exception classes.  See \*(L"Alzabo::Exception::Driver \s-1METHODS\*(R"\s0 for
a description of these methods.
.SH "METHODS"
.IX Header "METHODS"
.SS "available"
.IX Subsection "available"
Returns a list of names representing the available \f(CW\*(C`Alzabo::Driver\*(C'\fR
subclasses.  Any one of these names would be appropriate as the
\&\*(L"rdbms\*(R" parameter for the \f(CW\*(C`Alzabo::Driver\->new\*(C'\fR method.
.SS "new"
.IX Subsection "new"
The constructor takes the following parameters:
.IP "\(bu" 4
rdbms => \f(CW$rdbms_name\fR
.Sp
The name of the \s-1RDBMS\s0 being used.
.IP "\(bu" 4
schema => \f(CW\*(C`Alzabo::Schema\*(C'\fR object
.PP
It returns a new \f(CW\*(C`Alzabo::Driver\*(C'\fR object of the appropriate subclass.
.PP
Throws: \f(CW\*(C`Alzabo::Exception::Eval\*(C'\fR
.SS "tables"
.IX Subsection "tables"
Returns a list of strings containing the names of the tables in the
database.  See the \f(CW\*(C`DBI\*(C'\fR documentation of the \f(CW\*(C`DBI\->tables\*(C'\fR
method for more details.
.PP
Throws: \f(CW\*(C`Alzabo::Exception::Driver\*(C'\fR
.SS "handle ($optional_dbh)"
.IX Subsection "handle ($optional_dbh)"
This method takes one optional parameter, a connected \s-1DBI\s0 handle.  If
this is given, then this handle is the new handle for the driver.
.PP
It returns the active database handle.
.PP
Throws: \f(CW\*(C`Alzabo::Exception::Params\*(C'\fR
.SS "Data Retrieval methods"
.IX Subsection "Data Retrieval methods"
Some of these methods return lists of data (the
\&\f(CW\*(C`rows\*(C'\fR,
\&\f(CW\*(C`rows_hashref\*(C'\fR, and
\&\f(CW\*(C`column\*(C'\fR 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
\&\f(CW\*(C`Alzabo::DriverStatement\*(C'\fR class, which
allows you to fetch results one row at a time.
.PP
These methods all accept the following parameters:
.IP "\(bu" 4
sql => \f(CW$sql_string\fR
.IP "\(bu" 4
bind => \f(CW$bind_value\fR or \e@bind_values
.IP "\(bu" 4
limit => [ \f(CW$max\fR, optional \f(CW$offset\fR ] (optional)
.Sp
The \f(CW$offset\fR defaults to 0.
.Sp
This parameter has no effect for the methods that return only one
row.  For the others, it causes the drivers to skip \f(CW$offset\fR rows
and then return only \f(CW$max\fR rows.  This is useful if the \s-1RDBMS\s0 being
used does not support \f(CW\*(C`LIMIT\*(C'\fR clauses.
.SS "rows"
.IX Subsection "rows"
Returns an array of array references containing the data requested.
.SS "rows_hashref"
.IX Subsection "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.
.SS "one_row"
.IX Subsection "one_row"
Returns an array or scalar containing the data returned, depending on
context.
.SS "one_row_hash"
.IX Subsection "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.
.SS "column"
.IX Subsection "column"
Returns an array containing the values for the first column of each
row returned.
.SS "do"
.IX Subsection "do"
Use this for non-SELECT \s-1SQL\s0 statements.
.PP
Returns the number of rows affected.
.PP
Throws: \f(CW\*(C`Alzabo::Exception::Driver\*(C'\fR
.SS "statement"
.IX Subsection "statement"
This methods returns a new
\&\f(CW\*(C`Alzabo::DriverStatement\*(C'\fR handle, ready to
return data via the \f(CW\*(C`Alzabo::DriverStatement\->next()\*(C'\fR or \f(CW\*(C`Alzabo::DriverStatement\->next_as_hash()\*(C'\fR methods.
.PP
Throws: \f(CW\*(C`Alzabo::Exception::Driver\*(C'\fR
.SS "rdbms_version"
.IX Subsection "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.
.SS "quote (@strings)"
.IX Subsection "quote (@strings)"
This methods calls the underlying \s-1DBI\s0 handles \f(CW\*(C`quote()\*(C'\fR method on the
array of strings provided, and returns the quoted versions.
.SS "quote_identifier (@strings)"
.IX Subsection "quote_identifier (@strings)"
This methods calls the underlying \s-1DBI\s0 handles \f(CW\*(C`quote_identifier()\*(C'\fR
method on the array of strings provided, and returns the quoted
versions.
.SH "Alzabo::DriverStatement"
.IX Header "Alzabo::DriverStatement"
This class is a wrapper around \f(CW\*(C`DBI\*(C'\fR's statement handles.  It finishes
automatically as appropriate so the end user does need not worry about
doing this.
.SS "next"
.IX Subsection "next"
Use this method in a while loop to fetch all the data from a
statement.
.PP
Returns an array containing the next row of data for statement or an
empty list if no more data is available.
.PP
Throws: \f(CW\*(C`Alzabo::Exception::Driver\*(C'\fR
.SS "next_as_hash"
.IX Subsection "next_as_hash"
For backwards compatibility, this is also available as \f(CW\*(C`next_hash()\*(C'\fR.
.PP
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.
.PP
Throws: \f(CW\*(C`Alzabo::Exception::Driver\*(C'\fR
.SS "all_rows"
.IX Subsection "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 \fBremaining\fR value from the database.
.PP
Otherwise, it returns an array of array references, each one
containing a returned row from the database.
.PP
Throws: \f(CW\*(C`Alzabo::Exception::Driver\*(C'\fR
.SS "all_rows_hash"
.IX Subsection "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.
.PP
Throws: \f(CW\*(C`Alzabo::Exception::Driver\*(C'\fR
.SS "execute (@bind_values)"
.IX Subsection "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 \f(CW\*(C`finish()\*(C'\fR
method will be called first.
.PP
Throws: \f(CW\*(C`Alzabo::Exception::Driver\*(C'\fR
.SS "count"
.IX Subsection "count"
Returns the number of rows returned so far.
.SH "Alzabo::Exception::Driver METHODS"
.IX Header "Alzabo::Exception::Driver METHODS"
In addition to the methods inherited from
\&\f(CW\*(C`Exception::Class::Base\*(C'\fR, objects in this
class also contain several methods specific to this subclass.
.SS "sql"
.IX Subsection "sql"
Returns the \s-1SQL\s0 statement in use at the time the error occurred, if
any.
.SS "bind"
.IX Subsection "bind"
Returns an array reference contaning the bound parameters for the \s-1SQL\s0
statement, if any.
.SH "SUBCLASSING Alzabo::Driver"
.IX Header "SUBCLASSING Alzabo::Driver"
To create a subclass of \f(CW\*(C`Alzabo::Driver\*(C'\fR for your particular \s-1RDBMS\s0 is
fairly simple.  First of all, there must be a \f(CW\*(C`DBD::*\*(C'\fR driver for it,
as \f(CW\*(C`Alzabo::Driver\*(C'\fR is built on top of \f(CW\*(C`DBI\*(C'\fR.
.PP
Here's a sample header to the module using a fictional \s-1RDBMS\s0 called FooDB:
.PP
.Vb 1
\& package Alzabo::Driver::FooDB;
\&
\& use strict;
\& use vars qw($VERSION);
\&
\& use Alzabo::Driver;
\&
\& use DBI;
\& use DBD::FooDB;
\&
\& use base qw(Alzabo::Driver);
.Ve
.PP
The next step is to implement a \f(CW\*(C`new\*(C'\fR method and the methods listed
under \*(L"Virtual Methods\*(R".  The \f(CW\*(C`new\*(C'\fR method should look a bit like
this:
.PP
.Vb 10
\& 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:  }
.Ve
.PP
The hash \f(CW%p\fR contains any values passed to the
\&\f(CW\*(C`Alzabo::Driver\->new\*(C'\fR method by its caller.
.PP
Lines 1\-7 should probably be copied verbatim into your own \f(CW\*(C`new\*(C'\fR
method.  Line 5 can be deleted if you don't need to look at the
parameters.
.PP
Look at the included \f(CW\*(C`Alzabo::Driver\*(C'\fR 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.
.SS "Virtual Methods"
.IX Subsection "Virtual Methods"
The following methods are not implemented in \f(CW\*(C`Alzabo::Driver\*(C'\fR itself
and must be implemented in a subclass.
.PP
\fIParameters for \f(BIconnect()\fI, \f(BIcreate_database()\fI, and \f(BIdrop_database()\fI\fR
.IX Subsection "Parameters for connect(), create_database(), and drop_database()"
.IP "\(bu" 4
user => \f(CW$db_username\fR
.IP "\(bu" 4
password => \f(CW$db_pw\fR
.IP "\(bu" 4
host => \f(CW$hostname\fR
.IP "\(bu" 4
port => \f(CW$port\fR
.PP
All of these default to undef.  See the appropriate \s-1DBD\s0 driver
documentation for more details.
.PP
After the driver is created, it will have access to its associated
schema object in \f(CW\*(C`$self\->{schema}\*(C'\fR.
.SS "connect"
.IX Subsection "connect"
Some drivers may accept or require more arguments than specified
above.
.PP
Note that \f(CW\*(C`Alzabo::Driver\*(C'\fR subclasses are not expected to cache
connections.  If you want to do this please use \f(CW\*(C`Apache::DBI\*(C'\fR under
mod_perl or don't call \f(CW\*(C`connect()\*(C'\fR more than once per process.
.SS "create_database"
.IX Subsection "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.
.SS "drop_database"
.IX Subsection "drop_database"
Attempts to drop the database for the schema attached to the driver.
.SS "schemas"
.IX Subsection "schemas"
Returns a list of schemas in the specified \s-1RDBMS.\s0  This method may
accept some or all of the parameters which can be given to
\&\f(CW\*(C`connect()\*(C'\fR.
.SS "supports_referential_integrity"
.IX Subsection "supports_referential_integrity"
Should return a boolean value indicating whether or not the \s-1RDBMS\s0
supports referential integrity constraints.
.ie n .SS "next_sequence_number (""Alzabo::Column"" object)"
.el .SS "next_sequence_number (\f(CWAlzabo::Column\fP object)"
.IX Subsection "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 \f(CW\*(C`undef\*(C'\fR.  This is accounted for in
the Alzabo code that calls this method.
.SS "begin_work"
.IX Subsection "begin_work"
Notify Alzabo that you wish to start a transaction.
.SS "rollback"
.IX Subsection "rollback"
Rolls back the current transaction.
.SS "commit"
.IX Subsection "commit"
Notify Alzabo that you wish to finish a transaction.  This is
basically the equivalent of calling commit.
.SS "get_last_id"
.IX Subsection "get_last_id"
Returns the last primary key id created via a sequenced column.
.SS "rdbms_version"
.IX Subsection "rdbms_version"
Returns the version of the server to which the driver is connected.
.SS "driver_id"
.IX Subsection "driver_id"
Returns the driver's name.  This should be something that can be
passed to \f(CW\*(C`Alzabo::Driver\->new()\*(C'\fR as a \*(L"name\*(R" parameter.
.SH "AUTHOR"
.IX Header "AUTHOR"
Dave Rolsky, <dave@urth.org>