package DBI::DBD;
# vim:ts=8:sw=4
use vars qw($VERSION); # set $VERSION early so we don't confuse PAUSE/CPAN etc
# don't use Revision here because that's not in svn:keywords so that the
# examples that use it below won't be messed up
$VERSION = sprintf("12.%06d", q$Id: DBD.pm 11723 2008-09-02 10:09:51Z mjevans $ =~ /(\d+)/o);
# $Id: DBD.pm 11723 2008-09-02 10:09:51Z mjevans $
#
# Copyright (c) 1997-2006 Jonathan Leffler, Jochen Wiedmann, Steffen
# Goeldner and Tim Bunce
#
# You may distribute under the terms of either the GNU General Public
# License or the Artistic License, as specified in the Perl README file.
=head1 NAME
DBI::DBD - Perl DBI Database Driver Writer's Guide
=head1 SYNOPSIS
perldoc DBI::DBD
=head2 Version and volatility
This document is I a minimal draft which is in need of further work.
The changes will occur both because the B specification is changing
and hence the requirements on B drivers change, and because feedback
from people reading this document will suggest improvements to it.
Please read the B documentation first and fully, including the B FAQ.
Then reread the B specification again as you're reading this. It'll help.
This document is a patchwork of contributions from various authors.
More contributions (preferably as patches) are very welcome.
=head1 DESCRIPTION
This document is primarily intended to help people writing new
database drivers for the Perl Database Interface (Perl DBI).
It may also help others interested in discovering why the internals of
a B driver are written the way they are.
This is a guide. Few (if any) of the statements in it are completely
authoritative under all possible circumstances. This means you will
need to use judgement in applying the guidelines in this document.
If in I doubt at all, please do contact the I mailing list
(details given below) where Tim Bunce and other driver authors can help.
=head1 CREATING A NEW DRIVER
The first rule for creating a new database driver for the Perl DBI is
very simple: B
There is usually a driver already available for the database you want
to use, almost regardless of which database you choose. Very often, the
database will provide an ODBC driver interface, so you can often use
B to access the database. This is typically less convenient
on a Unix box than on a Microsoft Windows box, but there are numerous
options for ODBC driver managers on Unix too, and very often the ODBC
driver is provided by the database supplier.
Before deciding that you need to write a driver, do your homework to
ensure that you are not wasting your energies.
[As of December 2002, the consensus is that if you need an ODBC driver
manager on Unix, then the unixODBC driver (available from
L) is the way to go.]
The second rule for creating a new database driver for the Perl DBI is
also very simple: B
Nevertheless, there are occasions when it is necessary to write a new
driver, often to use a proprietary language or API to access the
database more swiftly, or more comprehensively, than an ODBC driver can.
Then you should read this document very carefully, but with a suitably
sceptical eye.
If there is something in here that does not make any sense, question it.
You might be right that the information is bogus, but don't come to that
conclusion too quickly.
=head2 URLs and mailing lists
The primary web-site for locating B software and information is
http://dbi.perl.org/
There are two main and one auxiliary mailing lists for people working
with B. The primary lists are I for general users
of B and B drivers, and I mainly for B driver
writers (don't join the I list unless you have a good reason).
The auxiliary list is I for announcing new
releases of B or B drivers.
You can join these lists by accessing the web-site L.
The lists are closed so you cannot send email to any of the lists
unless you join the list first.
You should also consider monitoring the I newsgroups,
especially I.
=head2 The Cheetah book
The definitive book on Perl DBI is the Cheetah book, so called because
of the picture on the cover. Its proper title is 'I' by Alligator Descartes
and Tim Bunce, published by O'Reilly Associates, February 2000, ISBN
1-56592-699-4. Buy it now if you have not already done so, and read it.
=head2 Locating drivers
Before writing a new driver, it is in your interests to find out
whether there already is a driver for your database. If there is such
a driver, it would be much easier to make use of it than to write your
own!
The primary web-site for locating Perl software is
L. You should look under the various
modules listings for the software you are after. For example:
http://search.cpan.org/modlist/Database_Interfaces
Follow the B and B links at the top to see those subsets.
See the B docs for information on B web sites and mailing lists.
=head2 Registering a new driver
Before going through any official registration process, you will need
to establish that there is no driver already in the works. You'll do
that by asking the B mailing lists whether there is such a driver
available, or whether anybody is working on one.
When you get the go ahead, you will need to establish the name of the
driver and a prefix for the driver. Typically, the name is based on the
name of the database software it uses, and the prefix is a contraction
of that. Hence, B has the name I and the prefix
'I'. The prefix must be lowercase and contain no underscores other
than the one at the end.
This information will be recorded in the B module. Apart from
documentation purposes, registration is a prerequisite for
L.
If you are writing a driver which will not be distributed on CPAN, then
you should choose a prefix beginning with 'I', to avoid potential
prefix collisions with drivers registered in the future. Thus, if you
wrote a non-CPAN distributed driver called B, the prefix
might be 'I'.
This document assumes you are writing a driver called B, and
that the prefix 'I' is assigned to the driver.
=head2 Two styles of database driver
There are two distinct styles of database driver that can be written to
work with the Perl DBI.
Your driver can be written in pure Perl, requiring no C compiler.
When feasible, this is the best solution, but most databases are not
written in such a way that this can be done. Some examples of pure
Perl drivers are B and B.
Alternatively, and most commonly, your driver will need to use some C
code to gain access to the database. This will be classified as a C/XS
driver.
=head2 What code will you write?
There are a number of files that need to be written for either a pure
Perl driver or a C/XS driver. There are no extra files needed only by
a pure Perl driver, but there are several extra files needed only by a
C/XS driver.
=head3 Files common to pure Perl and C/XS drivers
Assuming that your driver is called B, these files are:
=over 4
=item * F
=item * F
=item * F
=item * F
=item * F
=item * F
=item * F
=item * F
=back
The first four files are mandatory. F is used to control
how the driver is built and installed. The F file tells people
who download the file about how to build the module and any prerequisite
software that must be installed. The F file is used by the
standard Perl module distribution mechanism. It lists all the source
files that need to be distributed with your module. F is what
is loaded by the B code; it contains the methods peculiar to your
driver.
Although the F file is not B you are advised to
create one. Of particular importance are the I and
I attributes which newer CPAN modules understand.
You use these to tell the CPAN module (and CPANPLUS) that your build
and configure mechanisms require DBI. The best reference for META.yml
(at the time of writing) is
L. You can find
a reasonable example of a F in DBD::ODBC.
The F file allows you to specify other Perl
modules on which yours depends in a format that allows someone to type a
simple command and ensure that all the pre-requisites are in place as
well as building your driver.
The F file contains (an updated version of) the
information that was included - or that would have been included - in
the appendices of the Cheetah book as a summary of the abilities of your
driver and the associated database.
The files in the F subdirectory are unit tests for your driver.
You should write your tests as stringently as possible, while taking
into account the diversity of installations that you can encounter:
=over 4
=item *
Your tests should not casually modify operational databases.
=item *
You should never damage existing tables in a database.
=item *
You should code your tests to use a constrained name space within the
database. For example, the tables (and all other named objects) that are
created could all begin with 'I'.
=item *
At the end of a test run, there should be no testing objects left behind
in the database.
=item *
If you create any databases, you should remove them.
=item *
If your database supports temporary tables that are automatically
removed at the end of a session, then exploit them as often as possible.
=item *
Try to make your tests independent of each other. If you have a
test F that depends upon the successful running
of F, people cannot run the single test case
F. Further, running F twice in a row is
likely to fail (at least, if F modifies the database at
all) because the database at the start of the second run is not what you
saw at the start of the first run.
=item *
Document in your F file what you do, and what privileges people
need to do it.
=item *
You can, and probably should, sequence your tests by including a test
number before an abbreviated version of the test name; the tests are run
in the order in which the names are expanded by shell-style globbing.
=item *
It is in your interests to ensure that your tests work as widely
as possible.
=back
Many drivers also install sub-modules B
for any of a variety of different reasons, such as to support
the metadata methods (see the discussion of L
below). Such sub-modules are conventionally stored in the directory
F. The module itself would usually be in a file
F. All such sub-modules should themselves be version
stamped (see the discussions far below).
=head3 Extra files needed by C/XS drivers
The software for a C/XS driver will typically contain at least four
extra files that are not relevant to a pure Perl driver.
=over 4
=item * F
=item * F
=item * F
=item * F
=back
The F file is used to generate C code that Perl can call to gain
access to the C functions you write that will, in turn, call down onto
your database software.
The F header is a stylized header that ensures you can access the
necessary Perl and B macros, types, and function declarations.
The F is used to specify which functions have been implemented by
your driver.
The F file is where you write the C code that does the real work
of translating between Perl-ish data types and what the database expects
to use and return.
There are some (mainly small, but very important) differences between
the contents of F and F for pure Perl and C/XS
drivers, so those files are described both in the section on creating a
pure Perl driver and in the section on creating a C/XS driver.
Obviously, you can add extra source code files to the list.
=head2 Requirements on a driver and driver writer
To be remotely useful, your driver must be implemented in a format that
allows it to be distributed via CPAN, the Comprehensive Perl Archive
Network (L and L).
Of course, it is easier if you do not have to meet this criterion, but
you will not be able to ask for much help if you do not do so, and
no-one is likely to want to install your module if they have to learn a
new installation mechanism.
=head1 CREATING A PURE PERL DRIVER
Writing a pure Perl driver is surprisingly simple. However, there are
some problems you should be aware of. The best option is of course
picking up an existing driver and carefully modifying one method
after the other.
Also look carefully at B and B.
As an example we take a look at the B driver, a driver for
accessing plain files as tables, which is part of the B package.
The minimal set of files we have to implement are F,
F, F and F.
=head2 Pure Perl version of Makefile.PL
You typically start with writing F, a Makefile
generator. The contents of this file are described in detail in
the L man pages. It is definitely a good idea
if you start reading them. At least you should know about the
variables I, I, I, I, I,
I, I, I, I, I, I,
I, I, I, I, I from
the L man page: these are used in almost any
F.
Additionally read the section on I and the
descriptions of the I, I and I targets: They
will definitely be useful for you.
Of special importance for B drivers is the I method from
the L man page.
For Emacs users, I recommend the I method, which removes
Emacs backup files (file names which end with a tilde '~') from lists of
files.
Now an example, I use the word C wherever you should insert
your driver's name:
# -*- perl -*-
use ExtUtils::MakeMaker;
WriteMakefile(
dbd_edit_mm_attribs( {
'NAME' => 'DBD::Driver',
'VERSION_FROM' => 'Driver.pm',
'INC' => '',
'dist' => { 'SUFFIX' => '.gz',
'COMPRESS' => 'gzip -9f' },
'realclean' => { FILES => '*.xsi' },
'PREREQ_PM' => '1.03',
'CONFIGURE' => sub {
eval {require DBI::DBD;};
if ($@) {
warn $@;
exit 0;
}
my $dbi_arch_dir = dbd_dbi_arch_dir();
if (exists($opts{INC})) {
return {INC => "$opts{INC} -I$dbi_arch_dir"};
} else {
return {INC => "-I$dbi_arch_dir"};
}
}
},
{ create_pp_tests => 1})
);
package MY;
sub postamble { return main::dbd_postamble(@_); }
sub libscan {
my ($self, $path) = @_;
($path =~ m/\~$/) ? undef : $path;
}
Note the calls to C and C.
The second hash reference in the call to C
(containing C) is optional; you should not use it
unless your driver is a pure Perl driver (that is, it does not use C and
XS code). Therefore, the call to C is not
relevant for C/XS drivers and may be omitted; simply use the (single)
hash reference containing NAME etc as the only argument to C.
Note that the C code will fail if you do not have a
F sub-directory containing at least one test case.
I tells MakeMaker that DBI (version 1.03 in this case) is
required for this module. This will issue a warning that DBI 1.03 is
missing if someone attempts to install your DBD without DBI 1.03. See
I below for why this does not work reliably in stopping cpan
testers failing your module if DBI is not installed.
I is a subroutine called by MakeMaker during
C. By putting the C in this section
we can attempt to load DBI::DBD but if it is missing we exit with
success. As we exit successfully without creating a Makefile when
DBI::DBD is missing cpan testers will not report a failure. This may
seem at odds with I but I does not cause
C to fail (unless you also specify PREREQ_FATAL which
is strongly discouraged by MakeMaker) so C would
continue to call C and fail.
All drivers must use C or risk running into problems.
Note the specification of I; the named file
(F) will be scanned for the first line that looks like an
assignment to I<$VERSION>, and the subsequent text will be used to
determine the version number. Note the commentary in
L on the subject of correctly formatted version
numbers.
If your driver depends upon external software (it usually will), you
will need to add code to ensure that your environment is workable
before the call to C. If you need to check for the
existence of an external library and perhaps modify I to include
the paths to where the external library header files are located and
you cannot find the library or header files make sure you output a
message saying they cannot be found but C (success) B
calling C or CPAN testers will fail your module if the
external library is not found.
A full-fledged I can be quite large (for example, the
files for B and B are both over 1000 lines
long, and the Informix one uses - and creates - auxiliary modules
too).
See also L and L. Consider using
L in place of I.
=head2 README
The L file should describe what the driver is for, the
pre-requisites for the build process, the actual build process, how to
report errors, and who to report them to.
Users will find ways of breaking the driver build and test process
which you would never even have dreamed to be possible in your worst
nightmares. Therefore, you need to write this document defensively,
precisely and concisely.
As always, use the F from one of the established drivers as a basis
for your own; the version in B is worth a look as it has
been quite successful in heading off problems.
=over 4
=item *
Note that users will have versions of Perl and B that are both older
and newer than you expected, but this will seldom cause much trouble.
When it does, it will be because you are using features of B that are
not supported in the version they are using.
=item *
Note that users will have versions of the database software that are
both older and newer than you expected. You will save yourself time in
the long run if you can identify the range of versions which have been
tested and warn about versions which are not known to be OK.
=item *
Note that many people trying to install your driver will not be experts
in the database software.
=item *
Note that many people trying to install your driver will not be experts
in C or Perl.
=back
=head2 MANIFEST
The F will be used by the Makefile's dist target to build the
distribution tar file that is uploaded to CPAN. It should list every
file that you want to include in your distribution, one per line.
=head2 lib/Bundle/DBD/Driver.pm
The CPAN module provides an extremely powerful bundle mechanism that
allows you to specify pre-requisites for your driver.
The primary pre-requisite is B; you may want or need to add
some more. With the bundle set up correctly, the user can type:
perl -MCPAN -e 'install Bundle::DBD::Driver'
and Perl will download, compile, test and install all the Perl modules
needed to build your driver.
The prerequisite modules are listed in the C section, with the
official name of the module followed by a dash and an informal name or
description.
=over 4
=item *
Listing B as the main pre-requisite simplifies life.
=item *
Don't forget to list your driver.
=item *
Note that unless the DBMS is itself a Perl module, you cannot list it as
a pre-requisite in this file.
=item *
You should keep the version of the bundle the same as the version of
your driver.
=item *
You should add configuration management, copyright, and licencing
information at the top.
=back
A suitable skeleton for this file is shown below.
package Bundle::DBD::Driver;
$VERSION = '0.01';
1;
__END__
=head1 NAME
Bundle::DBD::Driver - A bundle to install all DBD::Driver related modules
=head1 SYNOPSIS
C
=head1 CONTENTS
Bundle::DBI - Bundle for DBI by TIMB (Tim Bunce)
DBD::Driver - DBD::Driver by YOU (Your Name)
=head1 DESCRIPTION
This bundle includes all the modules used by the Perl Database
Interface (DBI) driver for Driver (DBD::Driver), assuming the
use of DBI version 1.13 or later, created by Tim Bunce.
If you've not previously used the CPAN module to install any
bundles, you will be interrogated during its setup phase.
But when you've done it once, it remembers what you told it.
You could start by running:
C
=head1 SEE ALSO
Bundle::DBI
=head1 AUTHOR
Your Name EFE
=head1 THANKS
This bundle was created by ripping off Bundle::libnet created by
Graham Barr EFE, and radically simplified
with some information from Jochen Wiedmann EFE.
The template was then included in the DBI::DBD documentation by
Jonathan Leffler EFE.
=cut
=head2 lib/DBD/Driver/Summary.pm
There is no substitute for taking the summary file from a driver that
was documented in the Perl book (such as B or B or
B, to name but three), and adapting it to describe the
facilities available via B when accessing the Driver database.
=head2 Pure Perl version of Driver.pm
The F file defines the Perl module B for your driver.
It will define a package B along with some version information,
some variable definitions, and a function C which will have a more
or less standard structure.
It will also define three sub-packages of B:
=over 4
=item DBD::Driver::dr
with methods C, C and C;
=item DBD::Driver::db
with methods such as C;
=item DBD::Driver::st
with methods such as C and C.
=back
The F file will also contain the documentation specific to
B in the format used by perldoc.
In a pure Perl driver, the F file is the core of the
implementation. You will need to provide all the key methods needed by B.
Now let's take a closer look at an excerpt of F as an example.
We ignore things that are common to any module (even non-DBI modules)
or really specific to the B package.
=head3 The DBD::Driver package
=head4 The header
package DBD::File;
use strict;
use vars qw($VERSION $drh);
$VERSION = "1.23.00" # Version number of DBD::File
This is where the version number of your driver is specified, and is
where F looks for this information. Please ensure that any
other modules added with your driver are also version stamped so that
CPAN does not get confused.
It is recommended that you use a two-part (1.23) or three-part (1.23.45)
version number. Also consider the CPAN system, which gets confused and
considers version 1.10 to precede version 1.9, so that using a raw CVS,
RCS or SCCS version number is probably not appropriate (despite being
very common).
For Subversion you could use:
$VERSION = sprintf("12.%06d", q$Revision: 12345 $ =~ /(\d+)/o);
(use lots of leading zeros on the second portion so if you move the code to a
shared repository like svn.perl.org the much larger revision numbers won't
cause a problem, at least not for a few years). For RCS or CVS you can use:
$VERSION = sprintf "%d.%02d", '$Revision: 11.21 $ ' =~ /(\d+)\.(\d+)/;
which pads out the fractional part with leading zeros so all is well
(so long as you don't go past x.99)
$drh = undef; # holds driver handle once initialized
This is where the driver handle will be stored, once created.
Note that you may assume there is only one handle for your driver.
=head4 The driver constructor
The C method is the driver handle constructor. Note that
the C method is in the B package, not in
one of the sub-packages B, B, or
B.
sub driver
{
return $drh if $drh; # already created - return same one
my ($class, $attr) = @_;
$class .= "::dr";
DBD::Driver::db->install_method('drv_example_dbh_method');
DBD::Driver::st->install_method('drv_example_sth_method');
# not a 'my' since we use it above to prevent multiple drivers
$drh = DBI::_new_drh($class, {
'Name' => 'File',
'Version' => $VERSION,
'Attribution' => 'DBD::File by Jochen Wiedmann',
})
or return undef;
return $drh;
}
This is a reasonable example of how B implements its handles. There
are three kinds: B (typically stored in I<$drh>; from
now on called I or I<$drh>), B (from now on
called I or I<$dbh>) and B (from now on called
I or I<$sth>).
The prototype of C is
$drh = DBI::_new_drh($class, $public_attrs, $private_attrs);
with the following arguments:
=over 4
=item I<$class>
is typically the class for your driver, (for example, "DBD::File::dr"),
passed as the first argument to the C method.
=item I<$public_attrs>
is a hash ref to attributes like I, I, and I.
These are processed and used by B. You had better not make any
assumptions about them nor should you add private attributes here.
=item I<$private_attrs>
This is another (optional) hash ref with your private attributes.
B will store them and otherwise leave them alone.
=back
The C method and the C method both return C
for failure (in which case you must look at I<$DBI::err> and I<$DBI::errstr>
for the failure information, because you have no driver handle to use).
=head4 Using install_method() to expose driver-private methods
DBD::Foo::db->install_method($method_name, \%attr);
Installs the driver-private method named by $method_name into the
DBI method dispatcher so it can be called directly, avoiding the
need to use the func() method.
It is called as a static method on the driver class to which the
method belongs. The method name must begin with the corresponding
registered driver-private prefix. For example, for DBD::Oracle
$method_name must being with 'C', and for DBD::AnyData it
must begin with 'C'.
The attributes can be used to provide fine control over how the DBI
dispatcher handles the dispatching of the method. However, at this
point, it's undocumented and very liable to change. (Volunteers to
polish up and document the interface are very welcome to get in
touch via dbi-dev@perl.org)
Methods installed using install_method default to the standard error
handling behaviour for DBI methods: clearing err and errstr before
calling the method, and checking for errors to trigger RaiseError
etc. on return. This differs from the default behaviour of func().
Note for driver authors: The DBD::Foo::xx->install_method call won't
work until the class-hierarchy has been setup. Normally the DBI
looks after that just after the driver is loaded. This means
install_method() can't be called at the time the driver is loaded
unless the class-hierarchy is set up first. The way to do that is
to call the setup_driver() method:
DBI->setup_driver('DBD::Foo');
before using install_method().
=head4 The CLONE special subroutine
Also needed here, in the B package, is a C method
that will be called by perl when an interpreter is cloned. All your
C method needs to do, currently, is clear the cached I<$drh> so
the new interpreter won't start using the cached I<$drh> from the old
interpreter:
sub CLONE {
undef $drh;
}
See L
for details.
=head3 The DBD::Driver::dr package
The next lines of code look as follows:
package DBD::Driver::dr; # ====== DRIVER ======
$DBD::Driver::dr::imp_data_size = 0;
Note that no I<@ISA> is needed here, or for the other B
classes, because the B takes care of that for you when the driver is
loaded.
*FIX ME* Explain what the imp_data_size is, so that implementors aren't
practicing cargo-cult programming.
=head4 The database handle constructor
The database handle constructor is the driver's (hence the changed
namespace) C method:
sub connect
{
my ($drh, $dr_dsn, $user, $auth, $attr) = @_;
# Some database specific verifications, default settings
# and the like can go here. This should only include
# syntax checks or similar stuff where it's legal to
# 'die' in case of errors.
# For example, many database packages requires specific
# environment variables to be set; this could be where you
# validate that they are set, or default them if they are not set.
my $driver_prefix = "drv_"; # the assigned prefix for this driver
# Process attributes from the DSN; we assume ODBC syntax
# here, that is, the DSN looks like var1=val1;...;varN=valN
foreach my $var ( split /;/, $dr_dsn ) {
my ($attr_name, $attr_value) = split '=', $var, 2;
return $drh->set_err($DBI::stderr, "Can't parse DSN part '$var'")
unless defined $attr_value;
# add driver prefix to attribute name if it doesn't have it already
$attr_name = $driver_prefix.$attr_name
unless $attr_name =~ /^$driver_prefix/o;
# Store attribute into %$attr, replacing any existing value.
# The DBI will STORE() these into $dbh after we've connected
$attr->{$attr_name} = $attr_value;
}
# Get the attributes we'll use to connect.
# We use delete here because these no need to STORE them
my $db = delete $attr->{drv_database} || delete $attr->{drv_db}
or return $drh->set_err($DBI::stderr, "No database name given in DSN '$dr_dsn'");
my $host = delete $attr->{drv_host} || 'localhost';
my $port = delete $attr->{drv_port} || 123456;
# Assume you can attach to your database via drv_connect:
my $connection = drv_connect($db, $host, $port, $user, $auth)
or return $drh->set_err($DBI::stderr, "Can't connect to $dr_dsn: ...");
# create a 'blank' dbh (call superclass constructor)
my ($outer, $dbh) = DBI::_new_dbh($drh, { Name => $dr_dsn });
$dbh->STORE('Active', 1 );
$dbh->{drv_connection} = $connection;
return $outer;
}
This is mostly the same as in the I above.
The arguments are described in L.
The constructor C is called, returning a database handle.
The constructor's prototype is:
($outer, $inner) = DBI::_new_dbh($drh, $public_attr, $private_attr);
with similar arguments to those in the I,
except that the I<$class> is replaced by I<$drh>. The I attribute
is a standard B attribute (see L).
In scalar context, only the outer handle is returned.
Note the use of the C method for setting the I attributes.
That's because within the driver code, the handle object you have is
the 'inner' handle of a tied hash, not the outer handle that the
users of your driver have.
Because you have the inner handle, tie magic doesn't get invoked
when you get or set values in the hash. This is often very handy for
speed when you want to get or set simple non-special driver-specific
attributes.
However, some attribute values, such as those handled by the B like
I, don't actually exist in the hash and must be read via
C<$h-EFETCH($attrib)> and set via C<$h-ESTORE($attrib, $value)>.
If in any doubt, use these methods.
=head4 The data_sources() method
The C method must populate and return a list of valid data
sources, prefixed with the "I" incantation that allows them to
be used in the first argument of the Cconnect()> method.
An example of this might be scanning the F<$HOME/.odbcini> file on Unix
for ODBC data sources (DSNs).
As a trivial example, consider a fixed list of data sources:
sub data_sources
{
my($drh, $attr) = @_;
my(@list) = ();
# You need more sophisticated code than this to set @list...
push @list, "dbi:Driver:abc";
push @list, "dbi:Driver:def";
push @list, "dbi:Driver:ghi";
# End of code to set @list
return @list;
}
=head4 The disconnect_all() method
If you need to release any resources when the driver is unloaded, you
can provide a disconnect_all method.
=head4 Other driver handle methods
If you need any other driver handle methods, they can follow here.
=head4 Error handling
It is quite likely that something fails in the connect method.
With B for example, you might catch an error when setting the
current directory to something not existent by using the
(driver-specific) I attribute.
To report an error, you use the C