1DBD::File::Developers(3U)ser Contributed Perl DocumentatiDoBnD::File::Developers(3)
2
3
4

NAME

6       DBD::File::Developers - Developers documentation for DBD::File
7

SYNOPSIS

9           package DBD::myDriver;
10
11           use base qw( DBD::File );
12
13           sub driver
14           {
15               ...
16               my $drh = $proto->SUPER::driver ($attr);
17               ...
18               return $drh->{class};
19               }
20
21           sub CLONE { ... }
22
23           package DBD::myDriver::dr;
24
25           @ISA = qw( DBD::File::dr );
26
27           sub data_sources { ... }
28           ...
29
30           package DBD::myDriver::db;
31
32           @ISA = qw( DBD::File::db );
33
34           sub init_valid_attributes { ... }
35           sub init_default_attributes { ... }
36           sub set_versions { ... }
37           sub validate_STORE_attr { my ($dbh, $attrib, $value) = @_; ... }
38           sub validate_FETCH_attr { my ($dbh, $attrib) = @_; ... }
39           sub get_myd_versions { ... }
40
41           package DBD::myDriver::st;
42
43           @ISA = qw( DBD::File::st );
44
45           sub FETCH { ... }
46           sub STORE { ... }
47
48           package DBD::myDriver::Statement;
49
50           @ISA = qw( DBD::File::Statement );
51
52           package DBD::myDriver::Table;
53
54           @ISA = qw( DBD::File::Table );
55
56           my %reset_on_modify = (
57               myd_abc => "myd_foo",
58               myd_mno => "myd_bar",
59               );
60           __PACKAGE__->register_reset_on_modify (\%reset_on_modify);
61           my %compat_map = (
62               abc => 'foo_abc',
63               xyz => 'foo_xyz',
64               );
65           __PACKAGE__->register_compat_map (\%compat_map);
66
67           sub bootstrap_table_meta { ... }
68           sub init_table_meta { ... }
69           sub table_meta_attr_changed { ... }
70           sub open_data { ... }
71
72           sub fetch_row { ... }
73           sub push_row { ... }
74           sub push_names { ... }
75
76           # optimize the SQL engine by add one or more of
77           sub update_current_row { ... }
78           # or
79           sub update_specific_row { ... }
80           # or
81           sub update_one_row { ... }
82           # or
83           sub insert_new_row { ... }
84           # or
85           sub delete_current_row { ... }
86           # or
87           sub delete_one_row { ... }
88

DESCRIPTION

90       This document describes how DBD developers can write DBD::File based
91       DBI drivers. It supplements DBI::DBD and
92       DBI::DBD::SqlEngine::Developers, which you should read first.
93

CLASSES

