man > DBD::File::Developers(3pm)

man perldoc info pydoc3 ri search

📝 NAME

DBD::File::Developers - Developers documentation for DBD::File

🚀 Quick Reference

Use Case	Command	Description
Inherit from DBD::File	use base qw(DBD::File);	Base class for DBD::File-based drivers
Override driver initialization	sub driver { ... }	Custom driver method, call SUPER::driver
Define valid private attributes	sub init_valid_attributes { ... }	Initialize f_valid_attrs and f_readonly_attrs
Custom FETCH for statement handle	sub FETCH { ... }	Override statement handle attribute fetching
Initialize table meta data	sub init_table_meta { ... }	Called after file/table mapping succeeds
Register reset-on-modify rules	__PACKAGE__->register_reset_on_modify(\%map)	Reset calculated attrs on change
Register compatibility mapping	__PACKAGE__->register_compat_map(\%map)	Map old attribute names to new
Open data file	sub open_data { ... }	Override to customize file opening
Optimize SQL operations	sub update_current_row { ... }	Advanced row update methods

📋 SYNOPSIS

package DBD::myDriver;

use base qw( DBD::File );

sub driver
{
    ...
    my $drh = $proto->SUPER::driver ($attr);
    ...
    return $drh->{class};
}

sub CLONE { ... }

package DBD::myDriver::dr;

@ISA = qw( DBD::File::dr );

sub data_sources { ... }
...

package DBD::myDriver::db;

@ISA = qw( DBD::File::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 { ... }

package DBD::myDriver::st;

@ISA = qw( DBD::File::st );

sub FETCH { ... }
sub STORE { ... }

package DBD::myDriver::Statement;

@ISA = qw( DBD::File::Statement );

package DBD::myDriver::Table;

@ISA = qw( DBD::File::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 fetch_row { ... }
sub push_row { ... }
sub push_names { ... }

# 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 how DBD developers can write DBD::File based DBI drivers. It supplements DBI::DBD and DBI::DBD::SqlEngine::Developers, which you should read first.

📂 CLASSES

Each DBI driver must provide a package global "driver" method and three DBI related classes:

🔹 DBD::File::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( DBD::File::dr );

sub connect ($$;$$$)
{
    ...
}

Similar for data_sources and 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.

🔹 DBD::File::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");

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.

🔹 DBD::File::st

Contains the methods to deal with prepared statement handles. e.g.,

$sth->execute () or die $sth->errstr;

🔹 DBD::File

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.

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.

🔹 DBD::File::dr (detailed)

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";

🔹 DBD::File::db (detailed)

This package defines the database methods, which are called via the DBI database handle $dbh.

Methods provided by DBD::File:

• ping — Simply returns the content of the Active attribute. Override when your driver needs more complicated actions.
• prepare — Prepares a new SQL statement to execute. Returns a statement handle, $sth. 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. If a requested attribute is detected as a private attribute without a valid prefix, the driver prefix is added. The attribute is verified against $dbh->{$drv_prefix . "valid_attrs"}; if not listed, croaks. If readonly, a real copy is returned.
• STORE — Stores a database private attribute. Similar validation via ${drv_prefix}_valid_attrs and ${drv_prefix}_readonly_attrs. Croaks on invalid or immutable attributes.
• set_versions — Sets f_version with the version of DBD::File. Called at the begin of connect(). When overriding, invoke the superior one.
• init_valid_attributes — Called after the database handle is instantiated. Initializes f_valid_attrs and f_readonly_attrs. When overriding, invoke the superior one, preferably before anything else. Compatibility table attribute access must be initialized here to allow DBD::File to instantiate the map tie.
• init_default_attributes — Called after the database handle is instantiated to initialize default attributes: f_dir, f_meta, f_meta_map, f_version. If the derived class provides ${drv_prefix}_valid_attrs or ${drv_prefix}_readonly_attrs, the attributes drv_valid_attrs, drv_readonly_attrs, drv_version and drv_meta are added (when available). If drv_meta is set, an attribute with that name is initialized providing restricted read/write access to table meta data via DBD::File::TieTables and DBD::File::TieMeta.
• get_single_table_meta / get_file_meta — Retrieve an attribute from a table's meta information. get_file_meta allows wildcards (+, *, regex) for table names. get_single_table_meta allows only one table and one attribute. A table name of . is interpreted as the default table.
• set_single_table_meta / set_file_meta — Set an attribute in a table's meta information. Similar wildcard support.
• clear_file_meta — Clears all meta information cached about a table.

🔹 DBD::File::st (detailed)

Contains the methods to deal with prepared statement handles:

• FETCH — Fetches statement handle attributes. Supported attributes: NAME, TYPE, PRECISION and NULLABLE (when SQL::Statement is used and a statement is successfully prepared). Returns additional information if available; otherwise defaults from DBI::DBD::SqlEngine are used. This method usually requires extending in a derived implementation.

🔹 DBD::File::TableSource::FileSystem

Provides data sources and table information on driver and database handle level.

package DBD::File::TableSource::FileSystem;

sub data_sources ($;$)
{
    my ($class, $drh, $attrs) = @_;
    ...
}

sub avail_tables
{
    my ($class, $drh) = @_;
    ...
}

The data_sources method is called when the user invokes DBI->data_sources or $dbh->data_sources. The avail_tables method is called when the user invokes $dbh->tables, $dbh->table_info, or $dbh->func("list_tables"). Every time an %attr argument can be specified, the sql_table_source attribute is preferred over the $dbh attribute or driver default.

🔹 DBD::File::DataSource::Stream

package DBD::File::DataSource::Stream;

@DBD::File::DataSource::Stream::ISA = 'DBI::DBD::SqlEngine::DataSource';

sub complete_table_name
{
    my ($self, $meta, $file, $respect_case) = @_;
    ...
}

Clears all meta attributes identifying a file: f_fqfn, f_fqbn and f_fqln. The table name is set according to $respect_case and $meta->{sql_identifier_case}.

sub apply_encoding
{
    my ($self, $meta, $fn) = @_;
    ...
}

Applies the encoding from meta information ($meta->{f_encoding}) to the file handled opened in open_data.

sub open_data
{
    my ($self, $meta, $attrs, $flags) = @_;
    ...
}

Opens (dup(2)) the file handle provided in $meta->{f_file}.

sub can_flock { ... }

Returns whether flock(2) is available or not.

🔹 DBD::File::DataSource::File

package DBD::File::DataSource::File;

sub complete_table_name ($$;$)
{
    my ($self, $meta, $table, $respect_case) = @_;
    ...
}

The method complete_table_name tries to map a filename to the associated table name. It is called with a partially filled meta structure containing f_ext, f_dir, f_lockfile and sql_identifier_case. If a file/table map can be found, it sets f_fqfn, f_fqbn, f_fqln and table_name in the meta structure. If a map cannot be found, the table name will be undef.

sub open_data ($)
{
    my ($self, $meta, $attrs, $flags) = @_;
    ...
}

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. 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.

🔹 DBD::File::Statement

Derives from DBI::SQL::Nano::Statement to provide the following method:

• open_table — 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 in DBD::File::Table. Unless you intend to add anything, 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);
}

