DBI::DB...velopers(3)

💖 NAME 💖

DBI::DBD::SqlEngine::Developers — the developers documentation for DBI::DBD::SqlEngine. That's it, that's the whole name section, no cap. You're reading the page that lives at DBI::DBD::SqlEngine::Developers(3) in the User Contributed Perl Documentation, and it's literally the glow-up guide for anyone writing a DBD driver on top of DBI::DBD::SqlEngine. 🫶

---

✨ SYNOPSIS ✨

okay bestie, here's the whole vibe of a driver skeleton at a glance — read it and weep (affectionately):

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 — that's you, if you're out here writing DBI drivers based on DBI::DBD::SqlEngine. 💅 It supplements DBI::DBD and DBI::DBD::SqlEngine::HowTo, and bestie, you genuinely should read those first. Like, actually. This one assumes you already know the basics and is here to spill the deeper lore.

---

👑 CLASSES 👑

Every DBI driver has to provide exactly one package-global driver method and three DBI-related classes. That's the assignment. Here's the whole cast of characters:

🦋 DBI::DBD::SqlEngine::dr

The Driver package — it holds all the methods DBI calls indirectly through the DBI interface. Like, you never call them yourself, DBI does:

DBI->connect ('DBI:DBM:', undef, undef, {})

# invokes
package DBD::DBM::dr;
our @ISA = qw(DBI::DBD::SqlEngine::dr);

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

Same situation for data_sources () and disconnect_all().

Here's the tea: 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. But — if you need some extra initialization that just does not fit into init_valid_attributes() and init_default_attributes() of your ::db class, then the connect method might be the final place you can modify. Last-chance saloon energy. 🫡

🦋 DBI::DBD::SqlEngine::db

Contains the methods that get called through DBI database handles ($dbh). For example:

$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 writing DBI drivers based on DBI::DBD::SqlEngine need to override the methods set_versions and init_valid_attributes. Not optional, babe.

🦋 DBI::DBD::SqlEngine::TieMeta

Provides the tie-magic for $dbh->{$drv_pfx . "_meta"}. It routes STORE through $drv->set_sql_engine_meta() and FETCH through $drv->get_sql_engine_meta(). DELETE? Not supported, sorry bestie — you have to execute a DROP TABLE statement, where applicable.

🦋 DBI::DBD::SqlEngine::TieTables

Provides the tie-magic for tables in $dbh->{$drv_pfx . "_meta"}. Routes STORE through $tblClass->set_table_meta_attr() and FETCH through $tblClass->get_table_meta_attr(). And 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. Example:

$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 the derived driver's statement engine. It implements open_table.

🦋 DBI::DBD::SqlEngine::Table

This one contains all the tailoring between the SQL engine's requirements and the DBI::DBD::SqlEngine magic for finding the right tables and storage. It builds bridges between sql_meta handling of DBI::DBD::SqlEngine::db, table initialization for SQL engines, and meta object attribute management for derived drivers. Literally the social butterfly of the whole architecture. 🌸

---

💜 DBI::DBD::SqlEngine 💜

This is the main package containing the routines that initialize DBI::DBD::SqlEngine-based DBI drivers. First and foremost, the DBI::DBD::SqlEngine::driver method gets invoked — either directly from DBI when the driver is initialized, or from the derived class. Like so:

package DBD::DBM;

use base qw( DBI::DBD::SqlEngine );

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

Now listen: it is not necessary to implement your own driver method as long as you don't need additional initialization (like installing more private driver methods). And you do not need to call setup_driver — DBI::DBD::SqlEngine takes care of it for you. Sit back, let it cook. 👑

---

🌟 DBI::DBD::SqlEngine::dr 🌟

The driver package contains the methods DBI calls indirectly via the DBI interface (peep "DBI Class Methods" in DBI).

DBI::DBD::SqlEngine-based DBI drivers usually don't need to implement anything here — it's 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 you call:

DBI->connect( "dbi:Foo", , , { ... } );

First it instantiates a new driver using DBI::_new_dbh. After that, the initial bootstrap of the newly instantiated driver happens via:

$dbh->func( 0, "init_default_attributes" );

That first argument, 0, signals that this is the very first call to init_default_attributes. Modern drivers understand that and do early stage setup right here, after calling:

