DBI::DB...::HowTo(3)

💖 DBI::DBD::SqlEngine::HowTo 💖

User Contributed Perl Documentation · part of the DBI::DBD::SqlEngine universe · bestie edition

---

✨ NAME ✨

DBI::DBD::SqlEngine::HowTo — the guide to creating your very own DBI::DBD::SqlEngine based driver 🛠️✨

Like, it's literally right there in the name. HowTo. We're gonna teach you how to. 💅

---

🌸 SYNOPSIS 🌸

Okay so before you do anything, you read. That's the vibe. Go through these, bestie:

perldoc DBI::DBD::SqlEngine::HowTo
perldoc DBI
perldoc DBI::DBD
perldoc DBI::DBD::SqlEngine::Developers
perldoc SQL::Eval
perldoc DBI::DBD::SqlEngine
perldoc DBI::DBD::SqlEngine::HowTo
perldoc SQL::Statement::Embed

Yes, DBI::DBD::SqlEngine::HowTo shows up twice. It said what it said. Read it twice, you'll probably need to. 👑 (jk, but also not jk.)

---

🦋 DESCRIPTION 🦋

So here's the tea: this doc is a step-by-step guide for creating a brand-new DBD that's built on top of DBI::DBD::SqlEngine. 🌈

Before you roll up in here, there are some prereqs, and I'm gonna be so fr fr with you about them:

• You actually read the DBI documentation. Carefully. Not skimmed. Read. 👀
• You're already familiar with DBI::DBD.
• You've read DBD::ExampleP and you understood it. Read and understood. Both. That's the bar. 🫶

---

And like, who is this even for? This document is addressed to experienced developers who are really sure — like, genuinely, truly sure — that they need to invest the time into writing a new DBI Driver. 😭

Warning, bestie: 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 just for the first start. ⏳💀

That's the first start. As in you haven't even started starting yet. Not me hyping up the difficulty but it's giving "commit or don't" energy. 🎀

---

But if you're still reading after all that? 💖 That's main character energy. You should be able to sing the rules of "CREATING A NEW DRIVER" in DBI::DBD. 🎤👑 Sing them. Out loud. We'll wait.

---

✨ CREATING DRIVER CLASSES ✨

Okay bestie, so do you have an entry in DBI's DBD registry? Because DBI::DBD::SqlEngine expects a unique prefix for every driver class in the inheritance chain. Like, non-negotiable.

Good news: getting a prefix is easy 💅 — just drop the DBI team a note ("GETTING_HELP" in DBI). And if you're feeling mysterious and want to hide your work for some reason, go peek at Class::Method::Modifiers to see how to wrap a private prefix method around the existing driver_prefix.

For this whole guide, we're rolling with a prefix of foo_. Cute, right? 🎀

🌸 Sample Skeleton 🌸

package DBD::Foo;

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

use DBI ();

our $VERSION = "0.001";

package DBD::Foo::dr;

our @ISA = qw(DBI::DBD::SqlEngine::dr);
our $imp_data_size = 0;

package DBD::Foo::db;

our @ISA = qw(DBI::DBD::SqlEngine::db);
our $imp_data_size = 0;

package DBD::Foo::st;

our @ISA = qw(DBI::DBD::SqlEngine::st);
our $imp_data_size = 0;

package DBD::Foo::Statement;

our @ISA = qw(DBI::DBD::SqlEngine::Statement);

package DBD::Foo::Table;

our @ISA = qw(DBI::DBD::SqlEngine::Table);

1;

Tiny, right?? 😭 And after all that, literally all you have is a DBD named foo that can deal with temporary tables — and only as long as you use SQL::Statement. In DBI::SQL::Nano environments, this DBD can do nothing. Nothing!! A whole driver with zero tasks. It's giving unemployed. 💀

---

🦋 Deal with own attributes 🦋

Before we start doing actually usable stuff with our DBI driver, we gotta think about what we want to do and how we want to do it. Big brain hours.

Do we need tunable knobs that users can reach? Do we need status info? All of that lives in the attributes of the database handles — and heads up, bestie: be careful when your DBD is running "behind" a DBD::Gofer proxy. 🫶

So how do the attributes get into the DBD, and how does the user fetch them? Great question — and honestly you should already know this because you've read the DBI documentation. Periodt. 📚

DBI::DBD::SqlEngine::db::FETCH and DBI::DBD::SqlEngine::db::STORE are doing that work for you 💖 — all they need to know is which attribute names are valid and which ones are mutable or immutable. So just tell them! Add init_valid_attributes to your db class like this:

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
    };
    $dbh->{foo_readonly_attrs} = {
        foo_version         => 1,   # ensure no-one modifies the driver version
        foo_valid_attrs     => 1,   # do not permit one to add more valid attributes ...
        foo_readonly_attrs  => 1,   # ... or make the immutable mutable
        foo_manager         => 1,   # manager is set internally only
    };

    return $dbh;
}

Woooho 🎉 — but wait, now the user can't assign new managers?! That's intended, bestie. If you want that, overwrite STORE to handle it:

