dbd.pm

SinFP是一种新的识别对方计算机操作系统类型的工具

package DBI::DBD;
# vim:ts=8:sw=4

use vars qw($VERSION);	# set $VERSION early so we don't confuse PAUSE/CPAN etc

$VERSION = sprintf("%d.%02d", q$Revision: 11.21 $ =~ /(\d+)\.(\d+)/o);

# $Id: DBD.pm,v 11.21 2004/02/01 11:16:16 timbo Exp $
#
# Copyright (c) 1997-2003 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

  $Revision: 11.21 $
  $Date: 2004/02/01 11:16:16 $

This document is I<still> a minimal draft which is in need of further work.

The changes will occur both because the DBI specification is changing
and hence the requirements on DBD drivers change, and because feedback
from people reading this document will suggest improvements to it.

Please read the DBI documentation first and fully, including the DBI FAQ.
Then reread the DBI 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 DBD 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<any> doubt at all, please do contact the dbi-dev 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: "DON'T!"

There is usually a driver already available for the database you want to
use, almost regardless of which database you choose.
And very often, the database will provide an ODBC driver interface, so
you can often use DBD::ODBC 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<http://www.unixodbc.org/>) is the way to go.]

The second rule for creating a new database driver for the Perl DBI is
also very simple: "Don't -- get someone else to do it for you!"

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 DBI software and information is

  http://dbi.perl.org/

There are two main and one auxilliary mailing lists for people working
with DBI.  The primary lists are [e-mail] for general users
of DBI and DBD drivers, and [e-mail] mainly for DBD driver
writers (don't join the dbi-dev list unless you have a good reason).
The auxilliary list is [e-mail] for announcing new
releases of DBI or DBD drivers.

You can join these lists by accessing the web-site
L<http://dbi.perl.org/>.
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 comp.lang.perl.* newsgroups,
especially comp.lang.perl.modules.

=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 'Programming the Perl DBI: Database programming with
Perl' 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<http://search.cpan.org/>.  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 DBD:: and DBIx:: links at the top to see those subsets.

See the DBI docs for information on DBI 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 DBI 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, DBD::Oracle has the name Oracle and the prefix 'ora_'.
This information will be recorded in the DBI module.
Apart from documentation purposes, registration is a prerequisite for
L<installing private methods|DBI/install_method>.

This document assumes you are writing a driver called DBD::Driver, and
that the prefix 'drv_' 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 example pure Perl drivers are DBD::File and DBD::CSV.

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 DBD::Driver, these files are:

=over 4

=item * Makefile.PL

=item * README

=item * MANIFEST

=item * Driver.pm

=item * lib/Bundle/DBD/Driver.pm

=item * lib/DBD/Driver/Summary.pm

=item * t/*.t

=back

Needless to say, all these files are either text files or pure Perl.

The first four files are mandatory.
Makefile.PL is used to control how the driver is built and installed.
The README file tells people who download the file about how to build
the module and any prerequisite software that must be installed.
The MANIFEST file is used by the standard Perl module distribution mechanism.
It lists all the source files that need to be distributed with your module.
Driver.pm is what is loaded by the DBI code; it contains the methods
peculiar to your driver.

The lib/Bundle/DBD/Driver.pm 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 lib/DBD/Driver/Summary.pm 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 t 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.
Your tests should not casually modify operational databases.
You should never damage existing tables in a database.
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 'dbd_drv_'.
At the end of a test run, there should be no testing objects left behind
in the database.
If you create any databases, you should remove them.
If your database supports temporary tables that are automatically
removed at the end of a session, then exploit them as often as possible.
Try to make your tests independent of each other.
If you have a test t/t11dowhat.t that depends upon the successful
running of t/t10thingamy.t, people cannot run the single test case
t/t11dowhat.t.
Further, running t/t11dowhat.t twice in a row is likely to fail (at
least, if t/t11dowhat.t 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.
Document in your README file what you do, and what privileges people
need to do it.
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.

Many drivers also install sub-modules DBD::Driver::SubModule for any of
a variety of different reasons, such as to support the metadata methods
(see the discussion of L</METADATA METHODS> below).
Such sub-modules are conventionally stored in the directory lib/DBD/Driver.
The module itself would usually be in a file SubModule.pm.
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 * Driver.xs

=item * Driver.h

=item * dbdimp.h

=item * dbdimp.c

=back

The Driver.xs 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 Driver.h header is a stylized header that ensures you can access the
necessary Perl and DBI macros, types, and function declarations.

The dbdimp.h is used to specify which functions have been implemented by
your driver.

The dbdimp.c 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 Makefile.PL and Driver.pm 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 (http://www.cpan.org/ and http://search.cpan.org).
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 DBD::AnyData and DBD::Template.

As an example we take a look at the I<DBD::File> driver, a driver for
accessing plain files as tables, which is part of the I<DBD::CSV>
package.
In what follows I assume the name C<Driver> for your new package and the
prefix 'drv_'.
The minimal set of files we have to implement are I<Makefile.PL>,
I<README>, I<MANIFEST> and I<Driver.pm>.
Files in the 'nice to have' category include '

=head2 Pure Perl version of Makefile.PL

You typically start with writing C<Makefile.PL>, a Makefile generator.
The contents of this file are described in detail in the
C<ExtUtils::MakeMaker> man pages.
It is definitely a good idea if you start reading them.
At least you should know about the variables I<CONFIGURE>, I<DEFINED>,
I<PM>, I<DIR>, I<EXE_FILES>, I<INC>, I<LIBS>, I<LINKTYPE>, I<NAME>,
I<OPTIMIZE>, I<PL_FILES>, I<VERSION>, I<VERSION_FROM>, I<clean>,
I<depend>, I<realclean> from the C<ExtUtils::MakeMaker> man page: These
are used in almost any Makefile.PL.
Additionally read the section on I<Overriding MakeMaker Methods> and the
descriptions of the I<distcheck>, I<disttest> and I<dist> targets: They
will definitely be useful for you.

Of special importance for DBI drivers is the I<postamble> method from
the C<ExtUtils::MM_Unix> man page.
And, for Emacs users, I recommend the I<libscan> 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<Driver> wherever you should insert
your driver's name:

  # -*- perl -*-

  use DBI 1.03;
  use DBI::DBD;
  use ExtUtils::MakeMaker;

  WriteMakefile(
      dbd_edit_mm_attribs( {
          'NAME'         => 'DBD::Driver',
          'VERSION_FROM' => 'Driver.pm',
          'INC'          => $DBI_INC_DIR,
          'dist'         => { 'SUFFIX'   => '.gz',
                              'COMPRESS' => 'gzip -9f' },
          'realclean'    => { FILES => '*.xsi' },
      },
      { create_pp_tests => 1})
  );

  package MY;
  sub postamble { return main::dbd_postamble(@_); }
  sub libscan {
      my ($self, $path) = @_;
      ($path =~ m/\~$/) ? undef : $path;
  }