DBD::File::HowTo - Guide to create DBD::File based driver
perldoc DBD::File::HowTo perldoc DBI perldoc DBI::DBD perldoc DBD::File::Developers perldoc DBI::DBD::SqlEngine::Developers perldoc DBI::DBD::SqlEngine perldoc SQL::Eval perldoc DBI::DBD::SqlEngine::HowTo perldoc SQL::Statement::Embed perldoc DBD::File perldoc DBD::File::HowTo perldoc DBD::File::Developers
This document provides a step-by-step guide, how to create a new DBD::File based DBD. It expects that you carefully read the DBI documentation and that you're familiar with DBI::DBD and had read and understood DBD::ExampleP.
DBD::File
This document addresses experienced developers who are really sure that they need to invest time when writing a new DBI Driver. Writing a DBI Driver is neither a weekend project nor an easy job for hobby coders after work. Expect one or two man-month of time for the first start.
Those who are still reading, should be able to sing the rules of "CREATING A NEW DRIVER" in DBI::DBD.
Of course, DBD::File is a DBI::DBD::SqlEngine and you surely read DBI::DBD::SqlEngine::HowTo before continuing here.
Do you have an entry in DBI's DBD registry? For this guide, a prefix of foo_ is assumed.
foo_
package DBD::Foo; use strict; use warnings; use vars qw(@ISA $VERSION); use base qw(DBD::File); use DBI (); $VERSION = "0.001"; package DBD::Foo::dr; use vars qw(@ISA $imp_data_size); @ISA = qw(DBD::File::dr); $imp_data_size = 0; package DBD::Foo::db; use vars qw(@ISA $imp_data_size); @ISA = qw(DBD::File::db); $imp_data_size = 0; package DBD::Foo::st; use vars qw(@ISA $imp_data_size); @ISA = qw(DBD::File::st); $imp_data_size = 0; package DBD::Foo::Statement; use vars qw(@ISA); @ISA = qw(DBD::File::Statement); package DBD::Foo::Table; use vars qw(@ISA); @ISA = qw(DBD::File::Table); 1;
Tiny, eh? And all you have now is a DBD named foo which will is able to deal with temporary tables, as long as you use SQL::Statement. In DBI::SQL::Nano environments, this DBD can do nothing.
Based on DBI::DBD::SqlEngine::HowTo, we're now having a driver which could do basic things. Of course, it should now derive from DBD::File instead of DBI::DBD::SqlEngine, shouldn't it?
DBD::File extends DBI::DBD::SqlEngine to deal with any kind of files. In principle, the only extensions required are to the table class:
package DBD::Foo::Table; sub bootstrap_table_meta { my ( $self, $dbh, $meta, $table ) = @_; # initialize all $meta attributes which might be relevant for # file2table return $self->SUPER::bootstrap_table_meta($dbh, $meta, $table); } sub init_table_meta { my ( $self, $dbh, $meta, $table ) = @_; # called after $meta contains the results from file2table # initialize all missing $meta attributes $self->SUPER::init_table_meta( $dbh, $meta, $table ); }
In case DBD::File::Table::open_file doesn't open the files as the driver needs that, override it!
DBD::File::Table::open_file
sub open_file { my ( $self, $meta, $attrs, $flags ) = @_; # ensure that $meta->{f_dontopen} is set $self->SUPER::open_file( $meta, $attrs, $flags ); # now do what ever needs to be done }
Combined with the methods implemented using the SQL::Statement::Embed guide, the table is full working and you could try a start over.
DBD::File since 0.39 consolidates all persistent meta data of a table into a single structure stored in $dbh->{f_meta}. While DBD::File provides only readonly access to this structure, modifications are still allowed.
0.39
$dbh->{f_meta}
Primarily DBD::File provides access via setters get_file_meta, set_file_meta and clear_file_meta. Those methods are easily accessible by the users via the $dbh->func () interface provided by DBI. Well, many users don't feel comfortize when calling
get_file_meta
set_file_meta
clear_file_meta
$dbh->func ()
# don't require extension for tables cars $dbh->func ("cars", "f_ext", ".csv", "set_file_meta");
DBD::File will inject a method into your driver to increase the user comfort to allow:
# don't require extension for tables cars $dbh->foo_set_meta ("cars", "f_ext", ".csv");
Better, but here and there users likes to do:
# don't require extension for tables cars $dbh->{foo_tables}->{cars}->{f_ext} = ".csv";
This interface is provided when derived DBD's define following in init_valid_attributes (please compare carefully with the example in DBI::DBD::SqlEngine::HowTo):
init_valid_attributes
sub init_valid_attributes { my $dbh = $_[0]; $dbh->SUPER::init_valid_attributes (); $dbh->{foo_valid_attrs} = { foo_version => 1, # contains version of this driver foo_valid_attrs => 1, # contains the valid attributes of foo drivers foo_readonly_attrs => 1, # contains immutable attributes of foo drivers foo_bar => 1, # contains the bar attribute foo_baz => 1, # contains the baz attribute foo_manager => 1, # contains the manager of the driver instance foo_manager_type => 1, # contains the manager class of the driver instance foo_meta => 1, # contains the public interface to modify table meta attributes }; $dbh->{foo_readonly_attrs} = { foo_version => 1, # ensure no-one modifies the driver version foo_valid_attrs => 1, # do not permit to add more valid attributes ... foo_readonly_attrs => 1, # ... or make the immutable mutable foo_manager => 1, # manager is set internally only foo_meta => 1, # ensure public interface to modify table meta attributes are immutable }; $dbh->{foo_meta} = "foo_tables"; return $dbh; }
This provides a tied hash in $dbh->{foo_tables} and a tied hash for each table's meta data in $dbh->{foo_tables}->{$table_name}. Modifications on the table meta attributes are done using the table methods:
$dbh->{foo_tables}
$dbh->{foo_tables}->{$table_name}
sub get_table_meta_attr { ... } sub set_table_meta_attr { ... }
Both methods can adjust the attribute name for compatibility reasons, e.g. when former versions of the DBD allowed different names to be used for the same flag:
my %compat_map = ( abc => 'foo_abc', xyz => 'foo_xyz', ); __PACKAGE__->register_compat_map( \%compat_map );
If any user modification on a meta attribute needs reinitialization of the meta structure (in case of DBD::File these are the attributes f_file, f_dir, f_ext and f_lockfile), inform DBD::File by doing
f_file
f_dir
f_ext
f_lockfile
my %reset_on_modify = ( foo_xyz => "foo_bar", foo_abc => "foo_bar", ); __PACKAGE__->register_reset_on_modify( \%reset_on_modify );
The next access to the table meta data will force DBD::File to re-do the entire meta initialization process.
Any further action which needs to be taken can handled in table_meta_attr_changed:
table_meta_attr_changed
sub table_meta_attr_changed { my ($class, $meta, $attrib, $value) = @_; ... $class->SUPER::table_meta_attr_changed ($meta, $attrib, $value); }
This is done before the new value is set in $meta, so the attribute changed handler can act depending on the old value.
$meta
Now you should have your own DBD::File based driver. Was easy, wasn't it? But does it work well? Prove it by writing tests and remember to use dbd_edit_mm_attribs from DBI::DBD to ensure testing even rare cases.
This guide is written by Jens Rehsack. DBD::File is written by Jochen Wiedmann and Jeff Zucker.
The module DBD::File is currently maintained by
H.Merijn Brand < h.m.brand at xs4all.nl > and Jens Rehsack < rehsack at googlemail.com >
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.