DBD::File(3pm)

1DBD::File(3)          User Contributed Perl Documentation         DBD::File(3)
2
3
4

NAME

6       DBD::File - Base class for writing file based DBI drivers
7

SYNOPSIS

9       This module is a base class for writing other DBDs.  It is not intended
10       to function as a DBD itself (though it is possible).  If you want to
11       access flat files, use DBD::AnyData, or DBD::CSV (both of which are
12       subclasses of DBD::File).
13

DESCRIPTION

15       The DBD::File module is not a true DBI driver, but an abstract base
16       class for deriving concrete DBI drivers from it. The implication is,
17       that these drivers work with plain files, for example CSV files or INI
18       files. The module is based on the SQL::Statement module, a simple SQL
19       engine.
20
21       See DBI for details on DBI, SQL::Statement for details on
22       SQL::Statement and DBD::CSV, DBD::DBM or DBD::AnyData for example
23       drivers.
24
25   Metadata
26       The following attributes are handled by DBI itself and not by
27       DBD::File, thus they all work as expected:
28
29           Active
30           ActiveKids
31           CachedKids
32           CompatMode             (Not used)
33           InactiveDestroy
34           AutoInactiveDestroy
35           Kids
36           PrintError
37           RaiseError
38           Warn                   (Not used)
39
40       The following DBI attributes are handled by DBD::File:
41
42       AutoCommit
43
44       Always on.
45
46       ChopBlanks
47
48       Works.
49
50       NUM_OF_FIELDS
51
52       Valid after "$sth->execute".
53
54       NUM_OF_PARAMS
55
56       Valid after "$sth->prepare".
57
58       NAME
59
60       Valid after "$sth->execute"; undef for Non-Select statements.
61
62       NULLABLE
63
64       Not really working, always returns an array ref of ones, except the
65       affected table has been created in this session.  Valid after
66       "$sth->execute"; undef for non-select statements.
67
68       Unsupported DBI attributes and methods
69
70       bind_param_inout
71
72       CursorName
73
74       LongReadLen
75
76       LongTruncOk
77
78       DBD::File specific attributes
79
80       In addition to the DBI attributes, you can use the following dbh
81       attributes:
82
83       f_dir
84
85       This attribute is used for setting the directory where the files are
86       opened and it defaults to the current directory (.). Usually you set it
87       on the dbh but it may be overridden per table (see f_meta).
88
89       When the value for "f_dir" is a relative path, it is converted into the
90       appropriate absolute path name (based on the current working directory)
91       when the dbh attribute is set.
92
93         f_dir => "/data/foo/csv",
94
95       See "KNOWN BUGS AND LIMITATIONS".
96
97       f_dir_search
98
99       This optional attribute can be set to pass a list of folders to also
100       find existing tables. It will not be used to create new files.
101
102         f_dir_search => [ "/data/bar/csv", "/dump/blargh/data" ],
103
104       f_ext
105
106       This attribute is used for setting the file extension. The format is:
107
108         extension{/flag}
109
110       where the /flag is optional and the extension is case-insensitive.
111       "f_ext" allows you to specify an extension which:
112
113         f_ext => ".csv/r",
114
115       •   makes DBD::File prefer table.extension over table.
116
117       •   makes the table name the filename minus the extension.
118
119           DBI:CSV:f_dir=data;f_ext=.csv
120
121       In the above example and when "f_dir" contains both table.csv and
122       table, DBD::File will open table.csv and the table will be named
123       "table". If table.csv does not exist but table does that file is opened
124       and the table is also called "table".
125
126       If "f_ext" is not specified and table.csv exists it will be opened and
127       the table will be called "table.csv" which is probably not what you
128       want.
129
130       NOTE: even though extensions are case-insensitive, table names are not.
131
132           DBI:CSV:f_dir=data;f_ext=.csv/r
133
134       The "r" flag means the file extension is required and any filename that
135       does not match the extension is ignored.
136
137       Usually you set it on the dbh but it may be overridden per table (see
138       f_meta).
139
140       f_schema
141
142       This will set the schema name and defaults to the owner of the
143       directory in which the table file resides. You can set "f_schema" to
144       "undef".
145
146           my $dbh = DBI->connect ("dbi:CSV:", "", "", {
147               f_schema => undef,
148               f_dir    => "data",
149               f_ext    => ".csv/r",
150               }) or die $DBI::errstr;
151
152       By setting the schema you affect the results from the tables call:
153
154           my @tables = $dbh->tables ();
155
156           # no f_schema
157           "merijn".foo
158           "merijn".bar
159
160           # f_schema => "dbi"
161           "dbi".foo
162           "dbi".bar
163
164           # f_schema => undef
165           foo
166           bar
167
168       Defining "f_schema" to the empty string is equal to setting it to
169       "undef" so the DSN can be "dbi:CSV:f_schema=;f_dir=.".
170
171       f_lock
172
173       The "f_lock" attribute is used to set the locking mode on the opened
174       table files. Note that not all platforms support locking.  By default,
175       tables are opened with a shared lock for reading, and with an exclusive
176       lock for writing. The supported modes are:
177
178         0: No locking at all.
179
180         1: Shared locks will be used.
181
182         2: Exclusive locks will be used.
183
184       But see KNOWN BUGS below.
185
186       f_lockfile
187
188       If you wish to use a lockfile extension other than ".lck", simply
189       specify the "f_lockfile" attribute:
190
191         $dbh = DBI->connect ("dbi:DBM:f_lockfile=.foo");
192         $dbh->{f_lockfile} = ".foo";
193         $dbh->{dbm_tables}{qux}{f_lockfile} = ".foo";
194
195       If you wish to disable locking, set the "f_lockfile" to 0.
196
197         $dbh = DBI->connect ("dbi:DBM:f_lockfile=0");
198         $dbh->{f_lockfile} = 0;
199         $dbh->{dbm_tables}{qux}{f_lockfile} = 0;
200
201       f_encoding
202
203       With this attribute, you can set the encoding in which the file is
204       opened.  This is implemented using "binmode $fh,
205       ":encoding(<f_encoding>)"".
206
207       f_meta
208
209       Private data area aliasing "sql_meta" in DBI::DBD::SqlEngine which
210       contains information about the tables this module handles. Table meta
211       data might not be available until the table has been accessed for the
212       first time e.g., by issuing a select on it however it is possible to
213       pre-initialize attributes for each table you use.
214
215       DBD::File recognizes the (public) attributes "f_ext", "f_dir",
216       "f_file", "f_encoding", "f_lock", "f_lockfile", "f_schema", in addition
217       to the attributes "sql_meta" in DBI::DBD::SqlEngine already supports.
218       Be very careful when modifying attributes you do not know, the
219       consequence might be a destroyed or corrupted table.
220
221       "f_file" is an attribute applicable to table meta data only and you
222       will not find a corresponding attribute in the dbh. Whilst it may be
223       reasonable to have several tables with the same column names, it is not
224       for the same file name. If you need access to the same file using
225       different table names, use "SQL::Statement" as the SQL engine and the
226       "AS" keyword:
227
228           SELECT * FROM tbl AS t1, tbl AS t2 WHERE t1.id = t2.id
229
230       "f_file" can be an absolute path name or a relative path name but if it
231       is relative, it is interpreted as being relative to the "f_dir"
232       attribute of the table meta data. When "f_file" is set DBD::File will
233       use "f_file" as specified and will not attempt to work out an
234       alternative for "f_file" using the "table name" and "f_ext" attribute.
235
236       While "f_meta" is a private and readonly attribute (which means, you
237       cannot modify it's values), derived drivers might provide restricted
238       write access through another attribute. Well known accessors are
239       "csv_tables" for DBD::CSV, "ad_tables" for DBD::AnyData and
240       "dbm_tables" for DBD::DBM.
241
242       New opportunities for attributes from DBI::DBD::SqlEngine
243
244       sql_table_source
245
246       "$dbh->{sql_table_source}" can be set to
247       DBD::File::TableSource::FileSystem (and is the default setting of
248       DBD::File). This provides usual behaviour of previous DBD::File
249       releases on
250
251         @ary = DBI->data_sources ($driver);
252         @ary = DBI->data_sources ($driver, \%attr);
253
254         @ary = $dbh->data_sources ();
255         @ary = $dbh->data_sources (\%attr);
256
257         @names = $dbh->tables ($catalog, $schema, $table, $type);
258
259         $sth = $dbh->table_info ($catalog, $schema, $table, $type);
260         $sth = $dbh->table_info ($catalog, $schema, $table, $type, \%attr);
261
262         $dbh->func ("list_tables");
263
264       sql_data_source
265
266       "$dbh->{sql_data_source}" can be set to either
267       DBD::File::DataSource::File, which is default and provides the well
268       known behavior of DBD::File releases prior to 0.41, or
269       DBD::File::DataSource::Stream, which reuses already opened file-handle
270       for operations.
271
272       Internally private attributes to deal with SQL backends
273
274       Do not modify any of these private attributes unless you understand the
275       implications of doing so. The behavior of DBD::File and derived DBDs
276       might be unpredictable when one or more of those attributes are
277       modified.
278
279       sql_nano_version
280
281       Contains the version of loaded DBI::SQL::Nano.
282
283       sql_statement_version
284
285       Contains the version of loaded SQL::Statement.
286
287       sql_handler
288
289       Contains either the text 'SQL::Statement' or 'DBI::SQL::Nano'.
290
291       sql_ram_tables
292
293       Contains optionally temporary tables.
294
295       sql_flags
296
297       Contains optional flags to instantiate the SQL::Parser parsing engine
298       when SQL::Statement is used as SQL engine. See SQL::Parser for valid
299       flags.
300
301   Driver private methods
302       Default DBI methods
303
304       data_sources
305
306       The "data_sources" method returns a list of subdirectories of the
307       current directory in the form "dbi:CSV:f_dir=$dirname".
308
309       If you want to read the subdirectories of another directory, use
310
311           my ($drh)  = DBI->install_driver ("CSV");
312           my (@list) = $drh->data_sources (f_dir => "/usr/local/csv_data");
313
314       Additional methods
315
316       The following methods are only available via their documented name when
317       DBD::File is used directly. Because this is only reasonable for testing
318       purposes, the real names must be used instead. Those names can be
319       computed by replacing the "f_" in the method name with the driver
320       prefix.
321
322       f_versions
323
324       Signature:
325
326         sub f_versions (;$)
327         {
328           my ($table_name) = @_;
329           $table_name ||= ".";
330           ...
331           }
332
333       Returns the versions of the driver, including the DBI version, the Perl
334       version, DBI::PurePerl version (if DBI::PurePerl is active) and the
335       version of the SQL engine in use.
336
337           my $dbh = DBI->connect ("dbi:File:");
338           my $f_versions = $dbh->func ("f_versions");
339           print "$f_versions\n";
340           __END__
341           # DBD::File              0.41 using IO::File (1.16)
342           #   DBI::DBD::SqlEngine  0.05 using SQL::Statement 1.406
343           # DBI                    1.623
344           # OS                     darwin (12.2.1)
345           # Perl                   5.017006 (darwin-thread-multi-ld-2level)
346
347       Called in list context, f_versions will return an array containing each
348       line as single entry.
349
350       Some drivers might use the optional (table name) argument and modify
351       version information related to the table (e.g. DBD::DBM provides
352       storage backend information for the requested table, when it has a
353       table name).
354

KNOWN BUGS AND LIMITATIONS

356       •   This module uses flock () internally but flock is not available on
357           all platforms. On MacOS and Windows 95 there is no locking at all
358           (perhaps not so important on MacOS and Windows 95, as there is only
359           a single user).
360
361       •   The module stores details about the handled tables in a private
362           area of the driver handle ($drh). This data area is not shared
363           between different driver instances, so several "DBI->connect ()"
364           calls will cause different table instances and private data areas.
365
366           This data area is filled for the first time when a table is
367           accessed, either via an SQL statement or via "table_info" and is
368           not destroyed until the table is dropped or the driver handle is
369           released.  Manual destruction is possible via f_clear_meta.
370
371           The following attributes are preserved in the data area and will
372           evaluated instead of driver globals:
373
374           f_ext
375           f_dir
376           f_dir_search
377           f_lock
378           f_lockfile
379           f_encoding
380           f_schema
381           col_names
382           sql_identifier_case
383
384           The following attributes are preserved in the data area only and
385           cannot be set globally.
386
387           f_file
388
389           The following attributes are preserved in the data area only and
390           are computed when initializing the data area:
391
392           f_fqfn
393           f_fqbn
394           f_fqln
395           table_name
396
397           For DBD::CSV tables this means, once opened "foo.csv" as table
398           named "foo", another table named "foo" accessing the file "foo.txt"
399           cannot be opened.  Accessing "foo" will always access the file
400           "foo.csv" in memorized "f_dir", locking "f_lockfile" via memorized
401           "f_lock".
402
403           You can use f_clear_meta or the "f_file" attribute for a specific
404           table to work around this.
405
406       •   When used with SQL::Statement and temporary tables e.g.,
407
408             CREATE TEMP TABLE ...
409
410           the table data processing bypasses DBD::File::Table. No file system
411           calls will be made and there are no clashes with existing (file
412           based) tables with the same name. Temporary tables are chosen over
413           file tables, but they will not covered by "table_info".
414

AUTHOR

416       This module is currently maintained by
417
418       H.Merijn Brand < h.m.brand at xs4all.nl > and Jens Rehsack < rehsack at
419       googlemail.com >
420
421       The original author is Jochen Wiedmann.
422

COPYRIGHT AND LICENSE

424        Copyright (C) 2009-2013 by H.Merijn Brand & Jens Rehsack
425        Copyright (C) 2004-2009 by Jeff Zucker
426        Copyright (C) 1998-2004 by Jochen Wiedmann
427
428       All rights reserved.
429
430       You may freely distribute and/or modify this module under the terms of
431       either the GNU General Public License (GPL) or the Artistic License, as
432       specified in the Perl README file.
433

NAME

SYNOPSIS

DESCRIPTION

KNOWN BUGS AND LIMITATIONS

AUTHOR

COPYRIGHT AND LICENSE

SEE ALSO