DBD::File::Developers - Developers documentation for DBD::File
perldoc DBD::File::Developers perldoc DBD::File::Roadmap
This document describes how DBD developers can write DBD::File based DBI drivers. It supplements DBI::DBD, which you should read first.
Each DBI driver must provide a package global driver method and three DBI related classes:
driver
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(DBD::File::dr); sub connect ($$;$$$) { ... }
Similar for data_sources () and disconnect_all().
data_sources ()
disconnect_all()
Pure Perl DBI drivers derived from DBD::File 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.
Contains the methods which are called through DBI database handles ($dbh). e.g.,
$dbh
$sth = $dbh->prepare ("select * from foo"); # returns the f_encoding setting for table foo $dbh->csv_get_meta ("foo", "f_encoding");
DBD::File provides the typical methods required here. Developers who write DBI drivers based on DBD::File need to override the methods set_versions and init_valid_attributes.
set_versions
init_valid_attributes
Contains the methods to deal with prepared statement handles. e.g.,
$sth->execute () or die $sth->errstr;
This is the main package containing the routines to initialize DBD::File based DBI drivers. Primarily the DBD::File::driver method is invoked, either directly from DBI when the driver is initialized or from the derived class.
DBD::File::driver
package DBD::DBM; use base qw( DBD::File ); 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 DBD::File takes care of it.
setup_driver
The driver package contains the methods DBI calls indirectly via the DBI interface (see "DBI Class Methods" in DBI).
DBD::File 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 (DBD::File::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";
This package defines the database methods, which are called via the DBI database handle $dbh.
Methods provided by DBD::File:
Simply returns the content of the Active attribute. Override when your driver needs more complicated actions here.
Active
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.
$sth
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.
$drv_prefix
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 DBD::File::db or a derived class.
$dbh->{ $drv_prefix . "valid_attrs" }
$dbh->{ $drv_prefix . "readonly_attrs" }
f_valid_attrs
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.
${drv_prefix}_valid_attrs
${drv_prefix}_readonly_attrs
An example of a valid attributes list can be found in DBD::File::db::init_valid_attributes.
DBD::File::db::init_valid_attributes
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.
f_version
sql_nano_version
sql_statement_version
${prefix}_valid_attrs
${prefix}_version
This method is called at the end of the connect () phase.
connect ()
When overriding this method, do not forget to invoke the superior one.
This method is called after the database handle is instantiated as the first attribute initialization.
DBD::File::db::init_valid_attributes initializes the attributes f_valid_attrs, sql_valid_attrs, f_readonly_attrs and sql_readonly_attrs.
sql_valid_attrs
f_readonly_attrs
sql_readonly_attrs
When overriding this method, do not forget to invoke the superior one, preferably before doing anything else. Compatibility table attribute access must be initialized here to allow DBD::File to instantiate the map tie:
# for DBD::CSV $dbh->{csv_meta} = "csv_tables"; # for DBD::DBM $dbh->{dbm_meta} = "dbm_tables"; # for DBD::AnyData $dbh->{ad_meta} = "ad_tables";
This method is called after the database handle is instantiated to initialize the default attributes.
DBD::File::db::init_default_attributes initializes the attributes f_dir, f_meta, f_meta_map, f_version, sql_identifier_case, sql_quoted_identifier_case and sql_handler.
DBD::File::db::init_default_attributes
f_dir
f_meta
f_meta_map
sql_identifier_case
sql_quoted_identifier_case
sql_handler
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, drv_version and drv_meta are added (when available) to the list of valid and immutable attributes (where drv_ is interpreted as the driver prefix).
$dbh->{dbm_valid_attrs} = {...};
$dbh->{dbm_readonly_attrs} = {...};
drv_valid_attrs
drv_readonly_attrs
drv_version
drv_meta
drv_
If drv_meta is set, an attribute with the name in drv_meta is initialized providing restricted read/write access to the meta data of the tables using DBD::File::TieTables in the first (table) level and DBD::File::TieMeta for the meta attribute level. DBD::File::TieTables uses DBD::DRV::Table::get_table_meta to initialize the second level tied hash on FETCH/STORE. The DBD::File::TieMeta class uses DBD::DRV::Table::get_table_meta_attr to FETCH attribute values and DBD::DRV::Table::set_table_meta_attr to STORE attribute values. This allows it to map meta attributes for compatibility reasons.
DBD::File::TieTables
DBD::File::TieMeta
DBD::DRV::Table::get_table_meta
DBD::DRV::Table::get_table_meta_attr
DBD::DRV::Table::set_table_meta_attr
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, ...).
${prefix}versions
dbm_versions
csv_versions
The DBD::File implementation returns all version information known by DBD::File (e.g. DBI version, Perl version, DBD::File 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 DBD::File::db::get_versions itself - but might be in the future.
get_versions
DBD::File::db::get_versions
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:
get_${drv_prefix}versions
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.
Retrieve an attribute from a table's meta information. The method signature is get_file_meta ($dbh, $table, $attr). This method is called by the injected db handle method ${drv_prefix}get_meta.
get_file_meta ($dbh, $table, $attr)
${drv_prefix}get_meta
While get_file_meta allows $table or $attr to be a list of tables or attributes to retrieve, get_single_table_meta allows only one table name and only one attribute name. A table name of '.' (single dot) is interpreted as the default table and this will retrieve the appropriate attribute globally from the dbh. This has the same restrictions as $dbh->{$attrib}.
$table
$attr
'.'
$dbh->{$attrib}
get_file_meta allows '+' and '*' as wildcards for table names and $table being a regular expression matching against the table names (evaluated without the default table). The table name '*' is all currently known tables, including the default one. The table name '+' is all table names which conform to ANSI file name restrictions (/^[_A-Za-z0-9]+$/).
'+'
'*'
The table meta information is retrieved using the get_table_meta and get_table_meta_attr methods of the table class of the implementation.
Sets an attribute in a table's meta information. The method signature is set_file_meta ($dbh, $table, $attr, $value). This method is called by the injected db handle method ${drv_prefix}set_meta.
set_file_meta ($dbh, $table, $attr, $value)
${drv_prefix}set_meta
While set_file_meta allows $table to be a list of tables and $attr to be a hash of several attributes to set, set_single_table_meta allows only one table name and only one attribute name/value pair.
The wildcard characters for the table name are the same as for get_file_meta.
The table meta information is updated using the get_table_meta and set_table_meta_attr methods of the table class of the implementation.
Clears all meta information cached about a table. The method signature is clear_file_meta ($dbh, $table). This method is called by the injected db handle method ${drv_prefix}clear_meta.
clear_file_meta ($dbh, $table)
${drv_prefix}clear_meta
Returns a SQL::Parser instance, when sql_handler is set to "SQL::Statement". The parser instance is stored in sql_parser_object.
sql_parser_object
It is not recommended to override this method.
Disconnects from a database. All local table information is discarded and the Active attribute is set to 0.
Returns information about all the types supported by DBD::File.
Returns a statement handle which is prepared to deliver information about all known tables.
Returns a list of all known table names.
Quotes a string for use in SQL statements.
Warns about a useless call (if warnings enabled) and returns. DBD::File is typically a driver which commits every action instantly when executed.
Contains the methods to deal with prepared statement handles:
Common routine to bind placeholders to a statement for execution. It is dangerous to override this method without detailed knowledge about the DBD::File internal storage structure.
Executes a previously prepared statement (with placeholders, if any).
Finishes a statement handle, discards all buffered results. The prepared statement is not discarded so the statement can be executed again.
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.
Alias for fetch.
fetch
Fetches statement handle attributes. Supported attributes (for full overview see "Statement Handle Attributes" in DBI) are NAME 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.
NAME
NULLABLE
This method usually requires extending in a derived implementation. See DBD::CSV or DBD::DBM for some example.
Allows storing of statement private attributes.
Returns the number of rows affected by the last execute. This method might return undef.
undef
Derives from DBI::SQL::Nano::Statement to provide following method:
Implements the open_table method required by SQL::Statement and DBI::SQL::Nano. All the work for opening the file(s) belonging to the table is handled and parameterized in DBD::File::Table. Unless you intend to add anything to the following implementation, an empty DBD::XXX::Statement package satisfies DBD::File.
sub open_table ($$$$$) { my ($self, $data, $table, $createMode, $lockMode) = @_; my $class = ref $self; $class =~ s/::Statement/::Table/; my $flags = { createMode => $createMode, lockMode => $lockMode, }; $self->{command} eq "DROP" and $flags->{dropMode} = 1; return $class->new ($data, { table => $table }, $flags); } # open_table
Derives from DBI::SQL::Nano::Table and provides physical file access for the table data which are stored in the files.
This method tries to map a filename to the associated table name. It is called with a partially filled meta structure for the resulting table containing at least the following attributes: f_ext, f_dir, f_lockfile and sql_identifier_case.
f_ext
f_lockfile
If a file/table map can be found then this method sets the f_fqfn, f_fqbn, f_fqln and table_name attributes in the meta structure. If a map cannot be found the table name will be undef.
f_fqfn
f_fqbn
f_fqln
table_name
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.
SUPER
It copies the following attributes from the database into the table meta data f_dir, f_ext, f_encoding, f_lock, f_schema, f_lockfile and sql_identifier_case and makes them sticky to the table.
f_encoding
f_lock
f_schema
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.
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.
Returns the table meta data. If there are none for the required table, a new one is initialized. When it fails, nothing is returned. On success, the name of the table and the meta data structure is returned.
Returns a single attribute from the table meta data. This method should be overridden when mapped attribute names should be returned for compatibility reasons.
Sets a single attribute in the table meta data. This method should be overridden when mapped attribute names should be modified for compatibility reasons.
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.
Allows set_table_meta_attr to reset meta attributes when special attributes are modified. For DBD::File, modifying one of f_file, f_dir, f_ext or f_lockfile will reset f_fqfn. DBD::DBM extends the list for dbm_type and dbm_mldbm to reset the value of dbm_tietype.
set_table_meta_attr
f_file
dbm_type
dbm_mldbm
dbm_tietype
If your DBD has calculated values in the meta data area, then call register_reset_on_modify:
register_reset_on_modify
my %reset_on_modify = ( "xxx_foo" => "xxx_bar" ); __PACKAGE__->register_reset_on_modify( \%reset_on_modify );
Called to open the table's data file.
Depending on the attributes set in the table's meta data, the following steps are performed. Unless f_dontopen is set to a true value, f_fqfn must contain the full qualified file name for the table to work on (file2table ensures this). The encoding in f_encoding is applied if set and the file is opened. If <f_fqln > (full qualified lock name) is set, this file is opened, too. Depending on the value in f_lock, the appropriate lock is set on the opened data file or lock file.
f_dontopen
<f_fqln
After this is done, a derived class might add more steps in an overridden open_file method.
open_file
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.
Implements the abstract table method for the DROP command. Discards table meta data after all files belonging to the table are closed and unlinked.
DROP
Overriding this method might be reasonable in very rare cases.
Implements the abstract table method used when accessing the table from the engine. seek is called every time the engine uses dumb algorithms for iterating over the table content.
seek
Implements the abstract table method used when dumb table algorithms for UPDATE or DELETE need to truncate the table storage after the last written row.
UPDATE
DELETE
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.
SQL::Eval::Table
The module DBD::File is currently maintained by
H.Merijn Brand < h.m.brand at xs4all.nl > and Jens Rehsack < rehsack at googlemail.com >
The original author is Jochen Wiedmann.
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.
To install DBI, copy and paste the appropriate command in to your terminal.
cpanm
cpanm DBI
CPAN shell
perl -MCPAN -e shell install DBI
For more information on module installation, please visit the detailed CPAN module installation guide.