DBD::File - Base class for writing DBI drivers
This module is a base class for writing other DBDs. It is not intended to function as a DBD itself. If you want to access flatfiles, use DBD::AnyData, or DBD::CSV, (both of which are subclasses of DBD::File).
The DBD::File module is not a true DBI driver, but an abstract base class for deriving concrete DBI drivers from it. The implication is, that these drivers work with plain files, for example CSV files or INI files. The module is based on the SQL::Statement module, a simple SQL engine.
See DBI for details on DBI, SQL::Statement for details on SQL::Statement and DBD::CSV, DBD::DBM or DBD::AnyData for example drivers.
The following attributes are handled by DBI itself and not by DBD::File, thus they all work like expected:
Active ActiveKids CachedKids CompatMode (Not used) InactiveDestroy Kids PrintError RaiseError Warn (Not used)
The following DBI attributes are handled by DBD::File:
Always on
Works
Valid after $sth->execute
$sth->execute
Valid after $sth->prepare
$sth->prepare
Valid after $sth->execute; undef for Non-Select statements.
Not really working, always returns an array ref of one's, as DBD::CSV doesn't verify input data. Valid after $sth->execute; undef for Non-Select statements.
These attributes and methods are not supported:
bind_param_inout CursorName LongReadLen LongTruncOk
In addition to the DBI attributes, you can use the following dbh attributes:
This attribute is used for setting the directory where the files are opened and it defaults to the current directory ("."). Usually you set it on the dbh but it may be overridden on the statement handle. See "BUGS AND LIMITATIONS".
This attribute is used for setting the file extension. The format is:
extension{/flag}
where the /flag is optional and the extension is case-insensitive. f_ext allows you to specify an extension which:
f_ext
o makes DBD::File prefer F<table.extension> over F<table>. o makes the table name the filename minus the extension. DBI:CSV:f_dir=data;f_ext=.csv
In the above example and when f_dir contains both table.csv and table, DBD::File will open table.csv and the table will be named "table". If table.csv does not exist but table does that file is opened and the table is also called "table".
f_dir
If f_ext is not specified and table.csv exists it will be opened and the table will be called "table.csv" which is probably not what you want.
NOTE: even though extensions are case-insensitive, table names are not.
DBI:CSV:f_dir=data;f_ext=.csv/r
The r flag means the file extension is required and any filename that does not match the extension is ignored.
r
This will set the schema name and defaults to the owner of the directory in which the table file resides. You can set f_schema to undef.
f_schema
undef
my $dbh = DBI->connect ("dbi:CSV:", "", "", { f_schema => undef, f_dir => "data", f_ext => ".csv/r", }) or die $DBI::errstr;
By setting the schema you effect the results from the tables call:
my @tables = $dbh->tables (); # no f_schema "merijn".foo "merijn".bar # f_schema => "dbi" "dbi".foo "dbi".bar # f_schema => undef foo bar
Defining f_schema to the empty string is equal to setting it to undef so the DSN can be dbi:CSV:f_schema=;f_dir=..
dbi:CSV:f_schema=;f_dir=.
The f_lock attribute is used to set the locking mode on the opened table files. Note that not all platforms support locking. By default, tables are opened with a shared lock for reading, and with an exclusive lock for writing. The supported modes are:
f_lock
No locking at all.
Shared locks will be used.
Exclusive locks will be used.
But see "KNOWN BUGS" below.
If you wish to use a lockfile extension other than '.lck', simply specify the f_lockfile attribute:
$dbh = DBI->connect('dbi:DBM:f_lockfile=.foo'); $dbh->{f_lockfile} = '.foo'; $dbh->{f_meta}->{qux}->{f_lockfile} = '.foo';
If you wish to disable locking, set the f_lockfile equal to 0.
$dbh = DBI->connect('dbi:DBM:f_lockfile=0'); $dbh->{f_lockfile} = 0; $dbh->{f_meta}->{qux}->{f_lockfile} = 0;
With this attribute, you can set the encoding in which the file is opened. This is implemented using binmode $fh, ":encoding(<f_encoding)">.
binmode $fh, ":encoding(<f_encoding
Private data area which contains information about the tables this module handles. Meta data of a table might not be available unless the table has been accessed first time doing a statement on it. But it's possible to pre-initialize attributes for each table wanted to use.
DBD::File recognizes the (public) attributes f_ext, f_dir, f_encoding, f_lock, and f_lockfile. Be very careful when modifying attributes you do not know, the consequence might be a destroyed table.
Internally private attributes to deal with SQL backends:
Contains the version of loaded DBI::SQL::Nano
Contains the version of loaded SQL::Statement
Contains either 'SQL::Statement' or 'DBI::SQL::Nano'.
Contains optionally temporary tables.
Do not modify any of above private attributes unless you understand the implications of doing so. The behavior of DBD::File and derived DBD's might be unpredictable when one or more of those attributes are modified.
The data_sources method returns a list of subdirectories of the current directory in the form "DBI:CSV:f_dir=$dirname".
data_sources
If you want to read the subdirectories of another directory, use
my ($drh) = DBI->install_driver ("CSV"); my (@list) = $drh->data_sources (f_dir => "/usr/local/csv_data" );
This method returns a list of file names inside $dbh->{f_dir}. Example:
my ($dbh) = DBI->connect ("DBI:CSV:f_dir=/usr/local/csv_data"); my (@list) = $dbh->func ("list_tables");
Note that the list includes all files contained in the directory, even those that have non-valid table names, from the view of SQL.
DBD::File currently supports two SQL engines: DBI::SQL::Nano and SQL::Statement. DBI::SQL::Nano supports a very limited subset of SQL statements, but it might be faster for some very simple tasks. SQL::Statement in contrast supports a much larger subset of ANSI SQL.
To use SQL::Statement, the module version 1.28 of SQL::Statement is a prerequisite and the environment variable DBI_SQL_NANO must not be set to a true value.
DBI_SQL_NANO
This module uses flock() internally but flock is not available on all platforms. On MacOS and Windows 95 there is no locking at all (perhaps not so important on MacOS and Windows 95, as there is only a single user).
The module stores details about the handled tables in a private area of the driver handle ($drh). This data area isn't shared between different driver instances, so several DBI->connect() calls will cause different table instances and private data areas.
$drh
DBI->connect()
This data area is filled for the first time when a table is accessed, either via an SQL statement or via table_info and is not destroyed when the table is dropped or the driver handle is released.
table_info
Following attributes are preserved in the data area and will evaluated instead of driver globals:
For DBD::CSV tables this means, once opened 'foo.csv' as table named 'foo', another table named 'foo' accessing the file 'foo.csl' cannot be opened. Accessing 'foo' will always access the file 'foo.csv' in memorized f_dir, locking f_lockfile via memorized f_lock.
f_lockfile
When used with SQL::Statement and the feature of temporary tables is used with
CREATE TEMP TABLE ...
the table data processing passes DBD::File::Table. No file system calls will be made, no influence with existing (file based) tables with the same name will occur. Temporary tables are chosen in favor over file tables, but they will not covered by table_info.
This module is currently maintained by
H.Merijn Brand < h.m.brand at xs4all.nl > and Jens Rehsack < rehsack at googlemail.com >
The original author is Jochen Wiedmann.
Copyright (C) 2009-2010 by H.Merijn Brand & Jens Rehsack Copyright (C) 2004-2009 by Jeff Zucker Copyright (C) 1998-2004 by Jochen Wiedmann
All rights reserved.
You may freely distribute and/or modify this module under the terms of either the GNU General Public License (GPL) or the Artistic License, as specified in the Perl README file.
DBI, DBD::DBM, DBD::CSV, Text::CSV, Text::CSV_XS, SQL::Statement, DBI::SQL::Nano
2 POD Errors
The following errors were encountered while parsing the POD:
Expected text after =item, not a number
To install DBI, copy and paste the appropriate command in to your terminal.
cpanm
cpanm DBI
CPAN shell
perl -MCPAN -e shell install DBI
For more information on module installation, please visit the detailed CPAN module installation guide.