1DBD::File::Developers(3U)ser Contributed Perl DocumentatiDoBnD::File::Developers(3)
2
6 DBD::File::Developers - Developers documentation for DBD::File
7
9 perldoc DBD::File::Developers
10 perldoc DBD::File::Roadmap
12 This document describes how DBD developers can write DBD::File based
14 DBI drivers. It supplements DBI::DBD, which you should read first.
15
17 Each DBI driver must provide a package global "driver" method and three
18 DBI related classes:
19 DBD::File::dr
21 Driver package, contains the methods DBI calls indirectly via DBI
22 interface:
23 DBI->connect ('DBI:DBM:', undef, undef, {})
25 # invokes
27 package DBD::DBM::dr;
28 @DBD::DBM::dr::ISA = qw(DBD::File::dr);
29 sub connect ($$;$$$)
31 {
32 ...
33 }
34 Similar for "data_sources ()" and "disconnect_all()".
36 Pure Perl DBI drivers derived from DBD::File do not usually need to
38 override any of the methods provided through the DBD::XXX::dr
39 package however if you need additional initialization in the
40 connect method you may need to.
41 DBD::File::db
43 Contains the methods which are called through DBI database handles
44 ($dbh). e.g.,
45 $sth = $dbh->prepare ("select * from foo");
47 # returns the f_encoding setting for table foo
48 $dbh->csv_get_meta ("foo", "f_encoding");
49 DBD::File provides the typical methods required here. Developers
51 who write DBI drivers based on DBD::File need to override the
52 methods "set_versions" and "init_valid_attributes".
53 DBD::File::st
55 Contains the methods to deal with prepared statement handles. e.g.,
56 $sth->execute () or die $sth->errstr;
58 DBD::File
60 This is the main package containing the routines to initialize
61 DBD::File based DBI drivers. Primarily the "DBD::File::driver" method
62 is invoked, either directly from DBI when the driver is initialized or
63 from the derived class.
64 package DBD::DBM;
66 use base qw( DBD::File );
68 sub driver
70 {
71 my ( $class, $attr ) = @_;
72 ...
73 my $drh = $class->SUPER::driver( $attr );
74 ...
75 return $drh;
76 }
77 It is not necessary to implement your own driver method as long as
79 additional initialization (e.g. installing more private driver methods)
80 is not required. You do not need to call "setup_driver" as DBD::File
81 takes care of it.
82 DBD::File::dr
84 The driver package contains the methods DBI calls indirectly via the
85 DBI interface (see "DBI Class Methods" in DBI).
86 DBD::File based DBI drivers usually do not need to implement anything
88 here, it is enough to do the basic initialization:
89 package DBD:XXX::dr;
91 @DBD::XXX::dr::ISA = qw (DBD::File::dr);
93 $DBD::XXX::dr::imp_data_size = 0;
94 $DBD::XXX::dr::data_sources_attr = undef;
95 $DBD::XXX::ATTRIBUTION = "DBD::XXX $DBD::XXX::VERSION by Hans Mustermann";
96 DBD::File::db
98 This package defines the database methods, which are called via the DBI
99 database handle $dbh.
100 Methods provided by DBD::File:
102 ping
104 Simply returns the content of the "Active" attribute. Override when
105 your driver needs more complicated actions here.
106 prepare
108 Prepares a new SQL statement to execute. Returns a statement
109 handle, $sth - instance of the DBD:XXX::st. It is neither required
110 nor recommended to override this method.
111 FETCH
113 Fetches an attribute of a DBI database object. Private handle
114 attributes must have a prefix (this is mandatory). If a requested
115 attribute is detected as a private attribute without a valid
116 prefix, the driver prefix (written as $drv_prefix) is added.
117 The driver prefix is extracted from the attribute name and verified
119 against "$dbh->{ $drv_prefix . "valid_attrs" }" (when it exists).
120 If the requested attribute value is not listed as a valid
121 attribute, this method croaks. If the attribute is valid and
122 readonly (listed in "$dbh->{ $drv_prefix . "readonly_attrs" }" when
123 it exists), a real copy of the attribute value is returned. So it's
124 not possible to modify "f_valid_attrs" from outside of
125 DBD::File::db or a derived class.
126 STORE
128 Stores a database private attribute. Private handle attributes must
129 have a prefix (this is mandatory). If a requested attribute is
130 detected as a private attribute without a valid prefix, the driver
131 prefix (written as $drv_prefix) is added. If the database handle
132 has an attribute "${drv_prefix}_valid_attrs" - for attribute names
133 which are not listed in that hash, this method croaks. If the
134 database handle has an attribute "${drv_prefix}_readonly_attrs",
135 only attributes which are not listed there can be stored (once they
136 are initialized). Trying to overwrite such an immutable attribute
137 forces this method to croak.
138 An example of a valid attributes list can be found in
140 "DBD::File::db::init_valid_attributes".
141 set_versions
143 This method sets the attributes "f_version", "sql_nano_version",
144 "sql_statement_version" and (if not prohibited by a restrictive
145 "${prefix}_valid_attrs") "${prefix}_version".
146 This method is called at the end of the "connect ()" phase.
148 When overriding this method, do not forget to invoke the superior
150 one.
151 init_valid_attributes
153 This method is called after the database handle is instantiated as
154 the first attribute initialization.
155 "DBD::File::db::init_valid_attributes" initializes the attributes
157 "f_valid_attrs", "sql_valid_attrs", "f_readonly_attrs" and
158 "sql_readonly_attrs".
159 When overriding this method, do not forget to invoke the superior
161 one, preferably before doing anything else. Compatibility table
162 attribute access must be initialized here to allow DBD::File to
163 instantiate the map tie:
164 # for DBD::CSV
166 $dbh->{csv_meta} = "csv_tables";
167 # for DBD::DBM
168 $dbh->{dbm_meta} = "dbm_tables";
169 # for DBD::AnyData
170 $dbh->{ad_meta} = "ad_tables";
171 init_default_attributes
173 This method is called after the database handle is instantiated to
174 initialize the default attributes.
175 "DBD::File::db::init_default_attributes" initializes the attributes
177 "f_dir", "f_meta", "f_meta_map", "f_version",
178 "sql_identifier_case", "sql_quoted_identifier_case" and
179 "sql_handler".
180 When the derived implementor class provides the attribute to
182 validate attributes (e.g. "$dbh->{dbm_valid_attrs} = {...};") or
183 the attribute containing the immutable attributes (e.g.
184 "$dbh->{dbm_readonly_attrs} = {...};"), the attributes
185 "drv_valid_attrs", "drv_readonly_attrs", "drv_version" and
186 "drv_meta" are added (when available) to the list of valid and
187 immutable attributes (where "drv_" is interpreted as the driver
188 prefix).
189 If "drv_meta" is set, an attribute with the name in "drv_meta" is
191 initialized providing restricted read/write access to the meta data
192 of the tables using "DBD::File::TieTables" in the first (table)
193 level and "DBD::File::TieMeta" for the meta attribute level.
194 "DBD::File::TieTables" uses "DBD::DRV::Table::get_table_meta" to
195 initialize the second level tied hash on FETCH/STORE. The
196 "DBD::File::TieMeta" class uses
197 "DBD::DRV::Table::get_table_meta_attr" to FETCH attribute values
198 and "DBD::DRV::Table::set_table_meta_attr" to STORE attribute
199 values. This allows it to map meta attributes for compatibility
200 reasons.
201 get_versions
203 This method is called by the code injected into the instantiated
204 driver to provide the user callable driver method
205 "${prefix}versions" (e.g. "dbm_versions", "csv_versions", ...).
206 The DBD::File implementation returns all version information known
208 by DBD::File (e.g. DBI version, Perl version, DBD::File version and
209 the SQL handler version).
210 "get_versions" takes the $dbh as the first argument and optionally
212 a second argument containing a table name. The second argument is
213 not evaluated in "DBD::File::db::get_versions" itself - but might
214 be in the future.
215 If the derived implementor class provides a method named
217 "get_${drv_prefix}versions", this is invoked and the return value
218 of it is associated to the derived driver name:
219 if (my $dgv = $dbh->{ImplementorClass}->can ("get_" . $drv_prefix . "versions") {
221 (my $derived_driver = $dbh->{ImplementorClass}) =~ s/::db$//;
222 $versions{$derived_driver} = &$dgv ($dbh, $table);
223 }
224 Override it to add more version information about your module,
226 (e.g. some kind of parser version in case of DBD::CSV, ...), if
227 one line is not enough room to provide all relevant information.
228 get_single_table_meta
230 get_file_meta
231 Retrieve an attribute from a table's meta information. The method
232 signature is "get_file_meta ($dbh, $table, $attr)". This method is
233 called by the injected db handle method "${drv_prefix}get_meta".
234 While get_file_meta allows $table or $attr to be a list of tables
236 or attributes to retrieve, get_single_table_meta allows only one
237 table name and only one attribute name. A table name of '.' (single
238 dot) is interpreted as the default table and this will retrieve the
239 appropriate attribute globally from the dbh. This has the same
240 restrictions as "$dbh->{$attrib}".
241 get_file_meta allows '+' and '*' as wildcards for table names and
243 $table being a regular expression matching against the table names
244 (evaluated without the default table). The table name '*' is all
245 currently known tables, including the default one. The table name
246 '+' is all table names which conform to ANSI file name restrictions
247 (/^[_A-Za-z0-9]+$/).
248 The table meta information is retrieved using the get_table_meta
250 and get_table_meta_attr methods of the table class of the
251 implementation.
252 set_single_table_meta
254 set_file_meta
255 Sets an attribute in a table's meta information. The method
256 signature is "set_file_meta ($dbh, $table, $attr, $value)". This
257 method is called by the injected db handle method
258 "${drv_prefix}set_meta".
259 While set_file_meta allows $table to be a list of tables and $attr
261 to be a hash of several attributes to set, set_single_table_meta
262 allows only one table name and only one attribute name/value pair.
263 The wildcard characters for the table name are the same as for
265 get_file_meta.
266 The table meta information is updated using the get_table_meta and
268 set_table_meta_attr methods of the table class of the
269 implementation.
270 clear_file_meta
272 Clears all meta information cached about a table. The method
273 signature is "clear_file_meta ($dbh, $table)". This method is
274 called by the injected db handle method "${drv_prefix}clear_meta".
275 sql_parser_object
277 Returns a SQL::Parser instance, when "sql_handler" is set to
278 "SQL::Statement". The parser instance is stored in
279 "sql_parser_object".
280 It is not recommended to override this method.
282 disconnect
284 Disconnects from a database. All local table information is
285 discarded and the "Active" attribute is set to 0.
286 type_info_all
288 Returns information about all the types supported by DBD::File.
289 table_info
291 Returns a statement handle which is prepared to deliver information
292 about all known tables.
293 list_tables
295 Returns a list of all known table names.
296 quote
298 Quotes a string for use in SQL statements.
299 commit
301 Warns about a useless call (if warnings enabled) and returns.
302 DBD::File is typically a driver which commits every action
303 instantly when executed.
304 rollback
306 Warns about a useless call (if warnings enabled) and returns.
307 DBD::File is typically a driver which commits every action
308 instantly when executed.
309 DBD::File::st
311 Contains the methods to deal with prepared statement handles:
312 bind_param
314 Common routine to bind placeholders to a statement for execution.
315 It is dangerous to override this method without detailed knowledge
316 about the DBD::File internal storage structure.
317 execute
319 Executes a previously prepared statement (with placeholders, if
320 any).
321 finish
323 Finishes a statement handle, discards all buffered results. The
324 prepared statement is not discarded so the statement can be
325 executed again.
326 fetch
328 Fetches the next row from the result-set. This method may be
329 rewritten in a later version and if it's overridden in a derived
330 class, the derived implementation should not rely on the storage
331 details.
332 fetchrow_arrayref
334 Alias for "fetch".
335 FETCH
337 Fetches statement handle attributes. Supported attributes (for full
338 overview see "Statement Handle Attributes" in DBI) are "NAME" and
339 "NULLABLE". Each column is returned as "NULLABLE" which might be
340 wrong depending on the derived backend storage. If the statement
341 handle has private attributes, they can be fetched using this
342 method, too. Note that statement attributes are not associated with
343 any table used in this statement.
344 This method usually requires extending in a derived implementation.
346 See DBD::CSV or DBD::DBM for some example.
347 STORE
349 Allows storing of statement private attributes.
350 rows
352 Returns the number of rows affected by the last execute. This
353 method might return "undef".
354 DBD::File::Statement
356 Derives from DBI::SQL::Nano::Statement to provide following method:
357 open_table
359 Implements the open_table method required by SQL::Statement and
360 DBI::SQL::Nano. All the work for opening the file(s) belonging to
361 the table is handled and parameterized in DBD::File::Table. Unless
362 you intend to add anything to the following implementation, an
363 empty DBD::XXX::Statement package satisfies DBD::File.
364 sub open_table ($$$$$)
366 {
367 my ($self, $data, $table, $createMode, $lockMode) = @_;
368 my $class = ref $self;
370 $class =~ s/::Statement/::Table/;
371 my $flags = {
373 createMode => $createMode,
374 lockMode => $lockMode,
375 };
376 $self->{command} eq "DROP" and $flags->{dropMode} = 1;
377 return $class->new ($data, { table => $table }, $flags);
379 } # open_table
380 DBD::File::Table
382 Derives from DBI::SQL::Nano::Table and provides physical file access
383 for the table data which are stored in the files.
384 file2table
386 This method tries to map a filename to the associated table name.
387 It is called with a partially filled meta structure for the
388 resulting table containing at least the following attributes:
389 "f_ext", "f_dir", "f_lockfile" and "sql_identifier_case".
390 If a file/table map can be found then this method sets the
392 "f_fqfn", "f_fqbn", "f_fqln" and "table_name" attributes in the
393 meta structure. If a map cannot be found the table name will be
394 undef.
395 bootstrap_table_meta
397 Initializes a table meta structure. Can be safely overridden in a
398 derived class, as long as the "SUPER" method is called at the end
399 of the overridden method.
400 It copies the following attributes from the database into the table
402 meta data "f_dir", "f_ext", "f_encoding", "f_lock", "f_schema",
403 "f_lockfile" and "sql_identifier_case" and makes them sticky to the
404 table.
405 This method should be called before you attempt to map between file
407 name and table name to ensure the correct directory, extension etc.
408 are used.
409 init_table_meta
411 Initializes more attributes of the table meta data - usually more
412 expensive ones (e.g. those which require class instantiations) -
413 when the file name and the table name could mapped.
414 get_table_meta
416 Returns the table meta data. If there are none for the required
417 table, a new one is initialized. When it fails, nothing is
418 returned. On success, the name of the table and the meta data
419 structure is returned.
420 get_table_meta_attr
422 Returns a single attribute from the table meta data. This method
423 should be overridden when mapped attribute names should be returned
424 for compatibility reasons.
425 set_table_meta_attr
427 Sets a single attribute in the table meta data. This method should
428 be overridden when mapped attribute names should be modified for
429 compatibility reasons.
430 If the modified attribute requires to reset a calculated attribute,
432 the calculated attribute is reset (deleted from meta data
433 structure) and the initialized flag is removed, too.
434 register_reset_on_modify
436 Allows "set_table_meta_attr" to reset meta attributes when special
437 attributes are modified. For DBD::File, modifying one of "f_file",
438 "f_dir", "f_ext" or "f_lockfile" will reset "f_fqfn". DBD::DBM
439 extends the list for "dbm_type" and "dbm_mldbm" to reset the value
440 of "dbm_tietype".
441 If your DBD has calculated values in the meta data area, then call
443 "register_reset_on_modify":
444 my %reset_on_modify = ( "xxx_foo" => "xxx_bar" );
446 __PACKAGE__->register_reset_on_modify( \%reset_on_modify );
447 open_file
449 Called to open the table's data file.
450 Depending on the attributes set in the table's meta data, the
452 following steps are performed. Unless "f_dontopen" is set to a true
453 value, "f_fqfn" must contain the full qualified file name for the
454 table to work on (file2table ensures this). The encoding in
455 "f_encoding" is applied if set and the file is opened. If "<f_fqln
456 "> (full qualified lock name) is set, this file is opened, too.
457 Depending on the value in "f_lock", the appropriate lock is set on
458 the opened data file or lock file.
459 After this is done, a derived class might add more steps in an
461 overridden "open_file" method.
462 new Instantiates the table. This is done in 3 steps:
464 1. get the table meta data
466 2. open the data file
467 3. bless the table data structure using inherited constructor new
468 It is not recommended to override the constructor of the table
470 class. Find a reasonable place to add you extensions in one of the
471 above four methods.
472 drop
474 Implements the abstract table method for the "DROP" command.
475 Discards table meta data after all files belonging to the table are
476 closed and unlinked.
477 Overriding this method might be reasonable in very rare cases.
479 seek
481 Implements the abstract table method used when accessing the table
482 from the engine. "seek" is called every time the engine uses dumb
483 algorithms for iterating over the table content.
484 truncate
486 Implements the abstract table method used when dumb table
487 algorithms for "UPDATE" or "DELETE" need to truncate the table
488 storage after the last written row.
489 You should consult the documentation of "SQL::Eval::Table" (see
491 SQL::Eval) to get more information about the abstract methods of the
492 table's base class you have to override and a description of the table
493 meta information expected by the SQL engines.
494
496 The module DBD::File is currently maintained by
497 H.Merijn Brand < h.m.brand at xs4all.nl > and Jens Rehsack < rehsack
499 at googlemail.com >
500 The original author is Jochen Wiedmann.
502
504 Copyright (C) 2010 by H.Merijn Brand & Jens Rehsack
505 All rights reserved.
507 You may freely distribute and/or modify this module under the terms of
509 either the GNU General Public License (GPL) or the Artistic License, as
510 specified in the Perl README file.
511perl v5.12.1 2010-07-02 DBD::File::Developers(3)