1DBI::DBD::SqlEngine::DeUvseelropCeornst(r3i)buted Perl DDoBcIu:m:eDnBtDa:t:iSoqnlEngine::Developers(3)
2
3
4

NAME

6       DBI::DBD::SqlEngine::Developers - Developers documentation for
7       DBI::DBD::SqlEngine
8

SYNOPSIS

10           package DBD::myDriver;
11
12           use base qw(DBI::DBD::SqlEngine);
13
14           sub driver
15           {
16               ...
17               my $drh = $proto->SUPER::driver($attr);
18               ...
19               return $drh->{class};
20           }
21
22           sub CLONE { ... }
23
24           package DBD::myDriver::dr;
25
26           @ISA = qw(DBI::DBD::SqlEngine::dr);
27
28           sub data_sources { ... }
29           ...
30
31           package DBD::myDriver::db;
32
33           @ISA = qw(DBI::DBD::SqlEngine::db);
34
35           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
43           package DBD::myDriver::st;
44
45           @ISA = qw(DBI::DBD::SqlEngine::st);
46
47           sub FETCH { ... }
48           sub STORE { ... }
49
50           package DBD::myDriver::Statement;
51
52           @ISA = qw(DBI::DBD::SqlEngine::Statement);
53
54           sub open_table { ... }
55
56           package DBD::myDriver::Table;
57
58           @ISA = qw(DBI::DBD::SqlEngine::Table);
59
60           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
71           sub bootstrap_table_meta { ... }
72           sub init_table_meta { ... }
73           sub table_meta_attr_changed { ... }
74           sub open_data { ... }
75
76           sub new { ... }
77
78           sub fetch_row { ... }
79           sub push_row { ... }
80           sub push_names { ... }
81           sub seek { ... }
82           sub truncate { ... }
83           sub drop { ... }
84
85           # 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

DESCRIPTION

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

CLASSES

