Metadata

The following attributes are handled by DBI itself and not by DBD::File, thus they all work as expected:

Active
ActiveKids
CachedKids
CompatMode             (Not used)
InactiveDestroy
AutoInactiveDestroy
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 ones, except the affected table has been created in this session. Valid after "$sth->execute"; undef for non-select statements.

Unsupported DBI attributes and methods

bind_param_inout

CursorName

LongReadLen

LongTruncOk

DBD::File specific attributes

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 per table (see f_meta).

When the value for "f_dir" is a relative path, it is converted into the appropriate absolute path name (based on the current working directory) when the dbh attribute is set.

f_dir => "/data/foo/csv",

If "f_dir" is set to a non-existing location, the connection will fail. See CVE-2014-10401 for reasoning. Because of this, folders to use cannot be created after the connection, but must exist before the connection is initiated.

See "KNOWN BUGS AND LIMITATIONS".

f_dir_search

This optional attribute can be set to pass a list of folders to also find existing tables. It will not be used to create new files.

f_dir_search => [ "/data/bar/csv", "/dump/blargh/data" ],

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:

f_ext => ".csv/r",

• makes DBD::File prefer table.extension over table.
• 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.

Usually you set it on the dbh but it may be overridden per table (see f_meta).

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 affect 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->{dbm_tables}{qux}{f_lockfile} = ".foo";

If you wish to disable locking, set the "f_lockfile" to 0.

$dbh = DBI->connect ("dbi:DBM:f_lockfile=0");
$dbh->{f_lockfile} = 0;
$dbh->{dbm_tables}{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 aliasing "sql_meta" in DBI::DBD::SqlEngine which contains information about the tables this module handles. Table meta data might not be available until the table has been accessed for the first time e.g., by issuing a select on it however it is possible to pre-initialize attributes for each table you use.

DBD::File recognizes the (public) attributes "f_ext", "f_dir", "f_file", "f_encoding", "f_lock", "f_lockfile", "f_schema", in addition to the attributes "sql_meta" in DBI::DBD::SqlEngine already supports. Be very careful when modifying attributes you do not know, the consequence might be a destroyed or corrupted table.

"f_file" is an attribute applicable to table meta data only and you will not find a corresponding attribute in the dbh. Whilst it may be reasonable to have several tables with the same column names, it is not for the same file name. If you need access to the same file using different table names, use "SQL::Statement" as the SQL engine and the "AS" keyword:

SELECT * FROM tbl AS t1, tbl AS t2 WHERE t1.id = t2.id

"f_file" can be an absolute path name or a relative path name but if it is relative, it is interpreted as being relative to the "f_dir" attribute of the table meta data. When "f_file" is set DBD::File will use "f_file" as specified and will not attempt to work out an alternative for "f_file" using the "table name" and "f_ext" attribute.

While "f_meta" is a private and readonly attribute (which means, you cannot modify it's values), derived drivers might provide restricted write access through another attribute. Well known accessors are "csv_tables" for DBD::CSV, "ad_tables" for DBD::AnyData and "dbm_tables" for DBD::DBM.

New opportunities for attributes from DBI::DBD::SqlEngine

sql_table_source

"$dbh->{sql_table_source}" can be set to DBD::File::TableSource::FileSystem (and is the default setting of DBD::File). This provides usual behaviour of previous DBD::File releases on

@ary = DBI->data_sources ($driver);
@ary = DBI->data_sources ($driver, \%attr);
@ary = $dbh->data_sources ();
@ary = $dbh->data_sources (\%attr);
@names = $dbh->tables ($catalog, $schema, $table, $type);
$sth = $dbh->table_info ($catalog, $schema, $table, $type);
$sth = $dbh->table_info ($catalog, $schema, $table, $type, \%attr);
$dbh->func ("list_tables");

sql_data_source

"$dbh->{sql_data_source}" can be set to either DBD::File::DataSource::File, which is default and provides the well known behavior of DBD::File releases prior to 0.41, or DBD::File::DataSource::Stream, which reuses already opened file-handle for operations.

Internally private attributes to deal with SQL backends

Do not modify any of these private attributes unless you understand the implications of doing so. The behavior of DBD::File and derived DBDs might be unpredictable when one or more of those attributes are modified.

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 the text 'SQL::Statement' or 'DBI::SQL::Nano'.

sql_ram_tables

Contains optionally temporary tables.

sql_flags

Contains optional flags to instantiate the SQL::Parser parsing engine when SQL::Statement is used as SQL engine. See SQL::Parser for valid flags.

Driver private methods

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

Additional methods

The following methods are only available via their documented name when DBD::File is used directly. Because this is only reasonable for testing purposes, the real names must be used instead. Those names can be computed by replacing the "f_" in the method name with the driver prefix.

f_versions

Signature:

sub f_versions (;$)
{
  my ($table_name) = @_;
  $table_name ||= ".";
  ...
  }

Returns the versions of the driver, including the DBI version, the Perl version, DBI::PurePerl version (if DBI::PurePerl is active) and the version of the SQL engine in use.

my $dbh = DBI->connect ("dbi:File:");
my $f_versions = $dbh->func ("f_versions");
print "$f_versions\n";
__END__
# DBD::File              0.41 using IO::File (1.16)
#   DBI::DBD::SqlEngine  0.05 using SQL::Statement 1.406
# DBI                    1.623
# OS                     darwin (12.2.1)
# Perl                   5.017006 (darwin-thread-multi-ld-2level)

Called in list context, f_versions will return an array containing each line as single entry.

Some drivers might use the optional (table name) argument and modify version information related to the table (e.g. DBD::DBM provides storage backend information for the requested table, when it has a table name).