# info > DBI::DBD::SqlEngine::Developers

---
type: CommandReference
command: DBI::DBD::SqlEngine::Developers
mode: perldoc
section: 3pm
source: perldoc
---

## Quick Reference

- `DBD::Foo::db->init_valid_attributes()` — initialize valid and readonly attribute lists
- `DBD::Foo::db->init_default_attributes($phase)` — phase‑based attribute initialization
- `DBD::Foo::db->set_versions()` — set version attributes (f_version, sql_nano_version, etc.)
- `DBD::Foo::db->get_versions($dbh, $table)` — return version information
- `DBD::Foo::Table->bootstrap_table_meta($meta, $table)` — initialise table meta data
- `DBD::Foo::Table->init_table_meta($meta, $table)` — expensive meta initialisation
- `DBD::Foo::Table->register_reset_on_modify(\%map)` — register attributes that reset calculated ones
- `DBD::Foo::Table->register_compat_map(\%map)` — map old attribute names to new ones
- `DBD::Foo::DataSource->complete_table_name($meta, $table, $respect_case)` — resolve table name to resource
- `DBD::Foo::TableSource->data_sources($drh, $attrs)` — return list of DSNs

## Name

**DBI::DBD::SqlEngine::Developers** — Developers documentation for DBI::DBD::SqlEngine.

## Synopsis

perl
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 { ... }

# optional optimisations:
sub update_current_row { ... }
sub update_specific_row { ... }
sub update_one_row { ... }
sub insert_new_row { ... }
sub delete_current_row { ... }
sub delete_one_row { ... }
## Options (methods)

### DBI::DBD::SqlEngine (driver package)

- `driver($class, $attr)` — called by DBI; bootstraps the driver. Override only if extra initialization needed.
- `setup_driver` — automatically called by `driver()`; do not call manually.

### DBI::DBD::SqlEngine::dr

- `connect($dsn, $user, $pass, \%attr)` — creates a new database handle. Calls `init_default_attributes` in two phases (0 and 1). Modern drivers can override `init_default_attributes` to handle DSN/attr.
- `data_sources($drh, $attrs)` — returns a list of DSNs using `$dbh->{sql_table_source}`.
- `disconnect_all` — no-op (no driver cache).

### DBI::DBD::SqlEngine::db

- `ping` — returns `$dbh->{Active}`.
- `prepare($statement)` — creates a statement handle; do not override.
- `validate_FETCH_attr($dbh, $attrib)` — validate attribute name before FETCH; may throw.
- `FETCH($dbh, $attrib)` — fetch handle attribute; adds driver prefix if missing; validates against `$drv_prefix . "_valid_attrs"` and returns copy for readonly attributes.
- `validate_STORE_attr($dbh, $attrib, $value)` — validate attribute name/value before STORE; may throw.
- `STORE($dbh, $attrib, $value)` — store handle attribute; adds prefix, validates, rejects modifying readonly attributes.
- `set_versions($dbh)` — sets `f_version`, `sql_nano_version`, `sql_statement_version`, `${prefix}_version`. Call `SUPER::set_versions` when overriding.
- `init_valid_attributes($dbh)` — initialises `sql_valid_attrs` and `sql_readonly_attrs`. Call `SUPER::init_valid_attributes` first.
- `init_default_attributes($dbh, $phase)` — phase‑based initialisation. Sets `sql_identifier_case`, `sql_quoted_identifier_case`, `sql_handler`, `sql_init_order`, `sql_meta`, `sql_engine_version`, `sql_nano_version`, `sql_statement_version`. Adds driver‑specific valid/readonly attrs. Call `SUPER::init_default_attributes` when overriding.
- `get_versions($dbh, $table)` — returns version info (DBI, Perl, DBI::DBD::SqlEngine, SQL handler). Calls `get_${drv_prefix}versions` if available.
- `sql_parser_object($dbh)` — returns a `SQL::Parser` instance when `sql_handler` is `SQL::Statement`.
- `disconnect($dbh)` — discards table info, sets `Active` to 0.
- `type_info_all($dbh)` — returns all supported types.
- `table_info($dbh, $catalog, $schema, $table, $type)` — returns a statement handle for table info.
- `list_tables($dbh)` — returns list of known table names.
- `quote($dbh, $string)` — quotes a string for SQL.
- `commit($dbh)` — warns and returns (auto‑commit driver).
- `rollback($dbh)` — warns and returns (auto‑commit driver).

**Important attributes:**