105       Each DBI driver must provide a package global "driver" method and three
106       DBI related classes:
107
108       DBI::DBD::SqlEngine::dr
109           Driver package, contains the methods DBI calls indirectly via DBI
110           interface:
111
112             DBI->connect ('DBI:DBM:', undef, undef, {})
113
114             # invokes
115             package DBD::DBM::dr;
116             @DBD::DBM::dr::ISA = qw(DBI::DBD::SqlEngine::dr);
117
118             sub connect ($$;$$$)
119             {
120                 ...
121             }
122
123           Similar for "data_sources ()" and "disconnect_all()".
124
125           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
130           method might be the final place to be modified.
131
132       DBI::DBD::SqlEngine::db
133           Contains the methods which are called through DBI database handles
134           ($dbh). e.g.,
135
136             $sth = $dbh->prepare ("select * from foo");
137             # returns the f_encoding setting for table foo
138             $dbh->csv_get_meta ("foo", "f_encoding");
139
140           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
144       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
150       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
157       DBI::DBD::SqlEngine::st
158           Contains the methods to deal with prepared statement handles. e.g.,
159
160             $sth->execute () or die $sth->errstr;
161
162       DBI::DBD::SqlEngine::TableSource;
163           Base class for 3rd party table sources:
164
165             $dbh->{sql_table_source} = "DBD::Foo::TableSource";
166
167       DBI::DBD::SqlEngine::DataSource;
168           Base class for 3rd party data sources:
169
170             $dbh->{sql_data_source} = "DBD::Foo::DataSource";
171
172       DBI::DBD::SqlEngine::Statement;
173           Base class for derived drivers statement engine. Implements
174           "open_table".
175
176       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
183   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
189         package DBD::DBM;
190
191         use base qw( DBI::DBD::SqlEngine );
192
193         sub driver
194         {
195             my ( $class, $attr ) = @_;
196             ...
197             my $drh = $class->SUPER::driver( $attr );
198             ...
199             return $drh;
200         }
201
202       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
207   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
211       DBI::DBD::SqlEngine based DBI drivers usually do not need to implement
212       anything here, it is enough to do the basic initialization:
213
214         package DBD:XXX::dr;
215
216         @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
221       Methods provided by "DBI::DBD::SqlEngine::dr":
222
223       connect
224           Supervises the driver bootstrap when calling
225
226             DBI->connect( "dbi:Foo", , , { ... } );
227
228           First it instantiates a new driver using "DBI::_new_dbh". After
229           that, initial bootstrap of the newly instantiated driver is done by
230
231             $dbh->func( 0, "init_default_attributes" );
232
233           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
237             package DBD::Foo::db;
238             our @DBD::Foo::db::ISA = qw(DBI::DBD::SqlEngine::db);
239
240             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
247           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
253           At the end of the attribute initialization after phase 0,
254           "connect()" invoked "init_default_attributes" again for phase 1:
255
256             $dbh->func( 1, "init_default_attributes" );
257
258       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
262             @ary = DBI->data_sources($driver);
263             @ary = DBI->data_sources($driver, \%attr);
264
265       disconnect_all
266           "DBI::DBD::SqlEngine" doesn't have an overall driver cache, so
267           nothing happens here at all.
268
269   DBI::DBD::SqlEngine::db
270       This package defines the database methods, which are called via the DBI
271       database handle $dbh.
272
273       Methods provided by "DBI::DBD::SqlEngine::db":
274
275       ping
276           Simply returns the content of the "Active" attribute. Override when
277           your driver needs more complicated actions here.
278
279       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
284       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
289               return $validated_attribute_name;
290
291           In case of validation fails (e.g. accessing private attribute or
292           similar), "validate_FETCH_attr" is permitted to throw an exception.
293
294       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
300           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
309       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
315               return ($validated_attribute_name, $validated_attribute_value);
316
317           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
324       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
336           An example of a valid attributes list can be found in
337           "DBI::DBD::SqlEngine::db::init_valid_attributes".
338
339       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
344           This method is called at the end of the "connect ()" phase.
345
346           When overriding this method, do not forget to invoke the superior
347           one.
348
349       init_valid_attributes
350           This method is called after the database handle is instantiated as
351           the first attribute initialization.
352
353           "DBI::DBD::SqlEngine::db::init_valid_attributes" initializes the
354           attributes "sql_valid_attrs" and "sql_readonly_attrs".
355
356           When overriding this method, do not forget to invoke the superior
357           one, preferably before doing anything else.
358
359       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
366           "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
372           It sets "sql_init_order" to the given $phase.
373
374           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
382       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
387           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
391           "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
396           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
400               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
405           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
409       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
414           It is not recommended to override this method.
415
416       disconnect
417           Disconnects from a database. All local table information is
418           discarded and the "Active" attribute is set to 0.
419
420       type_info_all
421           Returns information about all the types supported by
422           DBI::DBD::SqlEngine.
423
424       table_info
425           Returns a statement handle which is prepared to deliver information
426           about all known tables.
427
428       list_tables
429           Returns a list of all known table names.
430
431       quote
432           Quotes a string for use in SQL statements.
433
434       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
439       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
444       Attributes used by "DBI::DBD::SqlEngine::db":
445
446       This section describes attributes which are important to developers of
447       DBI Database Drivers derived from "DBI::DBD::SqlEngine".
448
449       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
454           "DBI::DBD::SqlEngine" initializes following attributes:
455
456             $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
461           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
465             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
477           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
486       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
493       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
501       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
506           See "DBI::DBD::SqlEngine::TableSource" for details.
507
508       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
512           See "DBI::DBD::SqlEngine::DataSource" for details.
513
514       sql_dialect
515           Controls the dialect understood by SQL::Parser. Possible values
516           (delivery state of SQL::Statement):
517
518             * ANSI
519             * CSV
520             * AnyData
521
522           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
527   DBI::DBD::SqlEngine::st
528       Contains the methods to deal with prepared statement handles:
529
530       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
535       execute
536           Executes a previously prepared statement (with placeholders, if
537           any).
538
539       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
544       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
550       fetchrow_arrayref
551           Alias for "fetch".
552
553       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
562           This method usually requires extending in a derived implementation.
563           See DBD::CSV or DBD::DBM for some example.
564
565       STORE
566           Allows storing of statement private attributes. No special handling
567           is currently implemented here.
568
569       rows
570           Returns the number of rows affected by the last execute. This
571           method might return "undef".
572
573   DBI::DBD::SqlEngine::TableSource
574       Provides data sources and table information on database driver and
575       database handle level.
576
577         package DBI::DBD::SqlEngine::TableSource;
578
579         sub data_sources ($;$)
580         {
581           my ( $class, $drh, $attrs ) = @_;
582           ...
583         }
584
585         sub avail_tables
586         {
587           my ( $class, $drh ) = @_;
588           ...
589         }
590
591       The "data_sources" method is called when the user invokes any of the
592       following:
593
594         @ary = DBI->data_sources($driver);
595         @ary = DBI->data_sources($driver, \%attr);
596
597         @ary = $dbh->data_sources();
598         @ary = $dbh->data_sources(\%attr);
599
600       The "avail_tables" method is called when the user invokes any of the
601       following:
602
603         @names = $dbh->tables( $catalog, $schema, $table, $type );
604
605         $sth = $dbh->table_info( $catalog, $schema, $table, $type );
606         $sth = $dbh->table_info( $catalog, $schema, $table, $type, \%attr );
607
608         $dbh->func( "list_tables" );
609
610       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
614   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
619       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
623         package DBI::DBD::SqlEngine::DataSource;
624
625         sub complete_table_name ($$;$)
626         {
627           my ( $self, $meta, $table, $respect_case ) = @_;
628           ...
629         }
630
631       The method "complete_table_name" is called when first setting up the
632       meta information for a table:
633
634         "SELECT user.id, user.name, user.shell FROM user WHERE ..."
635
636       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
640         $dbh->{sql_identifier_case} = SQL_IC_LOWER;
641         $dbh->{f_ext} = '.lst';
642         $dbh->{f_dir} = '/data/web/adrmgr';
643
644       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
649       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
653         package DBI::DBD::SqlEngine::DataSource;
654
655         sub open_data ($)
656         {
657           my ( $self, $meta, $attrs, $flags ) = @_;
658           ...
659         }
660
661       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
667   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
671   DBI::DBD::SqlEngine::Table
672       Derives from DBI::SQL::Nano::Table for unified naming when deriving new
673       drivers.
674
675       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
680       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
685           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
690           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
694       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
699       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
710       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
715       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
720       table_meta_attr_changed
721           Called when an attribute of the meta data is modified.
722
723           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
728       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
735           If your DBD has calculated values in the meta data area, then call
736           "register_reset_on_modify":
737
738               my %reset_on_modify = ( "xxx_foo" => "xxx_bar" );
739               __PACKAGE__->register_reset_on_modify( \%reset_on_modify );
740
741       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
745               # from DBD::DBM
746               my %compat_map = ( "dbm_ext" => "f_ext" );
747               __PACKAGE__->register_compat_map( \%compat_map );
748
749       open_data
750           Called to open the table's data storage. This is silently forwarded
751           to "$meta->{sql_data_source}->open_data()".
752
753           After this is done, a derived class might add more steps in an
754           overridden "open_file" method.
755
756       new Instantiates the table. This is done in 3 steps:
757
758            1. get the table meta data
759            2. open the data file
760            3. bless the table data structure using inherited constructor new
761
762           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

AUTHOR

767       The module DBI::DBD::SqlEngine is currently maintained by
768
769       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
775       All rights reserved.
776
777       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.
780
781
782
783perl v5.34.0                      2021-07-22DBI::DBD::SqlEngine::Developers(3)
Impressum