DBI::DBD::SqlEngine::DUseroContributed Perl DBI::DBD::SqlEngine::Developers(3)NAMEDBI::DBD::SqlEngine::Developers - Developers documentation for
DBI::DBD::SqlEngine
SYNOPSIS
package DBD::myDriver;
use base qw(DBI::DBD::SqlEngine);
sub driver
{
...
my $drh = $proto->SUPER::driver($attr);
...
return $drh->{class};
}
sub CLONE { ... }
package DBD::myDriver::dr;
@ISA = qw(DBI::DBD::SqlEngine::dr);
sub data_sources { ... }
...
package DBD::myDriver::db;
@ISA = qw(DBI::DBD::SqlEngine::db);
sub init_valid_attributes { ... }
sub init_default_attributes { ... }
sub set_versions { ... }
sub validate_STORE_attr { my ($dbh, $attrib, $value) = @_; ... }
sub validate_FETCH_attr { my ($dbh, $attrib) = @_; ... }
sub get_myd_versions { ... }
sub get_avail_tables { ... }
package DBD::myDriver::st;
@ISA = qw(DBI::DBD::SqlEngine::st);
sub FETCH { ... }
sub STORE { ... }
package DBD::myDriver::Statement;
@ISA = qw(DBI::DBD::SqlEngine::Statement);
sub open_table { ... }
package DBD::myDriver::Table;
@ISA = qw(DBI::DBD::SqlEngine::Table);
sub new { ... }
sub fetch_row { ... }
sub push_row { ... }
sub push_names { ... }
sub seek { ... }
sub truncate { ... }
sub drop { ... }
# optimize the SQL engine by add one or more of
sub update_current_row { ... }
# or
sub update_specific_row { ... }
# or
sub update_one_row { ... }
# or
sub insert_new_row { ... }
# or
sub delete_current_row { ... }
# or
sub delete_one_row { ... }
DESCRIPTION
This document describes the interface of DBI::DBD::SqlEngine for DBD
developers who write DBI::DBD::SqlEngine based DBI drivers. It
supplements DBI::DBD and DBI::DBD::SqlEngine::HowTo, which you should
read first.
CLASSES
Each DBI driver must provide a package global "driver" method and three
DBI related classes:
DBI::DBD::SqlEngine::dr
Driver package, contains the methods DBI calls indirectly via DBI
interface:
DBI->connect ('DBI:DBM:', undef, undef, {})
# invokes
package DBD::DBM::dr;
@DBD::DBM::dr::ISA = qw(DBI::DBD::SqlEngine::dr);
sub connect ($$;$$$)
{
...
}
Similar for "data_sources ()" and "disconnect_all()".
Pure Perl DBI drivers derived from DBI::DBD::SqlEngine do not
usually need to override any of the methods provided through the
DBD::XXX::dr package however if you need additional initialization
in the connect method you may need to.
DBI::DBD::SqlEngine::db
Contains the methods which are called through DBI database handles
($dbh). e.g.,
$sth = $dbh->prepare ("select * from foo");
# returns the f_encoding setting for table foo
$dbh->csv_get_meta ("foo", "f_encoding");
DBI::DBD::SqlEngine provides the typical methods required here.
Developers who write DBI drivers based on DBI::DBD::SqlEngine need
to override the methods "set_versions" and "init_valid_attributes".
DBI::DBD::SqlEngine::st
Contains the methods to deal with prepared statement handles. e.g.,
$sth->execute () or die $sth->errstr;
DBI::DBD::SqlEngine
This is the main package containing the routines to initialize
DBI::DBD::SqlEngine based DBI drivers. Primarily the
"DBI::DBD::SqlEngine::driver" method is invoked, either directly from
DBI when the driver is initialized or from the derived class.
package DBD::DBM;
use base qw( DBI::DBD::SqlEngine );
sub driver
{
my ( $class, $attr ) = @_;
...
my $drh = $class->SUPER::driver( $attr );
...
return $drh;
}
It is not necessary to implement your own driver method as long as
additional initialization (e.g. installing more private driver methods)
is not required. You do not need to call "setup_driver" as
DBI::DBD::SqlEngine takes care of it.
DBI::DBD::SqlEngine::dr
The driver package contains the methods DBI calls indirectly via the
DBI interface (see "DBI Class Methods" in DBI).
DBI::DBD::SqlEngine based DBI drivers usually do not need to implement
anything here, it is enough to do the basic initialization:
package DBD:XXX::dr;
@DBD::XXX::dr::ISA = qw (DBI::DBD::SqlEngine::dr);
$DBD::XXX::dr::imp_data_size = 0;
$DBD::XXX::dr::data_sources_attr = undef;
$DBD::XXX::ATTRIBUTION = "DBD::XXX $DBD::XXX::VERSION by Hans Mustermann";
DBI::DBD::SqlEngine::db
This package defines the database methods, which are called via the DBI
database handle $dbh.
Methods provided by DBI::DBD::SqlEngine:
ping
Simply returns the content of the "Active" attribute. Override when
your driver needs more complicated actions here.
prepare
Prepares a new SQL statement to execute. Returns a statement
handle, $sth - instance of the DBD:XXX::st. It is neither required
nor recommended to override this method.
FETCH
Fetches an attribute of a DBI database object. Private handle
attributes must have a prefix (this is mandatory). If a requested
attribute is detected as a private attribute without a valid
prefix, the driver prefix (written as $drv_prefix) is added.
The driver prefix is extracted from the attribute name and verified
against "$dbh->{ $drv_prefix . "valid_attrs" }" (when it exists).
If the requested attribute value is not listed as a valid
attribute, this method croaks. If the attribute is valid and
readonly (listed in "$dbh->{ $drv_prefix . "readonly_attrs" }" when
it exists), a real copy of the attribute value is returned. So it's
not possible to modify "f_valid_attrs" from outside of
DBI::DBD::SqlEngine::db or a derived class.
STORE
Stores a database private attribute. Private handle attributes must
have a prefix (this is mandatory). If a requested attribute is
detected as a private attribute without a valid prefix, the driver
prefix (written as $drv_prefix) is added. If the database handle
has an attribute "${drv_prefix}_valid_attrs" - for attribute names
which are not listed in that hash, this method croaks. If the
database handle has an attribute "${drv_prefix}_readonly_attrs",
only attributes which are not listed there can be stored (once they
are initialized). Trying to overwrite such an immutable attribute
forces this method to croak.
An example of a valid attributes list can be found in
"DBI::DBD::SqlEngine::db::init_valid_attributes".
set_versions
This method sets the attributes "f_version", "sql_nano_version",
"sql_statement_version" and (if not prohibited by a restrictive
"${prefix}_valid_attrs") "${prefix}_version".
This method is called at the end of the "connect ()" phase.
When overriding this method, do not forget to invoke the superior
one.
init_valid_attributes
This method is called after the database handle is instantiated as
the first attribute initialization.
"DBI::DBD::SqlEngine::db::init_valid_attributes" initializes the
attributes "sql_valid_attrs" and "sql_readonly_attrs".
When overriding this method, do not forget to invoke the superior
one, preferably before doing anything else.
init_default_attributes
This method is called after the database handle is instantiated to
initialize the default attributes.
"DBI::DBD::SqlEngine::db::init_default_attributes" initializes the
attributes "sql_identifier_case", "sql_quoted_identifier_case",
"sql_handler", "sql_engine_version", "sql_nano_version" and
"sql_statement_version" when SQL::Statement is available.
When the derived implementor class provides the attribute to
validate attributes (e.g. "$dbh->{dbm_valid_attrs} = {...};") or
the attribute containing the immutable attributes (e.g.
"$dbh->{dbm_readonly_attrs} = {...};"), the attributes
"drv_valid_attrs", "drv_readonly_attrs" and "drv_version" are added
(when available) to the list of valid and immutable attributes
(where "drv_" is interpreted as the driver prefix).
get_versions
This method is called by the code injected into the instantiated
driver to provide the user callable driver method
"${prefix}versions" (e.g. "dbm_versions", "csv_versions", ...).
The DBI::DBD::SqlEngine implementation returns all version
information known by DBI::DBD::SqlEngine (e.g. DBI version, Perl
version, DBI::DBD::SqlEngine version and the SQL handler version).
"get_versions" takes the $dbh as the first argument and optionally
a second argument containing a table name. The second argument is
not evaluated in "DBI::DBD::SqlEngine::db::get_versions" itself -
but might be in the future.
If the derived implementor class provides a method named
"get_${drv_prefix}versions", this is invoked and the return value
of it is associated to the derived driver name:
if (my $dgv = $dbh->{ImplementorClass}->can ("get_" . $drv_prefix . "versions") {
(my $derived_driver = $dbh->{ImplementorClass}) =~ s/::db$//;
$versions{$derived_driver} = &$dgv ($dbh, $table);
}
Override it to add more version information about your module,
(e.g. some kind of parser version in case of DBD::CSV, ...), if
one line is not enough room to provide all relevant information.
sql_parser_object
Returns a SQL::Parser instance, when "sql_handler" is set to
"SQL::Statement". The parser instance is stored in
"sql_parser_object".
It is not recommended to override this method.
disconnect
Disconnects from a database. All local table information is
discarded and the "Active" attribute is set to 0.
type_info_all
Returns information about all the types supported by
DBI::DBD::SqlEngine.
table_info
Returns a statement handle which is prepared to deliver information
about all known tables.
list_tables
Returns a list of all known table names.
quote
Quotes a string for use in SQL statements.
commit
Warns about a useless call (if warnings enabled) and returns.
DBI::DBD::SqlEngine is typically a driver which commits every
action instantly when executed.
rollback
Warns about a useless call (if warnings enabled) and returns.
DBI::DBD::SqlEngine is typically a driver which commits every
action instantly when executed.
DBI::DBD::SqlEngine::st
Contains the methods to deal with prepared statement handles:
bind_param
Common routine to bind placeholders to a statement for execution.
It is dangerous to override this method without detailed knowledge
about the DBI::DBD::SqlEngine internal storage structure.
execute
Executes a previously prepared statement (with placeholders, if
any).
finish
Finishes a statement handle, discards all buffered results. The
prepared statement is not discarded so the statement can be
executed again.
fetch
Fetches the next row from the result-set. This method may be
rewritten in a later version and if it's overridden in a derived
class, the derived implementation should not rely on the storage
details.
fetchrow_arrayref
Alias for "fetch".
FETCH
Fetches statement handle attributes. Supported attributes (for full
overview see "Statement Handle Attributes" in DBI) are "NAME",
"TYPE", "PRECISION" and "NULLABLE". Each column is returned as
"NULLABLE" which might be wrong depending on the derived backend
storage. If the statement handle has private attributes, they can
be fetched using this method, too. Note that statement attributes
are not associated with any table used in this statement.
This method usually requires extending in a derived implementation.
See DBD::CSV or DBD::DBM for some example.
STORE
Allows storing of statement private attributes. No special handling
is currently implemented here.
rows
Returns the number of rows affected by the last execute. This
method might return "undef".
DBI::DBD::SqlEngine::Statement
Derives from DBI::SQL::Nano::Statement for unified naming when deriving
new drivers. No additional feature is provided from here.
DBI::DBD::SqlEngine::Table
Derives from DBI::SQL::Nano::Table for unified naming when deriving new
drivers. No additional feature is provided from here.
You should consult the documentation of "SQL::Eval::Table" (see
SQL::Eval) to get more information about the abstract methods of the
table's base class you have to override and a description of the table
meta information expected by the SQL engines.
AUTHOR
The module DBI::DBD::SqlEngine is currently maintained by
H.Merijn Brand < h.m.brand at xs4all.nl > and Jens Rehsack < rehsack
at googlemail.com >
COPYRIGHT AND LICENSE
Copyright (C) 2010 by H.Merijn Brand & Jens Rehsack
All rights reserved.
You may freely distribute and/or modify this module under the terms of
either the GNU General Public License (GPL) or the Artistic License, as
specified in the Perl README file.
perl v5.10.12010-08-30DBI::DBD::SqlEngine::Developers(3)