sub STORE ($$$) {
    my ( $dbh, $attrib, $value ) = @_;

    $dbh->SUPER::STORE( $attrib, $value );

    # we're still alive, so no exception is thrown ...
    # by DBI::DBD::SqlEngine::db::STORE
    if ( $attrib eq "foo_manager_type" ) {
        $dbh->{foo_manager} = $dbh->{foo_manager_type}->new();
        # ... probably correct some states based on the new
        # foo_manager_type - see DBD::Sys for an example
    }
}

But... my driver runs with no manager at all until someone first assignes a "foo_manager_type"?? 🙈 Nah, no worries — there are two places where you can initialize defaults:

sub init_default_attributes {
    my ($dbh, $phase) = @_;

    $dbh->SUPER::init_default_attributes($phase);

    if( 0 == $phase ) {
        # init all attributes which have no knowledge about
        # user settings from DSN or the attribute hash
        $dbh->{foo_manager_type} = "DBD::Foo::Manager";
    }
    elsif( 1 == $phase ) {
        # init phase with more knowledge from DSN or attribute
        # hash
        $dbh->{foo_manager} = $dbh->{foo_manager_type}->new();
    }

    return $dbh;
}

So at this point we can stop users from using our database driver as a data storage for absolutely anything and everything. 💅 We care only about the real important stuff for peace on earth and alike attributes. But ngl, the driver still can't do anything. Like, it can do less than nothing — meanwhile it's not a stupid storage area anymore. Character development, honestly. 🌱

---

💅 User comfort 💅

DBI::DBD::SqlEngine, since version 0.05, consolidates all persistent meta data of a table into a single structure stored in $dbh->{sql_meta} ✨. And while DBI::DBD::SqlEngine only provides readonly access to this structure, modifications are still allowed. Rules are rules, but loopholes are loopholes.

Primarily, DBI::DBD::SqlEngine gives you access via the setters new_sql_engine_meta, get_sql_engine_meta, get_single_table_meta, set_single_table_meta, set_sql_engine_meta and clear_sql_engine_meta. Those are super easy for users to reach via the $dbh->func () interface that DBI provides. But lowkey, lots of users do not feel comfortize when calling:

# don't require extension for tables cars
$dbh->func ("cars", "f_ext", ".csv", "set_sql_engine_meta");

So DBI::DBD::SqlEngine will inject a method into your driver to level up the user comfort and allow:

# don't require extension for tables cars
$dbh->foo_set_meta ("cars", "f_ext", ".csv");

Better! 🎀 But here and there users like to do:

# don't require extension for tables cars
$dbh->{foo_tables}->{cars}->{f_ext} = ".csv";

And that interface shows up when derived DBD's define the following in init_valid_attributes (re-capture Deal with own 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 one 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 hands you 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 happen through the table methods:

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

And if any user modification on a meta attribute needs a reinitialization of the meta structure (in the case of DBI::DBD::SqlEngine, those attributes are f_file, f_dir, f_ext and f_lockfile 👀), you inform DBI::DBD::SqlEngine by doing:

my %reset_on_modify = (
                        foo_xyz => "foo_bar",
                        foo_abc => "foo_bar",
                      );
__PACKAGE__->register_reset_on_modify( \%reset_on_modify );

That next access to the table meta data will force DBI::DBD::SqlEngine to re-do the entire meta initialization process. Full reset, no cap. 🔄

Any further action that needs to be taken can be handled in table_meta_attr_changed:

sub table_meta_attr_changed {
    my ($class, $meta, $attrib, $value) = @_;
    ...
    $class->SUPER::table_meta_attr_changed ($meta, $attrib, $value);
}

And heads up: this happens before the new value is set in $meta, so the attribute-changed handler can act depending on the old value. Order matters, bestie. ⭐

---

👑 Dealing with Tables 👑

Let's put some life into it — it's going to be time for it. 💖

This is a good spot for a quick side step over to SQL::Statement::Embed, which will help shorten the next paragraph. The documentation in SQL::Statement::Embed about embedding in your own DBD's works pretty fine with both SQL::Statement and DBI::SQL::Nano. 🦋

Second look should go to DBI::DBD::SqlEngine::Developers to get a picture of the driver part of the table API. Usually there isn't much to do for an easy driver — which is honestly iconic of it. 🌈

---

🧚 Testing 🧚

Now you should have your first own DBD. Easy, wasn't it? 😌 But does it actually work well?? Prove it by writing tests 📝 — and remember to use dbd_edit_mm_attribs from DBI::DBD to ensure testing even rare cases. Rare cases deserve love too. 🍓

---

🌸 AUTHOR 🌸

This guide is written by Jens Rehsack. DBI::DBD::SqlEngine is written by Jens Rehsack using code from DBD::File, which was originally written by Jochen Wiedmann and Jeff Zucker. Legacy collab energy, we love to see it. 🫶

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. Slay, open source. ✨

---

okay that's a wrap on part 2 bestie 🎀 this page is from perl v5.42.3, dated 2026-10-19 — and it's literally the DBI::DB...::HowTo(3) page, so go be the main character of your own DBD now. periodt. 💅🔥