{
    "mode": "perldoc",
    "parameter": "DBI::DBD::SqlEngine::HowTo",
    "section": "",
    "url": "https://www.chedong.com/phpMan.php/perldoc/DBI%3A%3ADBD%3A%3ASqlEngine%3A%3AHowTo/json",
    "generated": "2026-06-12T10:15:46Z",
    "synopsis": "perldoc DBI::DBD::SqlEngine::HowTo\nperldoc DBI\nperldoc DBI::DBD\nperldoc DBI::DBD::SqlEngine::Developers\nperldoc SQL::Eval\nperldoc DBI::DBD::SqlEngine\nperldoc DBI::DBD::SqlEngine::HowTo\nperldoc SQL::Statement::Embed",
    "sections": {
        "NAME": {
            "content": "DBI::DBD::SqlEngine::HowTo - Guide to create DBI::DBD::SqlEngine based driver\n",
            "subsections": []
        },
        "SYNOPSIS": {
            "content": "perldoc DBI::DBD::SqlEngine::HowTo\nperldoc DBI\nperldoc DBI::DBD\nperldoc DBI::DBD::SqlEngine::Developers\nperldoc SQL::Eval\nperldoc DBI::DBD::SqlEngine\nperldoc DBI::DBD::SqlEngine::HowTo\nperldoc SQL::Statement::Embed\n",
            "subsections": []
        },
        "DESCRIPTION": {
            "content": "This document provides a step-by-step guide, how to create a new \"DBI::DBD::SqlEngine\" based\nDBD. It expects that you carefully read the DBI documentation and that you're familiar with\nDBI::DBD and had read and understood DBD::ExampleP.\n\nThis document addresses experienced developers who are really sure that they need to invest time\nwhen writing a new DBI Driver. Writing a DBI Driver is neither a weekend project nor an easy job\nfor hobby coders after work. Expect one or two man-month of time for the first start.\n\nThose who are still reading, should be able to sing the rules of \"CREATING A NEW DRIVER\" in\nDBI::DBD.\n",
            "subsections": []
        },
        "CREATING DRIVER CLASSES": {
            "content": "Do you have an entry in DBI's DBD registry? DBI::DBD::SqlEngine expect having a unique prefix\nfor every driver class in inheritance chain.\n\nIt's easy to get a prefix - just drop the DBI team a note (\"GETTINGHELP\" in DBI). If you want\nfor some reason hide your work, take a look at Class::Method::Modifiers how to wrap a private\nprefix method around existing \"driverprefix\".\n\nFor this guide, a prefix of \"foo\" is assumed.\n",
            "subsections": [
                {
                    "name": "Sample Skeleton",
                    "content": "package DBD::Foo;\n\nuse strict;\nuse warnings;\nuse vars qw($VERSION);\nuse base qw(DBI::DBD::SqlEngine);\n\nuse DBI ();\n\n$VERSION = \"0.001\";\n\npackage DBD::Foo::dr;\n\nuse vars qw(@ISA $impdatasize);\n\n@ISA = qw(DBI::DBD::SqlEngine::dr);\n$impdatasize = 0;\n\npackage DBD::Foo::db;\n\nuse vars qw(@ISA $impdatasize);\n\n@ISA = qw(DBI::DBD::SqlEngine::db);\n$impdatasize = 0;\n\npackage DBD::Foo::st;\n\nuse vars qw(@ISA $impdatasize);\n\n@ISA = qw(DBI::DBD::SqlEngine::st);\n$impdatasize = 0;\n\npackage DBD::Foo::Statement;\n\nuse vars qw(@ISA);\n\n@ISA = qw(DBI::DBD::SqlEngine::Statement);\n\npackage DBD::Foo::Table;\n\nuse vars qw(@ISA);\n\n@ISA = qw(DBI::DBD::SqlEngine::Table);\n\n1;\n\nTiny, eh? And all you have now is a DBD named foo which will is able to deal with temporary\ntables, as long as you use SQL::Statement. In DBI::SQL::Nano environments, this DBD can do\nnothing.\n"
                },
                {
                    "name": "Deal with own attributes",
                    "content": "Before we start doing usable stuff with our DBI driver, we need to think about what we want to\ndo and how we want to do it.\n\nDo we need tunable knobs accessible by users? Do we need status information? All this is handled\nin attributes of the database handles (be careful when your DBD is running \"behind\" a DBD::Gofer\nproxy).\n\nHow come the attributes into the DBD and how are they fetchable by the user? Good question, but\nyou should know because you've read the DBI documentation.\n\n\"DBI::DBD::SqlEngine::db::FETCH\" and \"DBI::DBD::SqlEngine::db::STORE\" taking care for you - all\nthey need to know is which attribute names are valid and mutable or immutable. Tell them by\nadding \"initvalidattributes\" to your db class:\n\nsub initvalidattributes\n{\nmy $dbh = $[0];\n\n$dbh->SUPER::initvalidattributes ();\n\n$dbh->{foovalidattrs} = {\nfooversion         => 1,   # contains version of this driver\nfoovalidattrs     => 1,   # contains the valid attributes of foo drivers\nfooreadonlyattrs  => 1,   # contains immutable attributes of foo drivers\nfoobar             => 1,   # contains the bar attribute\nfoobaz             => 1,   # contains the baz attribute\nfoomanager         => 1,   # contains the manager of the driver instance\nfoomanagertype    => 1,   # contains the manager class of the driver instance\n};\n$dbh->{fooreadonlyattrs} = {\nfooversion         => 1,   # ensure no-one modifies the driver version\nfoovalidattrs     => 1,   # do not permit one to add more valid attributes ...\nfooreadonlyattrs  => 1,   # ... or make the immutable mutable\nfoomanager         => 1,   # manager is set internally only\n};\n\nreturn $dbh;\n}\n\nWoooho - but now the user cannot assign new managers? This is intended, overwrite \"STORE\" to\nhandle it!\n\nsub STORE ($$$)\n{\nmy ( $dbh, $attrib, $value ) = @;\n\n$dbh->SUPER::STORE( $attrib, $value );\n\n# we're still alive, so no exception is thrown ...\n# by DBI::DBD::SqlEngine::db::STORE\nif ( $attrib eq \"foomanagertype\" )\n{\n$dbh->{foomanager} = $dbh->{foomanagertype}->new();\n# ... probably correct some states based on the new\n# foomanagertype - see DBD::Sys for an example\n}\n}\n\nBut ... my driver runs without a manager until someone first assignes a \"foomanagertype\".\nWell, no - there're two places where you can initialize defaults:\n\nsub initdefaultattributes\n{\nmy ($dbh, $phase) = @;\n\n$dbh->SUPER::initdefaultattributes($phase);\n\nif( 0 == $phase )\n{\n# init all attributes which have no knowledge about\n# user settings from DSN or the attribute hash\n$dbh->{foomanagertype} = \"DBD::Foo::Manager\";\n}\nelsif( 1 == $phase )\n{\n# init phase with more knowledge from DSN or attribute\n# hash\n$dbh->{foomanager} = $dbh->{foomanagertype}->new();\n}\n\nreturn $dbh;\n}\n\nSo far we can prevent the users to use our database driver as data storage for anything and\neverything. We care only about the real important stuff for peace on earth and alike attributes.\nBut in fact, the driver still can't do anything. It can do less than nothing - meanwhile it's\nnot a stupid storage area anymore.\n"
                },
                {
                    "name": "User comfort",
                    "content": "\"DBI::DBD::SqlEngine\" since 0.05 consolidates all persistent meta data of a table into a single\nstructure stored in \"$dbh->{sqlmeta}\". While DBI::DBD::SqlEngine provides only readonly access\nto this structure, modifications are still allowed.\n\nPrimarily DBI::DBD::SqlEngine provides access via the setters \"newsqlenginemeta\",\n\"getsqlenginemeta\", \"getsingletablemeta\", \"setsingletablemeta\", \"setsqlenginemeta\"\nand \"clearsqlenginemeta\". Those methods are easily accessible by the users via the\n\"$dbh->func ()\" interface provided by DBI. Well, many users don't feel comfortize when calling\n\n# don't require extension for tables cars\n$dbh->func (\"cars\", \"fext\", \".csv\", \"setsqlenginemeta\");\n\nDBI::DBD::SqlEngine will inject a method into your driver to increase the user comfort to allow:\n\n# don't require extension for tables cars\n$dbh->foosetmeta (\"cars\", \"fext\", \".csv\");\n\nBetter, but here and there users likes to do:\n\n# don't require extension for tables cars\n$dbh->{footables}->{cars}->{fext} = \".csv\";\n\nThis interface is provided when derived DBD's define following in \"initvalidattributes\"\n(re-capture \"Deal with own attributes\"):\n\nsub initvalidattributes\n{\nmy $dbh = $[0];\n\n$dbh->SUPER::initvalidattributes ();\n\n$dbh->{foovalidattrs} = {\nfooversion         => 1,   # contains version of this driver\nfoovalidattrs     => 1,   # contains the valid attributes of foo drivers\nfooreadonlyattrs  => 1,   # contains immutable attributes of foo drivers\nfoobar             => 1,   # contains the bar attribute\nfoobaz             => 1,   # contains the baz attribute\nfoomanager         => 1,   # contains the manager of the driver instance\nfoomanagertype    => 1,   # contains the manager class of the driver instance\nfoometa            => 1,   # contains the public interface to modify table meta attributes\n};\n$dbh->{fooreadonlyattrs} = {\nfooversion         => 1,   # ensure no-one modifies the driver version\nfoovalidattrs     => 1,   # do not permit one to add more valid attributes ...\nfooreadonlyattrs  => 1,   # ... or make the immutable mutable\nfoomanager         => 1,   # manager is set internally only\nfoometa            => 1,   # ensure public interface to modify table meta attributes are immutable\n};\n\n$dbh->{foometa} = \"footables\";\n\nreturn $dbh;\n}\n\nThis provides a tied hash in \"$dbh->{footables}\" and a tied hash for each table's meta data in\n\"$dbh->{footables}->{$tablename}\". Modifications on the table meta attributes are done using\nthe table methods:\n\nsub gettablemetaattr { ... }\nsub settablemetaattr { ... }\n\nBoth methods can adjust the attribute name for compatibility reasons, e.g. when former versions\nof the DBD allowed different names to be used for the same flag:\n\nmy %compatmap = (\nabc => 'fooabc',\nxyz => 'fooxyz',\n);\nPACKAGE->registercompatmap( \\%compatmap );\n\nIf any user modification on a meta attribute needs reinitialization of the meta structure (in\ncase of \"DBI::DBD::SqlEngine\" these are the attributes \"ffile\", \"fdir\", \"fext\" and\n\"flockfile\"), inform DBI::DBD::SqlEngine by doing\n\nmy %resetonmodify = (\nfooxyz => \"foobar\",\nfooabc => \"foobar\",\n);\nPACKAGE->registerresetonmodify( \\%resetonmodify );\n\nThe next access to the table meta data will force DBI::DBD::SqlEngine to re-do the entire meta\ninitialization process.\n\nAny further action which needs to be taken can handled in \"tablemetaattrchanged\":\n\nsub tablemetaattrchanged\n{\nmy ($class, $meta, $attrib, $value) = @;\n...\n$class->SUPER::tablemetaattrchanged ($meta, $attrib, $value);\n}\n\nThis is done before the new value is set in $meta, so the attribute changed handler can act\ndepending on the old value.\n"
                },
                {
                    "name": "Dealing with Tables",
                    "content": "Let's put some life into it - it's going to be time for it.\n\nThis is a good point where a quick side step to SQL::Statement::Embed will help to shorten the\nnext paragraph. The documentation in SQL::Statement::Embed regarding embedding in own DBD's\nworks pretty fine with SQL::Statement and DBI::SQL::Nano.\n\nSecond look should go to DBI::DBD::SqlEngine::Developers to get a picture over the driver part\nof the table API. Usually there isn't much to do for an easy driver.\n"
                },
                {
                    "name": "Testing",
                    "content": "Now you should have your first own DBD. Was easy, wasn't it? But does it work well? Prove it by\nwriting tests and remember to use dbdeditmmattribs from DBI::DBD to ensure testing even rare\ncases.\n"
                }
            ]
        },
        "AUTHOR": {
            "content": "This guide is written by Jens Rehsack. DBI::DBD::SqlEngine is written by Jens Rehsack using code\nfrom DBD::File originally written by Jochen Wiedmann and Jeff Zucker.\n\nThe module DBI::DBD::SqlEngine is currently maintained by\n\nH.Merijn Brand < h.m.brand at xs4all.nl > and Jens Rehsack < rehsack at googlemail.com >\n",
            "subsections": []
        },
        "COPYRIGHT AND LICENSE": {
            "content": "Copyright (C) 2010 by H.Merijn Brand & Jens Rehsack\n\nAll rights reserved.\n\nYou may freely distribute and/or modify this module under the terms of either the GNU General\nPublic License (GPL) or the Artistic License, as specified in the Perl README file.\n",
            "subsections": []
        }
    },
    "summary": "DBI::DBD::SqlEngine::HowTo - Guide to create DBI::DBD::SqlEngine based driver",
    "flags": [],
    "examples": [],
    "see_also": []
}