package 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 gets passed all the way down until DBI::DBD::SqlEngine::db::init_default_attributes, connect() recognizes a modern driver and initializes the attributes from the DSN and $attr arguments passed via DBI->connect( $dsn, $user, $pass, \%attr ). Sniffing out the modern ones, iconic behaviour honestly.

Then, at the end of the attribute initialization after phase 0, connect() invokes init_default_attributes again, this time 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. Truly the do-nothing method of all time. 💀

---

💅 DBI::DBD::SqlEngine::db 💅

This package defines the database methods, the ones that get called via the DBI database handle $dbh.

Methods provided by DBI::DBD::SqlEngine::db:

🎀 ping

Simply returns the content of the Active attribute. Override it if your driver needs more complicated actions here. Low effort, high impact.

🎀 prepare

Prepares a new SQL statement to execute. Returns a statement handle, $sth — an instance of DBD:XXX::st. It is neither required nor recommended to override this method. So like, don't. 🙈

🎀 validate_FETCH_attr

Called by FETCH to let inherited drivers do their own attribute name validation. The calling convention is similar to FETCH, and the return value is the approved attribute name:

return $validated_attribute_name;

If validation fails (e.g. you're accessing a private attribute or something like that), validate_FETCH_attr is permitted to throw an exception. Go off, honestly.

🎀 FETCH

Fetches an attribute of a DBI database object. Private handle attributes must have a prefix — this is mandatory, no skipping. If a requested attribute is detected as a private attribute without a valid prefix, the driver prefix (written as $drv_prefix) gets 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. Protected. Guarded. Untouchable. ✨

🎀 validate_STORE_attr

Called by STORE to let inherited drivers do their own attribute name validation. The calling convention is similar to STORE, and the return value is the approved attribute name followed by the approved new value:

return ($validated_attribute_name, $validated_attribute_value);

And when validation fails — like somebody's out here touching a private attribute, the nerve 🙄 — validate_STORE_attr is fully permitted to just throw an exception. DBI::DBD::SqlEngine::db::validate_STORE_attr will straight up throw when someone tries to assign any value other than SQL_IC_UPPER .. SQL_IC_MIXED to $dbh->{sql_identifier_case} or $dbh->{sql_quoted_identifier_case}. Protecting the vibes, one exception at a time. ✨

STORE

Stores a database private attribute. Okay so private handle attributes have to have a prefix — that's not optional, bestie, it's mandatory. If some requested attribute shows up as a private attribute but with no valid prefix, the driver prefix (written here as $drv_prefix) gets added on for you.

If the database handle has an attribute named ${drv_prefix}_valid_attrs — then any attribute name that isn't listed in that hash makes this method croak. Like, immediately. 🫠

And if the database handle has an attribute named ${drv_prefix}_readonly_attrs, then only attributes that are not listed there can be stored (once they've been initialized). Try to overwrite one of those immutable attributes and this method will croak at you. No notes.

A cute little example of a valid attributes list lives 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 a restrictive ${prefix}_valid_attrs doesn't forbid it — ${prefix}_version.

It gets called at the end of the connect () phase. 👑

When you override this one, do not forget to invoke the superior one. Seriously. Don't ghost your parent method.

init_valid_attributes

This method is called after the database handle gets instantiated, as the very first attribute initialization.

DBI::DBD::SqlEngine::db::init_valid_attributes initializes the attributes sql_valid_attrs and sql_readonly_attrs.

Overriding this? Don't forget to invoke the superior one, and preferably do it before you do literally anything else. Order matters, queen. 💅

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 isn't given, connect of DBI::DBD::SqlEngine::dr assumes you're an old-fashioned driver that isn't capable of multi-phased initialization. A vintage vibe, respect. 🎀

DBI::DBD::SqlEngine::db::init_default_attributes initializes the attributes sql_identifier_case, sql_quoted_identifier_case, sql_handler, sql_init_order, sql_meta, sql_engine_version, sql_nano_version and sql_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 holding the immutable attributes (e.g. $dbh->{dbm_readonly_attrs} = {...};), then the attributes drv_valid_attrs, drv_readonly_attrs and drv_version get 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 hand you the user-callable driver method ${prefix}versions (e.g. dbm_versions, csv_versions, ...).

The DBI::DBD::SqlEngine implementation returns all version info that DBI::DBD::SqlEngine knows about (so: DBI version, Perl version, DBI::DBD::SqlEngine version and the SQL handler version). A whole info dump, slay. 🌈

get_versions takes $dbh as its first argument and optionally a second argument containing a table name. That second argument is not evaluated in DBI::DBD::SqlEngine::db::get_versions itself — but it might be in the future. 👀

If the derived implementor class provides a method named get_${drv_prefix}versions, that gets invoked and its return value gets associated with 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 (like, say, some kind of parser version in the case of DBD::CSV, ...) if one line isn't enough room to fit all the relevant info. Real ones know.

sql_parser_object

Returns a SQL::Parser instance, when sql_handler is set to SQL::Statement. That parser instance is stored in sql_parser_object.

Not recommended to override this method. Like, don't. 🙈

disconnect

Disconnects from a database. All local table information is discarded and the Active attribute is set to 0. It's giving closure. 🦋

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. Enumerate, bestie. ✨

quote

Quotes a string for use in SQL statements.

commit

Warns about a useless call (if warnings are enabled) and returns. DBI::DBD::SqlEngine is typically a driver which commits every action instantly when it's executed, so there's nothing to do here. 💀

rollback

Warns about a useless call (if warnings are enabled) and returns. DBI::DBD::SqlEngine is typically a driver which commits every action instantly when executed — so yeah, same energy as commit. It literally already happened.

---

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. Devs, this one's for you. 🫶

sql_init_order

This attribute contains a hash with priorities as keys and an array containing the $dbh attributes to be initialized before/after other attributes.

DBI::DBD::SqlEngine initializes the 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 attribute keys that aren't listed is 50. It's well known that a lot of attributes need to be set before some table settings are initialized. For example, for DBD::DBM, when using:

my $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 that $dbh->{f_dir} must be initialized before $dbh->{sql_meta}->{quick} is initialized by the bootstrap_table_meta method of DBI::DBD::SqlEngine::Table, so that $dbh->{sql_meta}->{quick}->{f_dir} gets initialized properly. Order is the whole plot. 📖

sql_init_phase

This attribute is only set during the initialization steps of the DBI Database Driver. It contains the value of the currently running initialization phase. Currently supported phases are phase 0 and phase 1. This attribute is set in init_default_attributes and removed in init_done. Blink and it's gone. ⭐

sql_engine_in_gofer

This value has a true value in case this driver is being 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 where you modify table attributes, so please carefully watch sql_engine_in_gofer. Silent chaos, so mind it. 💀

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

Names a class which is responsible for handling table resources open and completing table names requested via SQL statements. (Yes, that's two very similar-sounding things. Stay sharp. 👀)

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 you to modify the dialect once it's instantiated, it's strongly recommended to set this flag before any statement is executed (best place is the connect attribute hash). Set it early or forever hold your peace. 🎀

---

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. Like, do you actually know? Be honest. 😭

execute

Executes a previously prepared statement (with placeholders, if any). Let's gooooo. 🔥

finish

Finishes a statement handle, discards all buffered results. The prepared statement is not discarded, so the statement can be executed again. Reusable, iconic.

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. Same girl, different name. 💅

FETCH

Fetches statement handle attributes. Supported attributes (for the 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 examples.

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

---

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 gets called whenever the user invokes any of these bestie-coded lines:

@ary = DBI->data_sources($driver);
@ary = DBI->data_sources($driver, \%attr);

@ary = $dbh->data_sources();
@ary = $dbh->data_sources(\%attr);

And avail_tables? It wakes up when the user invokes any of these:

@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 single time a \%attr argument can be passed, that \%attr object's sql_table_source attribute wins over the $dbh attribute or the driver default. It's giving main character energy for \%attr, fr fr. 👑

---

DBI::DBD::SqlEngine::DataSource 🌈

This one hands you the base functionality for dealing with tables. It's primarily designed so you can transparently access files on disk, or already-opened (file-)streams — think DBD::CSV vibes. 💅

Derived classes shall be restricted to similar functionality too (like opening streams from an archive, or 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 gets called the very first time the meta information for a table is set up:

"SELECT user.id, user.name, user.shell FROM user WHERE ..."

…and that results in opening the table user. First step of the table-open process is completing the name. So picture this — you're holding a DBD::CSV handle with these settings, bestie:

$dbh->{sql_identifier_case} = SQL_IC_LOWER;
$dbh->{f_ext} = '.lst';
$dbh->{f_dir} = '/data/web/adrmgr';

Those settings make it go looking for files matching [Uu][Ss][Ee][Rr](\.lst)?$ inside /data/web/adrmgr/. The scanning of the directory /data/web/adrmgr/ and the pattern-match check both happen inside DBD::File::DataSource::File, courtesy of the complete_table_name method. Not me being obsessed with that regex 😭

If you're intending to provide other sources of data streams than files, then on top of providing an appropriate complete_table_name method, you also need a method to open the resource:

package DBI::DBD::SqlEngine::DataSource;

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

Once open_data has run successfully, the table's meta information is in a state where the table's data accessor methods will be able to fetch/store row information. Implementation details depend heavily on the table implementation — and the most famous one is surely DBD::File::Table. ✨

---

DBI::DBD::SqlEngine::Statement 💖

Derives from DBI::SQL::Nano::Statement, just for unified naming when you're deriving new drivers. No additional feature is provided from here. It's a vibe, not a feature set. 🫶

---

DBI::DBD::SqlEngine::Table 💜

Derives from DBI::SQL::Nano::Table, again for unified naming when deriving new drivers.

You should consult the documentation of SQL::Eval::Table (see SQL::Eval) to get more info about the abstract methods of the table's base class that you have to override, plus a description of the table meta information the SQL engines expect. Go read it, iykyk. 📚

bootstrap_table_meta

Initializes a table meta structure. It can be safely overridden in a derived class, as long as the SUPER method is called at the end of the overridden method. Don't skip that part, bestie, it matters. 🙈

It copies these attributes from the database into the table meta data — $dbh->{ReadOnly} into $meta->{readonly}, plus sql_identifier_case and sql_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, so the correct directory, extension, etc. get used. ✨

init_table_meta

Initializes more attributes of the table meta data — usually the more expensive ones (like those requiring class instantiations) — once the file name and the table name could be mapped. 💸

get_table_meta

Returns the table meta data. If there is none for the required table, a new one gets 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 one is used and a mapping shortcut between the recently used table name and the already known table name is held in $dbh->{sql_meta_map}. When it fails, nothing is returned. On success, the name of the table and the meta data structure are returned. 🎀

get_table_meta_attr

Returns a single attribute from the table meta data. If the attribute name shows up in %compat_map, the attribute name gets updated from there.

set_table_meta_attr

Sets a single attribute in the table meta data. Same deal — if the attribute name shows up in %compat_map, the attribute name gets updated from there.

table_meta_attr_changed

Called whenever an attribute of the meta data is modified.

If the modified attribute requires resetting a calculated attribute, the calculated attribute gets reset (deleted from the meta data structure) and the initialized flag is removed too. The decision is made based on %register_reset_on_modify.

register_reset_on_modify

Lets set_table_meta_attr reset meta attributes when special attributes get modified. For DBD::File, modifying one of f_file, f_dir, f_ext or f_lockfile will reset f_fqfn. DBD::DBM extends that list for dbm_type and dbm_mldbm to reset the value of dbm_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

Lets get_table_meta_attr and set_table_meta_attr update the attribute name to the currently 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 gets silently forwarded to $meta->{sql_data_source}->open_data().

After that's done, a derived class might add more steps in an overridden open_file method.

new

Instantiates the table. This happens 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 your extensions in one of the above four methods. Please, bestie. I'm begging. 🙏

---

AUTHOR 👑

The module DBI::DBD::SqlEngine is currently maintained by

H.Merijn Brand < perl5 at tux.freedom.nl > and Jens Rehsack < rehsack at googlemail.com >

---

COPYRIGHT AND LICENSE 🌸

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

---

And that's a wrap on the whole page, bestie!! 🎉 This version came from the perl v5.42.3 docs, dated 2026-10-19. Go forth and derive your DBDs responsibly. Slay. 💅✨🦋