- `sql_init_order` — hash of priorities to arrays of attribute keys to initialise in order. Default: `{ 0 => [qw(Profile RaiseError PrintError AutoCommit)], 90 => [ "sql_meta", $dbh->{$drv_pfx_meta} ] }`. Unlisted keys default to priority 50.
- `sql_init_phase` — set during initialisation (0 or 1); removed in `init_done`.
- `sql_engine_in_gofer` — true if operated via DBD::Gofer; makes handle read‑only.
- `sql_table_source` — class for data sources and tables.
- `sql_data_source` — class for handling table resources.
- `sql_dialect` — `ANSI`, `CSV`, or `AnyData` (default `CSV`). Set before any statement.

### DBI::DBD::SqlEngine::st

- `bind_param($sth, $param, $value, \%attr)` — binds placeholders.
- `execute($sth, @bind_values)` — executes prepared statement.
- `finish($sth)` — discards buffered results; statement remains preparable.
- `fetch($sth)` — fetches next row (alias `fetchrow_arrayref`).
- `FETCH($sth, $attrib)` — fetch statement attribute; supports `NAME`, `TYPE`, `PRECISION`, `NULLABLE`.
- `STORE($sth, $attrib, $value)` — store statement attribute.
- `rows($sth)` — returns number of rows affected; may return `undef`.

### DBI::DBD::SqlEngine::TableSource

- `data_sources($class, $drh, $attrs)` — return list of DSNs.
- `avail_tables($class, $drh)` — return list of available tables.

### DBI::DBD::SqlEngine::DataSource

- `complete_table_name($self, $meta, $table, $respect_case)` — resolve table name to a resource (e.g., file on disk).
- `open_data($self, $meta, $attrs, $flags)` — open the data resource; after success, meta is ready for data accessors.

### DBI::DBD::SqlEngine::Statement

- `open_table($self, $dbh, $meta, $data, $table)` — default implementation; override in derived class.

### DBI::DBD::SqlEngine::Table

- `bootstrap_table_meta($meta, $table, $dbh)` — initialise table meta; copies `ReadOnly`, `sql_identifier_case`, `sql_data_source` from dbh. Call `SUPER::bootstrap_table_meta` at end.
- `init_table_meta($meta, $table, $dbh)` — initialise expensive meta attributes after file/table name mapping.
- `get_table_meta($dbh, $table)` — returns meta for table; bootstraps if needed, applies name mapping shortcuts.
- `get_table_meta_attr($meta, $attribute)` — returns single attribute; applies compat map.
- `set_table_meta_attr($meta, $attribute, $value)` — sets attribute; applies compat map; triggers `table_meta_attr_changed`.
- `table_meta_attr_changed($meta, $attribute)` — resets calculated attributes as per `register_reset_on_modify`.
- `register_reset_on_modify(\%map)` — registers attributes that cause reset of other attributes.
- `register_compat_map(\%map)` — registers old‑to‑new attribute name mappings.
- `open_data($meta, $attrs, $flags)` — forwards to `$meta->{sql_data_source}->open_data()`.
- `new($dbh, $table, $data)` — creates table object: 1) get meta, 2) open data, 3) bless. Do not override; use `open_data`, `bootstrap_table_meta`, `init_table_meta` instead.

## Examples

### Connecting with custom attributes

perl
my $dbh = DBI->connect("dbi:DBM:", undef, undef, {
    f_dir      => "/path/to/dbm/databases",
    dbm_type   => "BerkeleyDB",
    dbm_mldbm  => "JSON",
    dbm_tables => {
        quick => {
            dbm_type  => "GDBM_File",
            dbm_MLDBM => "FreezeThaw",
        },
    },
});
### Overriding `init_default_attributes` for phase‑based setup

perl
package DBD::Foo::db;
our @ISA = qw(DBI::DBD::SqlEngine::db);

sub init_default_attributes {
    my ($dbh, $phase) = @_;
    $dbh->SUPER::init_default_attributes($phase);
    if ($phase == 0) {
        # early setup, e.g., set driver prefix
    } elsif ($phase == 1) {
        # late setup, e.g., open default files
    }
}
### Registering reset‑on‑modify and compat maps

perl
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);
## See Also

- [DBI::DBD](https://metacpan.org/pod/DBI::DBD) — base class for DBD development
- [DBI::DBD::SqlEngine](https://metacpan.org/pod/DBI::DBD::SqlEngine) — SQL engine implementation
- [DBI::DBD::SqlEngine::HowTo](https://metacpan.org/pod/DBI::DBD::SqlEngine::HowTo) — step‑by‑step guide
- [DBD::File](https://metacpan.org/pod/DBD::File) — file‑based DBD example
- [DBD::CSV](https://metacpan.org/pod/DBD::CSV) — CSV driver example
- [DBD::DBM](https://metacpan.org/pod/DBD::DBM) — DBM driver example
- [SQL::Statement](https://metacpan.org/pod/SQL::Statement) — SQL parser engine
- [SQL::Eval](https://metacpan.org/pod/SQL::Eval) — table evaluation abstraction

## Exit Codes

Not documented.