NAME
DBI::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);
my %reset_on_modify = (
myd_abc => "myd_foo",
myd_mno => "myd_bar",
);
__PACKAGE__->register_reset_on_modify( \%reset_on_modify );
my %compat_map = (
abc => 'foo_abc',
xyz => 'foo_xyz',
);
__PACKAGE__->register_compat_map( \%compat_map );
sub bootstrap_table_meta { ... }
sub init_table_meta { ... }
sub table_meta_attr_changed { ... }
sub open_data { ... }
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; our @ISA = qw(DBI::DBD::SqlEngine::dr); sub connect ($$;$$$) { ... }
Similar for
data_sources ()
anddisconnect_all()
.Pure Perl DBI drivers derived from DBI::DBD::SqlEngine usually don't need to override any of the methods provided through the DBD::XXX::dr package. However if you need additional initialization not fitting in
init_valid_attributes()
andinit_default_attributes()
of you're ::db class, the connect method might be the final place to be modified. - 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
andinit_valid_attributes
. - DBI::DBD::SqlEngine::TieMeta;
-
Provides the tie-magic for
$dbh->{$drv_pfx . "_meta"}
. RoutesSTORE
through$drv->set_sql_engine_meta()
andFETCH
through$drv->get_sql_engine_meta()
.DELETE
is not supported, you have to execute aDROP TABLE
statement, where applicable. - DBI::DBD::SqlEngine::TieTables;
-
Provides the tie-magic for tables in
$dbh->{$drv_pfx . "_meta"}
. RoutesSTORE
though$tblClass->set_table_meta_attr()
andFETCH
though$tblClass->get_table_meta_attr()
.DELETE
removes an attribute from the meta object retrieved by$tblClass->get_table_meta()
. - DBI::DBD::SqlEngine::st
-
Contains the methods to deal with prepared statement handles. e.g.,
$sth->execute () or die $sth->errstr;
- DBI::DBD::SqlEngine::TableSource;
-
Base class for 3rd party table sources:
$dbh->{sql_table_source} = "DBD::Foo::TableSource";
- DBI::DBD::SqlEngine::DataSource;
-
Base class for 3rd party data sources:
$dbh->{sql_data_source} = "DBD::Foo::DataSource";
- DBI::DBD::SqlEngine::Statement;
-
Base class for derived drivers statement engine. Implements
open_table
. - DBI::DBD::SqlEngine::Table;
-
Contains tailoring between SQL engine's requirements and
DBI::DBD::SqlEngine
magic for finding the right tables and storage. Builds bridges betweensql_meta
handling ofDBI::DBD::SqlEngine::db
, table initialization for SQL engines and meta object's attribute management for derived drivers.
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;
our @ISA = qw (DBI::DBD::SqlEngine::dr);
our $imp_data_size = 0;
our $data_sources_attr = undef;
$DBD::XXX::ATTRIBUTION = "DBD::XXX $DBD::XXX::VERSION by Hans Mustermann";
Methods provided by DBI::DBD::SqlEngine::dr
:
- connect
-
Supervises the driver bootstrap when calling
DBI->connect( "dbi:Foo", , , { ... } );
First it instantiates a new driver using
DBI::_new_dbh
. After that, initial bootstrap of the newly instantiated driver is done by$dbh->func( 0, "init_default_attributes" );
The first argument (
0
) signals that this is the very first call toinit_default_attributes
. Modern drivers understand that and do early stage setup here after callingpackage DBD::Foo::db; our @ISA = qw(DBI::DBD::SqlEngine::db); sub init_default_attributes { my ($dbh, $phase) = @_; $dbh->SUPER::init_default_attributes($phase); ...; # own setup code, maybe separated by phases }
When the
$phase
argument is passed down untilDBI::DBD::SqlEngine::db::init_default_attributes
,connect()
recognizes a modern driver and initializes the attributes from DSN and $attr arguments passed viaDBI->connect( $dsn, $user, $pass, \%attr )
.At the end of the attribute initialization after phase 0,
connect()
invokedinit_default_attributes
again for phase 1:$dbh->func( 1, "init_default_attributes" );
- data_sources
-
Returns a list of DSN's using the
data_sources
method of the class specified in$dbh->{sql_table_source}
or via\%attr
:@ary = DBI->data_sources($driver); @ary = DBI->data_sources($driver, \%attr);
- disconnect_all
-
DBI::DBD::SqlEngine
doesn't have an overall driver cache, so nothing happens here at all.
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::db
:
- 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. - validate_FETCH_attr
-
Called by
FETCH
to allow inherited drivers do their own attribute name validation. Calling convention is similar toFETCH
and the return value is the approved attribute name.return $validated_attribute_name;
In case of validation fails (e.g. accessing private attribute or similar),
validate_FETCH_attr
is permitted to throw an exception. - 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 modifyf_valid_attrs
from outside of DBI::DBD::SqlEngine::db or a derived class. - validate_STORE_attr
-
Called by
STORE
to allow inherited drivers do their own attribute name validation. Calling convention is similar toSTORE
and the return value is the approved attribute name followed by the approved new value.return ($validated_attribute_name, $validated_attribute_value);
In case of validation fails (e.g. accessing private attribute or similar),
validate_STORE_attr
is permitted to throw an exception (DBI::DBD::SqlEngine::db::validate_STORE_attr
throws an exception when someone tries to assign value other thanSQL_IC_UPPER .. SQL_IC_MIXED
to$dbh->{sql_identifier_case}
or$dbh->{sql_quoted_identifier_case}
). - 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 attributessql_valid_attrs
andsql_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. It expects one argument:
$phase
. If$phase
is not given,connect
ofDBI::DBD::SqlEngine::dr
expects this is an old-fashioned driver which isn't capable of multi-phased initialization.DBI::DBD::SqlEngine::db::init_default_attributes
initializes the attributessql_identifier_case
,sql_quoted_identifier_case
,sql_handler
,sql_init_order
,sql_meta
,sql_engine_version
,sql_nano_version
andsql_statement_version
when SQL::Statement is available.It sets
sql_init_order
to the given$phase
.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 attributesdrv_valid_attrs
,drv_readonly_attrs
anddrv_version
are added (when available) to the list of valid and immutable attributes (wheredrv_
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 inDBI::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 insql_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.
Attributes used by DBI::DBD::SqlEngine::db
:
This section describes attributes which are important to developers of DBI Database Drivers derived from DBI::DBD::SqlEngine
.
- sql_init_order
-
This attribute contains a hash with priorities as key and an array containing the
$dbh
attributes to be initialized during before/after other attributes.DBI::DBD::SqlEngine
initializes following attributes:$dbh->{sql_init_order} = { 0 => [qw( Profile RaiseError PrintError AutoCommit )], 90 => [ "sql_meta", $dbh->{$drv_pfx_meta} ? $dbh->{$drv_pfx_meta} : () ] }
The default priority of not listed attribute keys is
50
. It is well known that a lot of attributes needed to be set before some table settings are initialized. For example, for DBD::DBM, when usingmy $dbh = DBI->connect( "dbi:DBM:", undef, undef, { f_dir => "/path/to/dbm/databases", dbm_type => "BerkeleyDB", dbm_mldbm => "JSON", # use MLDBM::Serializer::JSON dbm_tables => { quick => { dbm_type => "GDBM_File", dbm_MLDBM => "FreezeThaw" } } });
This defines a known table
quick
which uses the GDBM_File backend and FreezeThaw as serializer instead of the overall default BerkeleyDB and JSON. But all files containing the table data have to be searched in$dbh->{f_dir}
, which requires$dbh->{f_dir}
must be initialized before$dbh->{sql_meta}->{quick}
is initialized bybootstrap_table_meta
method of "DBI::DBD::SqlEngine::Table" to get$dbh->{sql_meta}->{quick}->{f_dir}
being initialized properly. - sql_init_phase
-
This attribute is only set during the initialization steps of the DBI Database Driver. It contains the value of the currently run initialization phase. Currently supported phases are phase 0 and phase 1. This attribute is set in
init_default_attributes
and removed ininit_done
. - sql_engine_in_gofer
-
This value has a true value in case of this driver is operated via DBD::Gofer. The impact of being operated via Gofer is a read-only driver (not read-only databases!), so you cannot modify any attributes later - neither any table settings. But you won't get an error in cases you modify table attributes, so please carefully watch
sql_engine_in_gofer
. - sql_table_source
-
Names a class which is responsible for delivering data sources and available tables (Database Driver related). data sources here refers to "data_sources" in DBI, not
sql_data_source
.See "DBI::DBD::SqlEngine::TableSource" for details.
- sql_data_source
-
Name a class which is responsible for handling table resources open and completing table names requested via SQL statements.
See "DBI::DBD::SqlEngine::DataSource" for details.
- sql_dialect
-
Controls the dialect understood by SQL::Parser. Possible values (delivery state of SQL::Statement):
* ANSI * CSV * AnyData
Defaults to "CSV". Because an SQL::Parser is instantiated only once and SQL::Parser doesn't allow one to modify the dialect once instantiated, it's strongly recommended to set this flag before any statement is executed (best place is connect attribute hash).
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
andNULLABLE
. Each column is returned asNULLABLE
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::TableSource
Provides data sources and table information on database driver and database handle level.
package DBI::DBD::SqlEngine::TableSource;
sub data_sources ($;$)
{
my ( $class, $drh, $attrs ) = @_;
...
}
sub avail_tables
{
my ( $class, $drh ) = @_;
...
}
The data_sources
method is called when the user invokes any of the following:
@ary = DBI->data_sources($driver);
@ary = DBI->data_sources($driver, \%attr);
@ary = $dbh->data_sources();
@ary = $dbh->data_sources(\%attr);
The avail_tables
method is called when the user invokes any of the following:
@names = $dbh->tables( $catalog, $schema, $table, $type );
$sth = $dbh->table_info( $catalog, $schema, $table, $type );
$sth = $dbh->table_info( $catalog, $schema, $table, $type, \%attr );
$dbh->func( "list_tables" );
Every time where an \%attr
argument can be specified, this \%attr
object's sql_table_source
attribute is preferred over the $dbh
attribute or the driver default.
DBI::DBD::SqlEngine::DataSource
Provides base functionality for dealing with tables. It is primarily designed for allowing transparent access to files on disk or already opened (file-)streams (e.g. for DBD::CSV).
Derived classes shall be restricted to similar functionality, too (e.g. opening streams from an archive, transparently compress/uncompress log files before parsing them,
package DBI::DBD::SqlEngine::DataSource;
sub complete_table_name ($$;$)
{
my ( $self, $meta, $table, $respect_case ) = @_;
...
}
The method complete_table_name
is called when first setting up the meta information for a table:
"SELECT user.id, user.name, user.shell FROM user WHERE ..."
results in opening the table user
. First step of the table open process is completing the name. Let's imagine you're having a DBD::CSV handle with following settings:
$dbh->{sql_identifier_case} = SQL_IC_LOWER;
$dbh->{f_ext} = '.lst';
$dbh->{f_dir} = '/data/web/adrmgr';
Those settings will result in looking for files matching [Uu][Ss][Ee][Rr](\.lst)?$
in /data/web/adrmgr/
. The scanning of the directory /data/web/adrmgr/
and the pattern match check will be done in DBD::File::DataSource::File
by the complete_table_name
method.
If you intend to provide other sources of data streams than files, in addition to provide an appropriate complete_table_name
method, a method to open the resource is required:
package DBI::DBD::SqlEngine::DataSource;
sub open_data ($)
{
my ( $self, $meta, $attrs, $flags ) = @_;
...
}
After the method open_data
has been run successfully, the table's meta information are in a state which allows the table's data accessor methods will be able to fetch/store row information. Implementation details heavily depends on the table implementation, whereby the most famous is surely DBD::File::Table.
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.
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.
- bootstrap_table_meta
-
Initializes a table meta structure. Can be safely overridden in a derived class, as long as the
SUPER
method is called at the end of the overridden method.It copies the following attributes from the database into the table meta data
$dbh->{ReadOnly}
into$meta->{readonly}
,sql_identifier_case
andsql_data_source
and makes them sticky to the table.This method should be called before you attempt to map between file name and table name to ensure the correct directory, extension etc. are used.
- init_table_meta
-
Initializes more attributes of the table meta data - usually more expensive ones (e.g. those which require class instantiations) - when the file name and the table name could mapped.
- get_table_meta
-
Returns the table meta data. If there are none for the required table, a new one is initialized. When after bootstrapping a new table_meta and completing the table name a mapping can be established between an existing table_meta and the new bootstrapped one, the already existing is used and a mapping shortcut between the recent used table name and the already known table name is hold in
$dbh->{sql_meta_map}
. When it fails, nothing is returned. On success, the name of the table and the meta data structure is returned. - get_table_meta_attr
-
Returns a single attribute from the table meta data. If the attribute name appears in
%compat_map
, the attribute name is updated from there. - set_table_meta_attr
-
Sets a single attribute in the table meta data. If the attribute name appears in
%compat_map
, the attribute name is updated from there. - table_meta_attr_changed
-
Called when an attribute of the meta data is modified.
If the modified attribute requires to reset a calculated attribute, the calculated attribute is reset (deleted from meta data structure) and the initialized flag is removed, too. The decision is made based on
%register_reset_on_modify
. - register_reset_on_modify
-
Allows
set_table_meta_attr
to reset meta attributes when special attributes are modified. For DBD::File, modifying one off_file
,f_dir
,f_ext
orf_lockfile
will resetf_fqfn
. DBD::DBM extends the list fordbm_type
anddbm_mldbm
to reset the value ofdbm_tietype
.If your DBD has calculated values in the meta data area, then call
register_reset_on_modify
:my %reset_on_modify = ( "xxx_foo" => "xxx_bar" ); __PACKAGE__->register_reset_on_modify( \%reset_on_modify );
- register_compat_map
-
Allows
get_table_meta_attr
andset_table_meta_attr
to update the attribute name to the current favored one:# from DBD::DBM my %compat_map = ( "dbm_ext" => "f_ext" ); __PACKAGE__->register_compat_map( \%compat_map );
- open_data
-
Called to open the table's data storage. This is silently forwarded to
$meta->{sql_data_source}->open_data()
.After this is done, a derived class might add more steps in an overridden
open_file
method. - new
-
Instantiates the table. This is done in 3 steps:
1. get the table meta data 2. open the data file 3. bless the table data structure using inherited constructor new
It is not recommended to override the constructor of the table class. Find a reasonable place to add you extensions in one of the above four methods.
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.