NAME

DBD::File - Base class for writing DBI drivers

SYNOPSIS

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).

DESCRIPTION

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.

Metadata

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:

AutoCommit

Always on

ChopBlanks

Works

NUM_OF_FIELDS

Valid after $sth->execute

NUM_OF_PARAMS

Valid after $sth->prepare

NAME

Valid after $sth->execute; undef for Non-Select statements.

NULLABLE

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:

f_dir

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".

f_ext

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:

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".

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.

f_schema

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.

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=..

f_lock

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:

0

No locking at all.

1

Shared locks will be used.

2

Exclusive locks will be used.

But see "KNOWN BUGS" below.

f_lockfile

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;

f_encoding

With this attribute, you can set the encoding in which the file is opened. This is implemented using binmode $fh, ":encoding(<f_encoding)">.

f_meta

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:

sql_nano_version

Contains the version of loaded DBI::SQL::Nano

sql_statement_version

Contains the version of loaded SQL::Statement

sql_handler

Contains either 'SQL::Statement' or 'DBI::SQL::Nano'.

sql_ram_tables

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.

Driver private methods

data_sources

The data_sources method returns a list of subdirectories of the current directory in the form "DBI:CSV:f_dir=$dirname".

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" );

list_tables

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.

SQL ENGINES

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.

KNOWN BUGS AND LIMITATIONS

• 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.

  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.

  Following attributes are preserved in the data area and will evaluated instead of driver globals:

  f_ext

  f_dir

  f_lock

  f_lockfile

  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.

• 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.

AUTHOR

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 AND LICENSE

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.

SEE ALSO

DBI, DBD::DBM, DBD::CSV, Text::CSV, Text::CSV_XS, SQL::Statement, DBI::SQL::Nano

cpanm DBI

perl -MCPAN -e shell
install DBI