1DBI::DBD::SqlEngine::DeUvseelropCeornst(r3i)buted Perl DDoBcIu:m:eDnBtDa:t:iSoqnlEngine::Developers(3)
2
6 DBI::DBD::SqlEngine::Developers - Developers documentation for
7 DBI::DBD::SqlEngine
8
10 package DBD::myDriver;
11 use base qw(DBI::DBD::SqlEngine);
13 sub driver
15 {
16 ...
17 my $drh = $proto->SUPER::driver($attr);
18 ...
19 return $drh->{class};
20 }
21 sub CLONE { ... }
23 package DBD::myDriver::dr;
25 @ISA = qw(DBI::DBD::SqlEngine::dr);
27 sub data_sources { ... }
29 ...
30 package DBD::myDriver::db;
32 @ISA = qw(DBI::DBD::SqlEngine::db);
34 sub init_valid_attributes { ... }
36 sub init_default_attributes { ... }
37 sub set_versions { ... }
38 sub validate_STORE_attr { my ($dbh, $attrib, $value) = @_; ... }
39 sub validate_FETCH_attr { my ($dbh, $attrib) = @_; ... }
40 sub get_myd_versions { ... }
41 sub get_avail_tables { ... }
42 package DBD::myDriver::st;
44 @ISA = qw(DBI::DBD::SqlEngine::st);
46 sub FETCH { ... }
48 sub STORE { ... }
49 package DBD::myDriver::Statement;
51 @ISA = qw(DBI::DBD::SqlEngine::Statement);
53 sub open_table { ... }
55 package DBD::myDriver::Table;
57 @ISA = qw(DBI::DBD::SqlEngine::Table);
59 my %reset_on_modify = (
61 myd_abc => "myd_foo",
62 myd_mno => "myd_bar",
63 );
64 __PACKAGE__->register_reset_on_modify( \%reset_on_modify );
65 my %compat_map = (
66 abc => 'foo_abc',
67 xyz => 'foo_xyz',
68 );
69 __PACKAGE__->register_compat_map( \%compat_map );
70 sub bootstrap_table_meta { ... }
72 sub init_table_meta { ... }
73 sub table_meta_attr_changed { ... }
74 sub open_data { ... }
75 sub new { ... }
77 sub fetch_row { ... }
79 sub push_row { ... }
80 sub push_names { ... }
81 sub seek { ... }
82 sub truncate { ... }
83 sub drop { ... }
84 # optimize the SQL engine by add one or more of
86 sub update_current_row { ... }
87 # or
88 sub update_specific_row { ... }
89 # or
90 sub update_one_row { ... }
91 # or
92 sub insert_new_row { ... }
93 # or
94 sub delete_current_row { ... }
95 # or
96 sub delete_one_row { ... }
97
99 This document describes the interface of DBI::DBD::SqlEngine for DBD
100 developers who write DBI::DBD::SqlEngine based DBI drivers. It
101 supplements DBI::DBD and DBI::DBD::SqlEngine::HowTo, which you should
102 read first.
103
105 Each DBI driver must provide a package global "driver" method and three
106 DBI related classes:
107 DBI::DBD::SqlEngine::dr
109 Driver package, contains the methods DBI calls indirectly via DBI
110 interface:
111 DBI->connect ('DBI:DBM:', undef, undef, {})
113 # invokes
115 package DBD::DBM::dr;
116 @DBD::DBM::dr::ISA = qw(DBI::DBD::SqlEngine::dr);
117 sub connect ($$;$$$)
119 {
120 ...
121 }
122 Similar for "data_sources ()" and disconnect_all().
124 Pure Perl DBI drivers derived from DBI::DBD::SqlEngine usually
126 don't need to override any of the methods provided through the
127 DBD::XXX::dr package. However if you need additional
128 initialization not fitting in init_valid_attributes() and
129 init_default_attributes() of you're ::db class, the connect method
130 might be the final place to be modified.
131 DBI::DBD::SqlEngine::db
133 Contains the methods which are called through DBI database handles
134 ($dbh). e.g.,
135 $sth = $dbh->prepare ("select * from foo");
137 # returns the f_encoding setting for table foo
138 $dbh->csv_get_meta ("foo", "f_encoding");
139 DBI::DBD::SqlEngine provides the typical methods required here.
141 Developers who write DBI drivers based on DBI::DBD::SqlEngine need
142 to override the methods "set_versions" and "init_valid_attributes".
143 DBI::DBD::SqlEngine::TieMeta;
145 Provides the tie-magic for "$dbh->{$drv_pfx . "_meta"}". Routes
146 "STORE" through "$drv->set_sql_engine_meta()" and "FETCH" through
147 "$drv->get_sql_engine_meta()". "DELETE" is not supported, you have
148 to execute a "DROP TABLE" statement, where applicable.
149 DBI::DBD::SqlEngine::TieTables;
151 Provides the tie-magic for tables in "$dbh->{$drv_pfx . "_meta"}".
152 Routes "STORE" though "$tblClass->set_table_meta_attr()" and
153 "FETCH" though "$tblClass->get_table_meta_attr()". "DELETE" removes
154 an attribute from the meta object retrieved by
155 "$tblClass->get_table_meta()".
156 DBI::DBD::SqlEngine::st
158 Contains the methods to deal with prepared statement handles. e.g.,
159 $sth->execute () or die $sth->errstr;
161 DBI::DBD::SqlEngine::TableSource;
163 Base class for 3rd party table sources:
164 $dbh->{sql_table_source} = "DBD::Foo::TableSource";
166 DBI::DBD::SqlEngine::DataSource;
168 Base class for 3rd party data sources:
169 $dbh->{sql_data_source} = "DBD::Foo::DataSource";
171 DBI::DBD::SqlEngine::Statement;
173 Base class for derived drivers statement engine. Implements
174 "open_table".
175 DBI::DBD::SqlEngine::Table;
177 Contains tailoring between SQL engine's requirements and
178 "DBI::DBD::SqlEngine" magic for finding the right tables and
179 storage. Builds bridges between "sql_meta" handling of
180 "DBI::DBD::SqlEngine::db", table initialization for SQL engines and
181 meta object's attribute management for derived drivers.
182 DBI::DBD::SqlEngine
184 This is the main package containing the routines to initialize
185 DBI::DBD::SqlEngine based DBI drivers. Primarily the
186 "DBI::DBD::SqlEngine::driver" method is invoked, either directly from
187 DBI when the driver is initialized or from the derived class.
188 package DBD::DBM;
190 use base qw( DBI::DBD::SqlEngine );
192 sub driver
194 {
195 my ( $class, $attr ) = @_;
196 ...
197 my $drh = $class->SUPER::driver( $attr );
198 ...
199 return $drh;
200 }
201 It is not necessary to implement your own driver method as long as
203 additional initialization (e.g. installing more private driver methods)
204 is not required. You do not need to call "setup_driver" as
205 DBI::DBD::SqlEngine takes care of it.
206 DBI::DBD::SqlEngine::dr
208 The driver package contains the methods DBI calls indirectly via the
209 DBI interface (see "DBI Class Methods" in DBI).
210 DBI::DBD::SqlEngine based DBI drivers usually do not need to implement
212 anything here, it is enough to do the basic initialization:
213 package DBD:XXX::dr;
215 @DBD::XXX::dr::ISA = qw (DBI::DBD::SqlEngine::dr);
217 $DBD::XXX::dr::imp_data_size = 0;
218 $DBD::XXX::dr::data_sources_attr = undef;
219 $DBD::XXX::ATTRIBUTION = "DBD::XXX $DBD::XXX::VERSION by Hans Mustermann";
220 Methods provided by "DBI::DBD::SqlEngine::dr":
222 connect
224 Supervises the driver bootstrap when calling
225 DBI->connect( "dbi:Foo", , , { ... } );
227 First it instantiates a new driver using "DBI::_new_dbh". After
229 that, initial bootstrap of the newly instantiated driver is done by
230 $dbh->func( 0, "init_default_attributes" );
232 The first argument (0) signals that this is the very first call to
234 "init_default_attributes". Modern drivers understand that and do
235 early stage setup here after calling
236 package DBD::Foo::db;
238 our @DBD::Foo::db::ISA = qw(DBI::DBD::SqlEngine::db);
239 sub init_default_attributes
241 {
242 my ($dbh, $phase) = @_;
243 $dbh->SUPER::init_default_attributes($phase);
244 ...; # own setup code, maybe separated by phases
245 }
246 When the $phase argument is passed down until
248 "DBI::DBD::SqlEngine::db::init_default_attributes", connect()
249 recognizes a modern driver and initializes the attributes from DSN
250 and $attr arguments passed via "DBI->connect( $dsn, $user, $pass,
251 \%attr )".
252 At the end of the attribute initialization after phase 0, connect()
254 invoked "init_default_attributes" again for phase 1:
255 $dbh->func( 1, "init_default_attributes" );
257 data_sources
259 Returns a list of DSN's using the "data_sources" method of the
260 class specified in "$dbh->{sql_table_source}" or via "\%attr":
261 @ary = DBI->data_sources($driver);
263 @ary = DBI->data_sources($driver, \%attr);
264 disconnect_all
266 "DBI::DBD::SqlEngine" doesn't have an overall driver cache, so
267 nothing happens here at all.
268 DBI::DBD::SqlEngine::db
270 This package defines the database methods, which are called via the DBI
271 database handle $dbh.
272 Methods provided by "DBI::DBD::SqlEngine::db":
274 ping
276 Simply returns the content of the "Active" attribute. Override when
277 your driver needs more complicated actions here.
278 prepare
280 Prepares a new SQL statement to execute. Returns a statement
281 handle, $sth - instance of the DBD:XXX::st. It is neither required
282 nor recommended to override this method.
283 validate_FETCH_attr
285 Called by "FETCH" to allow inherited drivers do their own attribute
286 name validation. Calling convention is similar to "FETCH" and the
287 return value is the approved attribute name.
288 return $validated_attribute_name;
290 In case of validation fails (e.g. accessing private attribute or
292 similar), "validate_FETCH_attr" is permitted to throw an exception.
293 FETCH
295 Fetches an attribute of a DBI database object. Private handle
296 attributes must have a prefix (this is mandatory). If a requested
297 attribute is detected as a private attribute without a valid
298 prefix, the driver prefix (written as $drv_prefix) is added.
299 The driver prefix is extracted from the attribute name and verified
301 against "$dbh->{ $drv_prefix . "valid_attrs" }" (when it exists).
302 If the requested attribute value is not listed as a valid
303 attribute, this method croaks. If the attribute is valid and
304 readonly (listed in "$dbh->{ $drv_prefix . "readonly_attrs" }" when
305 it exists), a real copy of the attribute value is returned. So it's
306 not possible to modify "f_valid_attrs" from outside of
307 DBI::DBD::SqlEngine::db or a derived class.
308 validate_STORE_attr
310 Called by "STORE" to allow inherited drivers do their own attribute
311 name validation. Calling convention is similar to "STORE" and the
312 return value is the approved attribute name followed by the
313 approved new value.
314 return ($validated_attribute_name, $validated_attribute_value);
316 In case of validation fails (e.g. accessing private attribute or
318 similar), "validate_STORE_attr" is permitted to throw an exception
319 ("DBI::DBD::SqlEngine::db::validate_STORE_attr" throws an exception
320 when someone tries to assign value other than "SQL_IC_UPPER ..
321 SQL_IC_MIXED" to "$dbh->{sql_identifier_case}" or
322 "$dbh->{sql_quoted_identifier_case}").
323 STORE
325 Stores a database private attribute. Private handle attributes must
326 have a prefix (this is mandatory). If a requested attribute is
327 detected as a private attribute without a valid prefix, the driver
328 prefix (written as $drv_prefix) is added. If the database handle
329 has an attribute "${drv_prefix}_valid_attrs" - for attribute names
330 which are not listed in that hash, this method croaks. If the
331 database handle has an attribute "${drv_prefix}_readonly_attrs",
332 only attributes which are not listed there can be stored (once they
333 are initialized). Trying to overwrite such an immutable attribute
334 forces this method to croak.
335 An example of a valid attributes list can be found in
337 "DBI::DBD::SqlEngine::db::init_valid_attributes".
338 set_versions
340 This method sets the attributes "f_version", "sql_nano_version",
341 "sql_statement_version" and (if not prohibited by a restrictive
342 "${prefix}_valid_attrs") "${prefix}_version".
343 This method is called at the end of the "connect ()" phase.
345 When overriding this method, do not forget to invoke the superior
347 one.
348 init_valid_attributes
350 This method is called after the database handle is instantiated as
351 the first attribute initialization.
352 "DBI::DBD::SqlEngine::db::init_valid_attributes" initializes the
354 attributes "sql_valid_attrs" and "sql_readonly_attrs".
355 When overriding this method, do not forget to invoke the superior
357 one, preferably before doing anything else.
358 init_default_attributes
360 This method is called after the database handle is instantiated to
361 initialize the default attributes. It expects one argument: $phase.
362 If $phase is not given, "connect" of "DBI::DBD::SqlEngine::dr"
363 expects this is an old-fashioned driver which isn't capable of
364 multi-phased initialization.
365 "DBI::DBD::SqlEngine::db::init_default_attributes" initializes the
367 attributes "sql_identifier_case", "sql_quoted_identifier_case",
368 "sql_handler", "sql_init_order", "sql_meta", "sql_engine_version",
369 "sql_nano_version" and "sql_statement_version" when SQL::Statement
370 is available.
371 It sets "sql_init_order" to the given $phase.
373 When the derived implementor class provides the attribute to
375 validate attributes (e.g. "$dbh->{dbm_valid_attrs} = {...};") or
376 the attribute containing the immutable attributes (e.g.
377 "$dbh->{dbm_readonly_attrs} = {...};"), the attributes
378 "drv_valid_attrs", "drv_readonly_attrs" and "drv_version" are added
379 (when available) to the list of valid and immutable attributes
380 (where "drv_" is interpreted as the driver prefix).
381 get_versions
383 This method is called by the code injected into the instantiated
384 driver to provide the user callable driver method
385 "${prefix}versions" (e.g. "dbm_versions", "csv_versions", ...).
386 The DBI::DBD::SqlEngine implementation returns all version
388 information known by DBI::DBD::SqlEngine (e.g. DBI version, Perl
389 version, DBI::DBD::SqlEngine version and the SQL handler version).
390 "get_versions" takes the $dbh as the first argument and optionally
392 a second argument containing a table name. The second argument is
393 not evaluated in "DBI::DBD::SqlEngine::db::get_versions" itself -
394 but might be in the future.
395 If the derived implementor class provides a method named
397 "get_${drv_prefix}versions", this is invoked and the return value
398 of it is associated to the derived driver name:
399 if (my $dgv = $dbh->{ImplementorClass}->can ("get_" . $drv_prefix . "versions") {
401 (my $derived_driver = $dbh->{ImplementorClass}) =~ s/::db$//;
402 $versions{$derived_driver} = &$dgv ($dbh, $table);
403 }
404 Override it to add more version information about your module,
406 (e.g. some kind of parser version in case of DBD::CSV, ...), if
407 one line is not enough room to provide all relevant information.
408 sql_parser_object
410 Returns a SQL::Parser instance, when "sql_handler" is set to
411 "SQL::Statement". The parser instance is stored in
412 "sql_parser_object".
413 It is not recommended to override this method.
415 disconnect
417 Disconnects from a database. All local table information is
418 discarded and the "Active" attribute is set to 0.
419 type_info_all
421 Returns information about all the types supported by
422 DBI::DBD::SqlEngine.
423 table_info
425 Returns a statement handle which is prepared to deliver information
426 about all known tables.
427 list_tables
429 Returns a list of all known table names.
430 quote
432 Quotes a string for use in SQL statements.
433 commit
435 Warns about a useless call (if warnings enabled) and returns.
436 DBI::DBD::SqlEngine is typically a driver which commits every
437 action instantly when executed.
438 rollback
440 Warns about a useless call (if warnings enabled) and returns.
441 DBI::DBD::SqlEngine is typically a driver which commits every
442 action instantly when executed.
443 Attributes used by "DBI::DBD::SqlEngine::db":
445 This section describes attributes which are important to developers of
447 DBI Database Drivers derived from "DBI::DBD::SqlEngine".
448 sql_init_order
450 This attribute contains a hash with priorities as key and an array
451 containing the $dbh attributes to be initialized during
452 before/after other attributes.
453 "DBI::DBD::SqlEngine" initializes following attributes:
455 $dbh->{sql_init_order} = {
457 0 => [qw( Profile RaiseError PrintError AutoCommit )],
458 90 => [ "sql_meta", $dbh->{$drv_pfx_meta} ? $dbh->{$drv_pfx_meta} : () ]
459 }
460 The default priority of not listed attribute keys is 50. It is well
462 known that a lot of attributes needed to be set before some table
463 settings are initialized. For example, for DBD::DBM, when using
464 my $dbh = DBI->connect( "dbi:DBM:", undef, undef, {
466 f_dir => "/path/to/dbm/databases",
467 dbm_type => "BerkeleyDB",
468 dbm_mldbm => "JSON", # use MLDBM::Serializer::JSON
469 dbm_tables => {
470 quick => {
471 dbm_type => "GDBM_File",
472 dbm_MLDBM => "FreezeThaw"
473 }
474 }
475 });
476 This defines a known table "quick" which uses the GDBM_File backend
478 and FreezeThaw as serializer instead of the overall default
479 BerkeleyDB and JSON. But all files containing the table data have
480 to be searched in "$dbh->{f_dir}", which requires "$dbh->{f_dir}"
481 must be initialized before "$dbh->{sql_meta}->{quick}" is
482 initialized by "bootstrap_table_meta" method of
483 "DBI::DBD::SqlEngine::Table" to get
484 "$dbh->{sql_meta}->{quick}->{f_dir}" being initialized properly.
485 sql_init_phase
487 This attribute is only set during the initialization steps of the
488 DBI Database Driver. It contains the value of the currently run
489 initialization phase. Currently supported phases are phase 0 and
490 phase 1. This attribute is set in "init_default_attributes" and
491 removed in "init_done".
492 sql_engine_in_gofer
494 This value has a true value in case of this driver is operated via
495 DBD::Gofer. The impact of being operated via Gofer is a read-only
496 driver (not read-only databases!), so you cannot modify any
497 attributes later - neither any table settings. But you won't get an
498 error in cases you modify table attributes, so please carefully
499 watch "sql_engine_in_gofer".
500 sql_table_source
502 Names a class which is responsible for delivering data sources and
503 available tables (Database Driver related). data sources here
504 refers to "data_sources" in DBI, not "sql_data_source".
505 See "DBI::DBD::SqlEngine::TableSource" for details.
507 sql_data_source
509 Name a class which is responsible for handling table resources open
510 and completing table names requested via SQL statements.
511 See "DBI::DBD::SqlEngine::DataSource" for details.
513 sql_dialect
515 Controls the dialect understood by SQL::Parser. Possible values
516 (delivery state of SQL::Statement):
517 * ANSI
519 * CSV
520 * AnyData
521 Defaults to "CSV". Because an SQL::Parser is instantiated only
523 once and SQL::Parser doesn't allow one to modify the dialect once
524 instantiated, it's strongly recommended to set this flag before any
525 statement is executed (best place is connect attribute hash).
526 DBI::DBD::SqlEngine::st
528 Contains the methods to deal with prepared statement handles:
529 bind_param
531 Common routine to bind placeholders to a statement for execution.
532 It is dangerous to override this method without detailed knowledge
533 about the DBI::DBD::SqlEngine internal storage structure.
534 execute
536 Executes a previously prepared statement (with placeholders, if
537 any).
538 finish
540 Finishes a statement handle, discards all buffered results. The
541 prepared statement is not discarded so the statement can be
542 executed again.
543 fetch
545 Fetches the next row from the result-set. This method may be
546 rewritten in a later version and if it's overridden in a derived
547 class, the derived implementation should not rely on the storage
548 details.
549 fetchrow_arrayref
551 Alias for "fetch".
552 FETCH
554 Fetches statement handle attributes. Supported attributes (for full
555 overview see "Statement Handle Attributes" in DBI) are "NAME",
556 "TYPE", "PRECISION" and "NULLABLE". Each column is returned as
557 "NULLABLE" which might be wrong depending on the derived backend
558 storage. If the statement handle has private attributes, they can
559 be fetched using this method, too. Note that statement attributes
560 are not associated with any table used in this statement.
561 This method usually requires extending in a derived implementation.
563 See DBD::CSV or DBD::DBM for some example.
564 STORE
566 Allows storing of statement private attributes. No special handling
567 is currently implemented here.
568 rows
570 Returns the number of rows affected by the last execute. This
571 method might return "undef".
572 DBI::DBD::SqlEngine::TableSource
574 Provides data sources and table information on database driver and
575 database handle level.
576 package DBI::DBD::SqlEngine::TableSource;
578 sub data_sources ($;$)
580 {
581 my ( $class, $drh, $attrs ) = @_;
582 ...
583 }
584 sub avail_tables
586 {
587 my ( $class, $drh ) = @_;
588 ...
589 }
590 The "data_sources" method is called when the user invokes any of the
592 following:
593 @ary = DBI->data_sources($driver);
595 @ary = DBI->data_sources($driver, \%attr);
596 @ary = $dbh->data_sources();
598 @ary = $dbh->data_sources(\%attr);
599 The "avail_tables" method is called when the user invokes any of the
601 following:
602 @names = $dbh->tables( $catalog, $schema, $table, $type );
604 $sth = $dbh->table_info( $catalog, $schema, $table, $type );
606 $sth = $dbh->table_info( $catalog, $schema, $table, $type, \%attr );
607 $dbh->func( "list_tables" );
609 Every time where an "\%attr" argument can be specified, this "\%attr"
611 object's "sql_table_source" attribute is preferred over the $dbh
612 attribute or the driver default.
613 DBI::DBD::SqlEngine::DataSource
615 Provides base functionality for dealing with tables. It is primarily
616 designed for allowing transparent access to files on disk or already
617 opened (file-)streams (e.g. for DBD::CSV).
618 Derived classes shall be restricted to similar functionality, too (e.g.
620 opening streams from an archive, transparently compress/uncompress log
621 files before parsing them,
622 package DBI::DBD::SqlEngine::DataSource;
624 sub complete_table_name ($$;$)
626 {
627 my ( $self, $meta, $table, $respect_case ) = @_;
628 ...
629 }
630 The method "complete_table_name" is called when first setting up the
632 meta information for a table:
633 "SELECT user.id, user.name, user.shell FROM user WHERE ..."
635 results in opening the table "user". First step of the table open
637 process is completing the name. Let's imagine you're having a DBD::CSV
638 handle with following settings:
639 $dbh->{sql_identifier_case} = SQL_IC_LOWER;
641 $dbh->{f_ext} = '.lst';
642 $dbh->{f_dir} = '/data/web/adrmgr';
643 Those settings will result in looking for files matching
645 "[Uu][Ss][Ee][Rr](\.lst)?$" in "/data/web/adrmgr/". The scanning of the
646 directory "/data/web/adrmgr/" and the pattern match check will be done
647 in "DBD::File::DataSource::File" by the "complete_table_name" method.
648 If you intend to provide other sources of data streams than files, in
650 addition to provide an appropriate "complete_table_name" method, a
651 method to open the resource is required:
652 package DBI::DBD::SqlEngine::DataSource;
654 sub open_data ($)
656 {
657 my ( $self, $meta, $attrs, $flags ) = @_;
658 ...
659 }
660 After the method "open_data" has been run successfully, the table's
662 meta information are in a state which allows the table's data accessor
663 methods will be able to fetch/store row information. Implementation
664 details heavily depends on the table implementation, whereby the most
665 famous is surely DBD::File::Table.
666 DBI::DBD::SqlEngine::Statement
668 Derives from DBI::SQL::Nano::Statement for unified naming when deriving
669 new drivers. No additional feature is provided from here.
670 DBI::DBD::SqlEngine::Table
672 Derives from DBI::SQL::Nano::Table for unified naming when deriving new
673 drivers.
674 You should consult the documentation of "SQL::Eval::Table" (see
676 SQL::Eval) to get more information about the abstract methods of the
677 table's base class you have to override and a description of the table
678 meta information expected by the SQL engines.
679 bootstrap_table_meta
681 Initializes a table meta structure. Can be safely overridden in a
682 derived class, as long as the "SUPER" method is called at the end
683 of the overridden method.
684 It copies the following attributes from the database into the table
686 meta data "$dbh->{ReadOnly}" into "$meta->{readonly}",
687 "sql_identifier_case" and "sql_data_source" and makes them sticky
688 to the table.
689 This method should be called before you attempt to map between file
691 name and table name to ensure the correct directory, extension etc.
692 are used.
693 init_table_meta
695 Initializes more attributes of the table meta data - usually more
696 expensive ones (e.g. those which require class instantiations) -
697 when the file name and the table name could mapped.
698 get_table_meta
700 Returns the table meta data. If there are none for the required
701 table, a new one is initialized. When after bootstrapping a new
702 table_meta and completing the table name a mapping can be
703 established between an existing table_meta and the new bootstrapped
704 one, the already existing is used and a mapping shortcut between
705 the recent used table name and the already known table name is hold
706 in "$dbh->{sql_meta_map}". When it fails, nothing is returned. On
707 success, the name of the table and the meta data structure is
708 returned.
709 get_table_meta_attr
711 Returns a single attribute from the table meta data. If the
712 attribute name appears in %compat_map, the attribute name is
713 updated from there.
714 set_table_meta_attr
716 Sets a single attribute in the table meta data. If the attribute
717 name appears in %compat_map, the attribute name is updated from
718 there.
719 table_meta_attr_changed
721 Called when an attribute of the meta data is modified.
722 If the modified attribute requires to reset a calculated attribute,
724 the calculated attribute is reset (deleted from meta data
725 structure) and the initialized flag is removed, too. The decision
726 is made based on %register_reset_on_modify.
727 register_reset_on_modify
729 Allows "set_table_meta_attr" to reset meta attributes when special
730 attributes are modified. For DBD::File, modifying one of "f_file",
731 "f_dir", "f_ext" or "f_lockfile" will reset "f_fqfn". DBD::DBM
732 extends the list for "dbm_type" and "dbm_mldbm" to reset the value
733 of "dbm_tietype".
734 If your DBD has calculated values in the meta data area, then call
736 "register_reset_on_modify":
737 my %reset_on_modify = ( "xxx_foo" => "xxx_bar" );
739 __PACKAGE__->register_reset_on_modify( \%reset_on_modify );
740 register_compat_map
742 Allows "get_table_meta_attr" and "set_table_meta_attr" to update
743 the attribute name to the current favored one:
744 # from DBD::DBM
746 my %compat_map = ( "dbm_ext" => "f_ext" );
747 __PACKAGE__->register_compat_map( \%compat_map );
748 open_data
750 Called to open the table's data storage. This is silently forwarded
751 to "$meta->{sql_data_source}->open_data()".
752 After this is done, a derived class might add more steps in an
754 overridden "open_file" method.
755 new Instantiates the table. This is done in 3 steps:
757 1. get the table meta data
759 2. open the data file
760 3. bless the table data structure using inherited constructor new
761 It is not recommended to override the constructor of the table
763 class. Find a reasonable place to add you extensions in one of the
764 above four methods.
765
767 The module DBI::DBD::SqlEngine is currently maintained by
768 H.Merijn Brand < h.m.brand at xs4all.nl > and Jens Rehsack < rehsack
770 at googlemail.com >
771
773 Copyright (C) 2010 by H.Merijn Brand & Jens Rehsack
774 All rights reserved.
776 You may freely distribute and/or modify this module under the terms of
778 either the GNU General Public License (GPL) or the Artistic License, as
779 specified in the Perl README file.
780perl v5.38.0 2023-07-20DBI::DBD::SqlEngine::Developers(3)