95       Each DBI driver must provide a package global "driver" method and three
96       DBI related classes:
97
98       DBD::File::dr
99           Driver package, contains the methods DBI calls indirectly via DBI
100           interface:
101
102             DBI->connect ('DBI:DBM:', undef, undef, {})
103
104             # invokes
105             package DBD::DBM::dr;
106             @DBD::DBM::dr::ISA = qw( DBD::File::dr );
107
108             sub connect ($$;$$$)
109             {
110                 ...
111                 }
112
113           Similar for "data_sources" and "disconnect_all".
114
115           Pure Perl DBI drivers derived from DBD::File do not usually need to
116           override any of the methods provided through the DBD::XXX::dr
117           package however if you need additional initialization in the
118           connect method you may need to.
119
120       DBD::File::db
121           Contains the methods which are called through DBI database handles
122           ($dbh). e.g.,
123
124             $sth = $dbh->prepare ("select * from foo");
125             # returns the f_encoding setting for table foo
126             $dbh->csv_get_meta ("foo", "f_encoding");
127
128           DBD::File provides the typical methods required here. Developers
129           who write DBI drivers based on DBD::File need to override the
130           methods "set_versions" and "init_valid_attributes".
131
132       DBD::File::st
133           Contains the methods to deal with prepared statement handles. e.g.,
134
135             $sth->execute () or die $sth->errstr;
136
137   DBD::File
138       This is the main package containing the routines to initialize
139       DBD::File based DBI drivers. Primarily the "DBD::File::driver" method
140       is invoked, either directly from DBI when the driver is initialized or
141       from the derived class.
142
143         package DBD::DBM;
144
145         use base qw( DBD::File );
146
147         sub driver
148         {
149             my ($class, $attr) = @_;
150             ...
151             my $drh = $class->SUPER::driver ($attr);
152             ...
153             return $drh;
154             }
155
156       It is not necessary to implement your own driver method as long as
157       additional initialization (e.g. installing more private driver methods)
158       is not required.  You do not need to call "setup_driver" as DBD::File
159       takes care of it.
160
161   DBD::File::dr
162       The driver package contains the methods DBI calls indirectly via the
163       DBI interface (see "DBI Class Methods" in DBI).
164
165       DBD::File based DBI drivers usually do not need to implement anything
166       here, it is enough to do the basic initialization:
167
168         package DBD:XXX::dr;
169
170         @DBD::XXX::dr::ISA = qw (DBD::File::dr);
171         $DBD::XXX::dr::imp_data_size     = 0;
172         $DBD::XXX::dr::data_sources_attr = undef;
173         $DBD::XXX::ATTRIBUTION = "DBD::XXX $DBD::XXX::VERSION by Hans Mustermann";
174
175   DBD::File::db
176       This package defines the database methods, which are called via the DBI
177       database handle $dbh.
178
179       Methods provided by DBD::File:
180
181       ping
182           Simply returns the content of the "Active" attribute. Override when
183           your driver needs more complicated actions here.
184
185       prepare
186           Prepares a new SQL statement to execute. Returns a statement
187           handle, $sth - instance of the DBD:XXX::st. It is neither required
188           nor recommended to override this method.
189
190       FETCH
191           Fetches an attribute of a DBI database object. Private handle
192           attributes must have a prefix (this is mandatory). If a requested
193           attribute is detected as a private attribute without a valid
194           prefix, the driver prefix (written as $drv_prefix) is added.
195
196           The driver prefix is extracted from the attribute name and verified
197           against "$dbh->{$drv_prefix . "valid_attrs"}" (when it exists). If
198           the requested attribute value is not listed as a valid attribute,
199           this method croaks. If the attribute is valid and readonly (listed
200           in "$dbh->{ $drv_prefix . "readonly_attrs" }" when it exists), a
201           real copy of the attribute value is returned. So it's not possible
202           to modify "f_valid_attrs" from outside of DBD::File::db or a
203           derived class.
204
205       STORE
206           Stores a database private attribute. Private handle attributes must
207           have a prefix (this is mandatory). If a requested attribute is
208           detected as a private attribute without a valid prefix, the driver
209           prefix (written as $drv_prefix) is added. If the database handle
210           has an attribute "${drv_prefix}_valid_attrs" - for attribute names
211           which are not listed in that hash, this method croaks. If the
212           database handle has an attribute "${drv_prefix}_readonly_attrs",
213           only attributes which are not listed there can be stored (once they
214           are initialized). Trying to overwrite such an immutable attribute
215           forces this method to croak.
216
217           An example of a valid attributes list can be found in
218           "DBD::File::db::init_valid_attributes".
219
220       set_versions
221           This method sets the attribute "f_version" with the version of
222           DBD::File.
223
224           This method is called at the begin of the "connect ()" phase.
225
226           When overriding this method, do not forget to invoke the superior
227           one.
228
229       init_valid_attributes
230           This method is called after the database handle is instantiated as
231           the first attribute initialization.
232
233           "DBD::File::db::init_valid_attributes" initializes the attributes
234           "f_valid_attrs" and "f_readonly_attrs".
235
236           When overriding this method, do not forget to invoke the superior
237           one, preferably before doing anything else. Compatibility table
238           attribute access must be initialized here to allow DBD::File to
239           instantiate the map tie:
240
241               # for DBD::CSV
242               $dbh->{csv_meta} = "csv_tables";
243               # for DBD::DBM
244               $dbh->{dbm_meta} = "dbm_tables";
245               # for DBD::AnyData
246               $dbh->{ad_meta}  = "ad_tables";
247
248       init_default_attributes
249           This method is called after the database handle is instantiated to
250           initialize the default attributes.
251
252           "DBD::File::db::init_default_attributes" initializes the attributes
253           "f_dir", "f_meta", "f_meta_map", "f_version".
254
255           When the derived implementor class provides the attribute to
256           validate attributes (e.g. "$dbh->{dbm_valid_attrs} = {...};") or
257           the attribute containing the immutable attributes (e.g.
258           "$dbh->{dbm_readonly_attrs} = {...};"), the attributes
259           "drv_valid_attrs", "drv_readonly_attrs", "drv_version" and
260           "drv_meta" are added (when available) to the list of valid and
261           immutable attributes (where "drv_" is interpreted as the driver
262           prefix).
263
264           If "drv_meta" is set, an attribute with the name in "drv_meta" is
265           initialized providing restricted read/write access to the meta data
266           of the tables using "DBD::File::TieTables" in the first (table)
267           level and "DBD::File::TieMeta" for the meta attribute level.
268           "DBD::File::TieTables" uses "DBD::DRV::Table::get_table_meta" to
269           initialize the second level tied hash on FETCH/STORE. The
270           "DBD::File::TieMeta" class uses
271           "DBD::DRV::Table::get_table_meta_attr" to FETCH attribute values
272           and "DBD::DRV::Table::set_table_meta_attr" to STORE attribute
273           values. This allows it to map meta attributes for compatibility
274           reasons.
275
276       get_single_table_meta
277       get_file_meta
278           Retrieve an attribute from a table's meta information. The method
279           signature is "get_file_meta ($dbh, $table, $attr)". This method is
280           called by the injected db handle method "${drv_prefix}get_meta".
281
282           While get_file_meta allows $table or $attr to be a list of tables
283           or attributes to retrieve, get_single_table_meta allows only one
284           table name and only one attribute name. A table name of '.' (single
285           dot) is interpreted as the default table and this will retrieve the
286           appropriate attribute globally from the dbh. This has the same
287           restrictions as "$dbh->{$attrib}".
288
289           get_file_meta allows '+' and '*' as wildcards for table names and
290           $table being a regular expression matching against the table names
291           (evaluated without the default table). The table name '*' is all
292           currently known tables, including the default one. The table name
293           '+' is all table names which conform to ANSI file name restrictions
294           (/^[_A-Za-z0-9]+$/).
295
296           The table meta information is retrieved using the get_table_meta
297           and get_table_meta_attr methods of the table class of the
298           implementation.
299
300       set_single_table_meta
301       set_file_meta
302           Sets an attribute in a table's meta information. The method
303           signature is "set_file_meta ($dbh, $table, $attr, $value)". This
304           method is called by the injected db handle method
305           "${drv_prefix}set_meta".
306
307           While set_file_meta allows $table to be a list of tables and $attr
308           to be a hash of several attributes to set, set_single_table_meta
309           allows only one table name and only one attribute name/value pair.
310
311           The wildcard characters for the table name are the same as for
312           get_file_meta.
313
314           The table meta information is updated using the get_table_meta and
315           set_table_meta_attr methods of the table class of the
316           implementation.
317
318       clear_file_meta
319           Clears all meta information cached about a table. The method
320           signature is "clear_file_meta ($dbh, $table)". This method is
321           called by the injected db handle method "${drv_prefix}clear_meta".
322
323   DBD::File::st
324       Contains the methods to deal with prepared statement handles:
325
326       FETCH
327           Fetches statement handle attributes. Supported attributes (for full
328           overview see "Statement Handle Attributes" in DBI) are "NAME",
329           "TYPE", "PRECISION" and "NULLABLE" in case that SQL::Statement is
330           used as SQL execution engine and a statement is successful
331           prepared.  When SQL::Statement has additional information about a
332           table, those information are returned. Otherwise, the same defaults
333           as in DBI::DBD::SqlEngine are used.
334
335           This method usually requires extending in a derived implementation.
336           See DBD::CSV or DBD::DBM for some example.
337
338   DBD::File::TableSource::FileSystem
339       Provides data sources and table information on database driver and
340       database handle level.
341
342         package DBD::File::TableSource::FileSystem;
343
344         sub data_sources ($;$)
345         {
346             my ($class, $drh, $attrs) = @_;
347             ...
348             }
349
350         sub avail_tables
351         {
352             my ($class, $drh) = @_;
353             ...
354             }
355
356       The "data_sources" method is called when the user invokes any of the
357       following:
358
359         @ary = DBI->data_sources ($driver);
360         @ary = DBI->data_sources ($driver, \%attr);
361
362         @ary = $dbh->data_sources ();
363         @ary = $dbh->data_sources (\%attr);
364
365       The "avail_tables" method is called when the user invokes any of the
366       following:
367
368         @names = $dbh->tables ($catalog, $schema, $table, $type);
369
370         $sth   = $dbh->table_info ($catalog, $schema, $table, $type);
371         $sth   = $dbh->table_info ($catalog, $schema, $table, $type, \%attr);
372
373         $dbh->func ("list_tables");
374
375       Every time where an "\%attr" argument can be specified, this "\%attr"
376       object's "sql_table_source" attribute is preferred over the $dbh
377       attribute or the driver default.
378
379   DBD::File::DataSource::Stream
380         package DBD::File::DataSource::Stream;
381
382         @DBD::File::DataSource::Stream::ISA = 'DBI::DBD::SqlEngine::DataSource';
383
384         sub complete_table_name
385         {
386             my ($self, $meta, $file, $respect_case) = @_;
387             ...
388             }
389
390       Clears all meta attributes identifying a file: "f_fqfn", "f_fqbn" and
391       "f_fqln". The table name is set according to $respect_case and
392       "$meta->{sql_identifier_case}" (SQL_IC_LOWER, SQL_IC_UPPER).
393
394         package DBD::File::DataSource::Stream;
395
396         sub apply_encoding
397         {
398             my ($self, $meta, $fn) = @_;
399             ...
400             }
401
402       Applies the encoding from meta information ("$meta->{f_encoding}") to
403       the file handled opened in "open_data".
404
405         package DBD::File::DataSource::Stream;
406
407         sub open_data
408         {
409             my ($self, $meta, $attrs, $flags) = @_;
410             ...
411             }
412
413       Opens ("dup (2)") the file handle provided in "$meta->{f_file}".
414
415         package DBD::File::DataSource::Stream;
416
417         sub can_flock { ... }
418
419       Returns whether "flock (2)" is available or not (avoids retesting in
420       subclasses).
421
422   DBD::File::DataSource::File
423         package DBD::File::DataSource::File;
424
425         sub complete_table_name ($$;$)
426         {
427             my ($self, $meta, $table, $respect_case) = @_;
428             ...
429             }
430
431       The method "complete_table_name" tries to map a filename to the
432       associated table name.  It is called with a partially filled meta
433       structure for the resulting table containing at least the following
434       attributes: "f_ext", "f_dir", "f_lockfile" and "sql_identifier_case".
435
436       If a file/table map can be found then this method sets the "f_fqfn",
437       "f_fqbn", "f_fqln" and "table_name" attributes in the meta structure.
438       If a map cannot be found the table name will be undef.
439
440         package DBD::File::DataSource::File;
441
442         sub open_data ($)
443         {
444             my ($self, $meta, $attrs, $flags) = @_;
445             ...
446             }
447
448       Depending on the attributes set in the table's meta data, the following
449       steps are performed. Unless "f_dontopen" is set to a true value,
450       "f_fqfn" must contain the full qualified file name for the table to
451       work on (file2table ensures this). The encoding in "f_encoding" is
452       applied if set and the file is opened. If "<f_fqln "> (full qualified
453       lock name) is set, this file is opened, too. Depending on the value in
454       "f_lock", the appropriate lock is set on the opened data file or lock
455       file.
456
457   DBD::File::Statement
458       Derives from DBI::SQL::Nano::Statement to provide following method:
459
460       open_table
461           Implements the open_table method required by SQL::Statement and
462           DBI::SQL::Nano. All the work for opening the file(s) belonging to
463           the table is handled and parametrized in DBD::File::Table. Unless
464           you intend to add anything to the following implementation, an
465           empty DBD::XXX::Statement package satisfies DBD::File.
466
467             sub open_table ($$$$$)
468             {
469                 my ($self, $data, $table, $createMode, $lockMode) = @_;
470
471                 my $class = ref $self;
472                 $class =~ s/::Statement/::Table/;
473
474                 my $flags = {
475                     createMode => $createMode,
476                     lockMode   => $lockMode,
477                     };
478                 $self->{command} eq "DROP" and $flags->{dropMode} = 1;
479
480                 return $class->new ($data, { table => $table }, $flags);
481                 } # open_table
482
483   DBD::File::Table
484       Derives from DBI::SQL::Nano::Table and provides physical file access
485       for the table data which are stored in the files.
486
487       bootstrap_table_meta
488           Initializes a table meta structure. Can be safely overridden in a
489           derived class, as long as the "SUPER" method is called at the end
490           of the overridden method.
491
492           It copies the following attributes from the database into the table
493           meta data "f_dir", "f_ext", "f_encoding", "f_lock", "f_schema" and
494           "f_lockfile" and makes them sticky to the table.
495
496           This method should be called before you attempt to map between file
497           name and table name to ensure the correct directory, extension etc.
498           are used.
499
500       init_table_meta
501           Initializes more attributes of the table meta data - usually more
502           expensive ones (e.g. those which require class instantiations) -
503           when the file name and the table name could mapped.
504
505       get_table_meta
506           Returns the table meta data. If there are none for the required
507           table, a new one is initialized. When it fails, nothing is
508           returned. On success, the name of the table and the meta data
509           structure is returned.
510
511       get_table_meta_attr
512           Returns a single attribute from the table meta data. If the
513           attribute name appears in %compat_map, the attribute name is
514           updated from there.
515
516       set_table_meta_attr
517           Sets a single attribute in the table meta data. If the attribute
518           name appears in %compat_map, the attribute name is updated from
519           there.
520
521       table_meta_attr_changed
522           Called when an attribute of the meta data is modified.
523
524           If the modified attribute requires to reset a calculated attribute,
525           the calculated attribute is reset (deleted from meta data
526           structure) and the initialized flag is removed, too. The decision
527           is made based on %register_reset_on_modify.
528
529       register_reset_on_modify
530           Allows "set_table_meta_attr" to reset meta attributes when special
531           attributes are modified. For DBD::File, modifying one of "f_file",
532           "f_dir", "f_ext" or "f_lockfile" will reset "f_fqfn". DBD::DBM
533           extends the list for "dbm_type" and "dbm_mldbm" to reset the value
534           of "dbm_tietype".
535
536           If your DBD has calculated values in the meta data area, then call
537           "register_reset_on_modify":
538
539             my %reset_on_modify = (xxx_foo => "xxx_bar");
540             __PACKAGE__->register_reset_on_modify (\%reset_on_modify);
541
542       register_compat_map
543           Allows "get_table_meta_attr" and "set_table_meta_attr" to update
544           the attribute name to the current favored one:
545
546             # from DBD::DBM
547             my %compat_map = (dbm_ext => "f_ext");
548             __PACKAGE__->register_compat_map (\%compat_map);
549
550       open_file
551           Called to open the table's data file.
552
553           Depending on the attributes set in the table's meta data, the
554           following steps are performed. Unless "f_dontopen" is set to a true
555           value, "f_fqfn" must contain the full qualified file name for the
556           table to work on (file2table ensures this). The encoding in
557           "f_encoding" is applied if set and the file is opened. If "<f_fqln
558           "> (full qualified lock name) is set, this file is opened, too.
559           Depending on the value in "f_lock", the appropriate lock is set on
560           the opened data file or lock file.
561
562           After this is done, a derived class might add more steps in an
563           overridden "open_file" method.
564
565       new Instantiates the table. This is done in 3 steps:
566
567            1. get the table meta data
568            2. open the data file
569            3. bless the table data structure using inherited constructor new
570
571           It is not recommended to override the constructor of the table
572           class.  Find a reasonable place to add you extensions in one of the
573           above four methods.
574
575       drop
576           Implements the abstract table method for the "DROP" command.
577           Discards table meta data after all files belonging to the table are
578           closed and unlinked.
579
580           Overriding this method might be reasonable in very rare cases.
581
582       seek
583           Implements the abstract table method used when accessing the table
584           from the engine. "seek" is called every time the engine uses dumb
585           algorithms for iterating over the table content.
586
587       truncate
588           Implements the abstract table method used when dumb table
589           algorithms for "UPDATE" or "DELETE" need to truncate the table
590           storage after the last written row.
591
592       You should consult the documentation of "SQL::Eval::Table" (see
593       SQL::Eval) to get more information about the abstract methods of the
594       table's base class you have to override and a description of the table
595       meta information expected by the SQL engines.
596

AUTHOR

598       The module DBD::File is currently maintained by
599
600       H.Merijn Brand < h.m.brand at xs4all.nl > and Jens Rehsack  < rehsack
601       at googlemail.com >
602
603       The original author is Jochen Wiedmann.
604
606       Copyright (C) 2010-2013 by H.Merijn Brand & Jens Rehsack
607
608       All rights reserved.
609
610       You may freely distribute and/or modify this module under the terms of
611       either the GNU General Public License (GPL) or the Artistic License, as
612       specified in the Perl README file.
613
614
615
616perl v5.34.0                      2022-01-21          DBD::File::Developers(3)
Impressum