1DBD::File::Developers(3U)ser Contributed Perl DocumentatiDoBnD::File::Developers(3)
2
6 DBD::File::Developers - Developers documentation for DBD::File
7
9 package DBD::myDriver;
10 use base qw( DBD::File );
12 sub driver
14 {
15 ...
16 my $drh = $proto->SUPER::driver ($attr);
17 ...
18 return $drh->{class};
19 }
20 sub CLONE { ... }
22 package DBD::myDriver::dr;
24 @ISA = qw( DBD::File::dr );
26 sub data_sources { ... }
28 ...
29 package DBD::myDriver::db;
31 @ISA = qw( DBD::File::db );
33 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 package DBD::myDriver::st;
42 @ISA = qw( DBD::File::st );
44 sub FETCH { ... }
46 sub STORE { ... }
47 package DBD::myDriver::Statement;
49 @ISA = qw( DBD::File::Statement );
51 package DBD::myDriver::Table;
53 @ISA = qw( DBD::File::Table );
55 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 sub bootstrap_table_meta { ... }
68 sub init_table_meta { ... }
69 sub table_meta_attr_changed { ... }
70 sub open_data { ... }
71 sub fetch_row { ... }
73 sub push_row { ... }
74 sub push_names { ... }
75 # 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
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
95 Each DBI driver must provide a package global "driver" method and three
96 DBI related classes:
97 DBD::File::dr
99 Driver package, contains the methods DBI calls indirectly via DBI
100 interface:
101 DBI->connect ('DBI:DBM:', undef, undef, {})
103 # invokes
105 package DBD::DBM::dr;
106 @DBD::DBM::dr::ISA = qw( DBD::File::dr );
107 sub connect ($$;$$$)
109 {
110 ...
111 }
112 Similar for "data_sources" and "disconnect_all".
114 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 DBD::File::db
121 Contains the methods which are called through DBI database handles
122 ($dbh). e.g.,
123 $sth = $dbh->prepare ("select * from foo");
125 # returns the f_encoding setting for table foo
126 $dbh->csv_get_meta ("foo", "f_encoding");
127 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 DBD::File::st
133 Contains the methods to deal with prepared statement handles. e.g.,
134 $sth->execute () or die $sth->errstr;
136 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 package DBD::DBM;
144 use base qw( DBD::File );
146 sub driver
148 {
149 my ($class, $attr) = @_;
150 ...
151 my $drh = $class->SUPER::driver ($attr);
152 ...
153 return $drh;
154 }
155 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 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 DBD::File based DBI drivers usually do not need to implement anything
166 here, it is enough to do the basic initialization:
167 package DBD:XXX::dr;
169 @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 DBD::File::db
176 This package defines the database methods, which are called via the DBI
177 database handle $dbh.
178 Methods provided by DBD::File:
180 ping
182 Simply returns the content of the "Active" attribute. Override when
183 your driver needs more complicated actions here.
184 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 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 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 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 An example of a valid attributes list can be found in
218 "DBD::File::db::init_valid_attributes".
219 set_versions
221 This method sets the attribute "f_version" with the version of
222 DBD::File.
223 This method is called at the begin of the "connect ()" phase.
225 When overriding this method, do not forget to invoke the superior
227 one.
228 init_valid_attributes
230 This method is called after the database handle is instantiated as
231 the first attribute initialization.
232 "DBD::File::db::init_valid_attributes" initializes the attributes
234 "f_valid_attrs" and "f_readonly_attrs".
235 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 # 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 init_default_attributes
249 This method is called after the database handle is instantiated to
250 initialize the default attributes.
251 "DBD::File::db::init_default_attributes" initializes the attributes
253 "f_dir", "f_meta", "f_meta_map", "f_version".
254 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 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 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 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 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 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 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 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 The wildcard characters for the table name are the same as for
312 get_file_meta.
313 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 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 DBD::File::st
324 Contains the methods to deal with prepared statement handles:
325 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 This method usually requires extending in a derived implementation.
336 See DBD::CSV or DBD::DBM for some example.
337 DBD::File::TableSource::FileSystem
339 Provides data sources and table information on database driver and
340 database handle level.
341 package DBD::File::TableSource::FileSystem;
343 sub data_sources ($;$)
345 {
346 my ($class, $drh, $attrs) = @_;
347 ...
348 }
349 sub avail_tables
351 {
352 my ($class, $drh) = @_;
353 ...
354 }
355 The "data_sources" method is called when the user invokes any of the
357 following:
358 @ary = DBI->data_sources ($driver);
360 @ary = DBI->data_sources ($driver, \%attr);
361 @ary = $dbh->data_sources ();
363 @ary = $dbh->data_sources (\%attr);
364 The "avail_tables" method is called when the user invokes any of the
366 following:
367 @names = $dbh->tables ($catalog, $schema, $table, $type);
369 $sth = $dbh->table_info ($catalog, $schema, $table, $type);
371 $sth = $dbh->table_info ($catalog, $schema, $table, $type, \%attr);
372 $dbh->func ("list_tables");
374 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 DBD::File::DataSource::Stream
380 package DBD::File::DataSource::Stream;
381 @DBD::File::DataSource::Stream::ISA = 'DBI::DBD::SqlEngine::DataSource';
383 sub complete_table_name
385 {
386 my ($self, $meta, $file, $respect_case) = @_;
387 ...
388 }
389 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 package DBD::File::DataSource::Stream;
395 sub apply_encoding
397 {
398 my ($self, $meta, $fn) = @_;
399 ...
400 }
401 Applies the encoding from meta information ("$meta->{f_encoding}") to
403 the file handled opened in "open_data".
404 package DBD::File::DataSource::Stream;
406 sub open_data
408 {
409 my ($self, $meta, $attrs, $flags) = @_;
410 ...
411 }
412 Opens ("dup (2)") the file handle provided in "$meta->{f_file}".
414 package DBD::File::DataSource::Stream;
416 sub can_flock { ... }
418 Returns whether "flock (2)" is available or not (avoids retesting in
420 subclasses).
421 DBD::File::DataSource::File
423 package DBD::File::DataSource::File;
424 sub complete_table_name ($$;$)
426 {
427 my ($self, $meta, $table, $respect_case) = @_;
428 ...
429 }
430 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 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 package DBD::File::DataSource::File;
441 sub open_data ($)
443 {
444 my ($self, $meta, $attrs, $flags) = @_;
445 ...
446 }
447 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 DBD::File::Statement
458 Derives from DBI::SQL::Nano::Statement to provide following method:
459 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 sub open_table ($$$$$)
468 {
469 my ($self, $data, $table, $createMode, $lockMode) = @_;
470 my $class = ref $self;
472 $class =~ s/::Statement/::Table/;
473 my $flags = {
475 createMode => $createMode,
476 lockMode => $lockMode,
477 };
478 $self->{command} eq "DROP" and $flags->{dropMode} = 1;
479 return $class->new ($data, { table => $table }, $flags);
481 } # open_table
482 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 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 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 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 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 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 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 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 table_meta_attr_changed
522 Called when an attribute of the meta data is modified.
523 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 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 If your DBD has calculated values in the meta data area, then call
537 "register_reset_on_modify":
538 my %reset_on_modify = (xxx_foo => "xxx_bar");
540 __PACKAGE__->register_reset_on_modify (\%reset_on_modify);
541 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 # from DBD::DBM
547 my %compat_map = (dbm_ext => "f_ext");
548 __PACKAGE__->register_compat_map (\%compat_map);
549 open_file
551 Called to open the table's data file.
552 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 After this is done, a derived class might add more steps in an
563 overridden "open_file" method.
564 new Instantiates the table. This is done in 3 steps:
566 1. get the table meta data
568 2. open the data file
569 3. bless the table data structure using inherited constructor new
570 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 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 Overriding this method might be reasonable in very rare cases.
581 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 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 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
598 The module DBD::File is currently maintained by
599 H.Merijn Brand < h.m.brand at xs4all.nl > and Jens Rehsack < rehsack
601 at googlemail.com >
602 The original author is Jochen Wiedmann.
604
606 Copyright (C) 2010-2013 by H.Merijn Brand & Jens Rehsack
607 All rights reserved.
609 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.
613perl v5.30.0 2019-07-26 DBD::File::Developers(3)