🔹 DBD::File::Table

Derives from DBI::SQL::Nano::Table and provides physical file access for the table data stored in files.

• bootstrap_table_meta — Initializes a table meta structure. Copies f_dir, f_ext, f_encoding, f_lock, f_schema and f_lockfile from the database into the table meta data and makes them sticky. Should be called before attempting to map between file name and table name.
• init_table_meta — Initializes more attributes of the table meta data (usually more expensive ones) when the file name and table name could be mapped.
• get_table_meta — Returns the table meta data. If none exist, a new one is initialized. On success, returns the table name and meta data structure.
• 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.
• 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.
• table_meta_attr_changed — Called when an attribute of the meta data is modified. If the modified attribute requires resetting a calculated attribute, it is reset and the initialized flag is removed, 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 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 dbm_tietype.
• register_compat_map — Allows get_table_meta_attr and set_table_meta_attr to update the attribute name to the current favored one. Example: dbm_ext => "f_ext".
• open_file — Called to open the table's data file. Performs steps similar to open_data in DBD::File::DataSource::File. A derived class may add more steps in an overridden method.
• new — Instantiates the table in 3 steps: 1) get the table meta data, 2) open the data file, 3) bless the table data structure. Not recommended to override.
• drop — Implements the abstract table method for the DROP command. Discards table meta data after all files are closed and unlinked.
• seek — Implements the abstract table method used when the engine iterates over the table content.
• truncate — 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.

Consult the documentation of SQL::Eval::Table (see SQL::Eval) for more information about abstract methods and expected table meta information.

👤 AUTHOR

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 AND LICENSE

Copyright (C) 2010-2013 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.

📝 NAME 🚀 Quick Reference 📋 SYNOPSIS 📖 DESCRIPTION 📂 CLASSES 👤 AUTHOR ©️ COPYRIGHT AND LICENSE