DBD::File(3)

📦
version 1.656 · 26 versions
, in fedora 43, fedora 44

💖 DBD::File(3) — User Contributed Perl Documentation 💖

okay so, bestie, welcome to the manual page for DBD::File, straight outta the User Contributed Perl Documentation. it's giving foundational. it's giving main character origin story. buckle up 🎀

🌸 NAME 🌸

DBD::File — the base class for writing file-based DBI drivers. that's it, that's the whole name, no notes 💅

✨ SYNOPSIS ✨

so here's the vibe: this module is a base class for writing other DBDs. 😌 it's the blueprint, the template, the little scaffolding that other drivers get built on top of.

and like — it is not intended to function as a DBD itself. technically it is possible, bestie, it's not gonna explode or anything 🙈 but that's not what it's for, iykyk. it's a parent class, not a whole personality.

if what you actually want is to poke at flat files? then no cap, go use DBD::AnyData, or DBD::CSV — both of which are subclasses of DBD::File 🦋. they're the ones who actually showed up to do the job. DBD::File is the one who raised them. periodt. 👑

💅 DESCRIPTION 💅

okay so bestie, here's the tea — DBD::File is not a true DBI driver. it's an abstract base class you derive concrete DBI drivers from. and what that actually means? those drivers vibe with plain files. like CSV files, INI files, that whole situation. 🦋 the module is built on top of SQL::Statement, which is a simple SQL engine.

want the lore? check DBI for the DBI details, SQL::Statement for the SQL::Statement details, and peep DBD::CSV, DBD::DBM or DBD::AnyData for example drivers out here actually living their truth. ✨

🎀 Metadata 🎀

the attributes DBI handles all by itself (not DBD::File)

these ones are literally DBI's job and not ours, so they all work exactly as expected, no notes:

Active
ActiveKids
CachedKids
CompatMode             (Not used)
InactiveDestroy
AutoInactiveDestroy
Kids
PrintError
RaiseError
Warn                   (Not used)

the DBI attributes DBD::File actually handles

  • AutoCommit — always on. periodt. 💅
  • ChopBlanks — works. slay.
  • NUM_OF_FIELDS — valid after $sth->execute. ✅
  • NUM_OF_PARAMS — valid after $sth->prepare. ✅
  • NAME — valid after $sth->execute; and it's undef for Non-Select statements.
  • NULLABLE — ngl bestie, this one is not really working 😭 it 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 🙈

these ones? not invited to the party:

bind_param_inout
CursorName
LongReadLen
LongTruncOk

DBD::File specific attributes 🌸

on top of the DBI attributes, you can also use these dbh attributes:

  • f_dir — this is how you set the directory where the files get 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 gets converted into the appropriate absolute path name (based on the current working directory) at the moment 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. and because of this, folders to use cannot be created after the connection — they have to already 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 lets you specify an extension which:

  • 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 example above, 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 [reasonable] 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 its 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 the 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. you've been warned bestie. 🙈

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

💀 KNOWN BUGS AND LIMITATIONS 💀

okay bestie, sit down, we're doing the ✨fine print✨ portion of the tour. none of this is scary, it's just... the vibes have limits, and we respect them. 🫶

  • This module uses flock () internally but flock is not available on all platforms. on MacOS and Windows 95 there is literally no locking at all 😭 (which, honestly? maybe not that deep on MacOS and Windows 95, since there's only a single user anyway. one person, one vibe.)
  • The module stores details about the handled tables in a private area of the driver handle ($drh). this little data area is not shared between different driver instances, so if you do several DBI->connect () calls you'll get different table instances and different private data areas. it's giving separate bedrooms, no sleepovers. 🙈

this data area gets filled up for the first time when a table is accessed — whether that's via an SQL statement or via table_info — and it is not destroyed until the table is dropped or the driver handle is released. manual destruction is possible via f_clear_meta, so if you need to yeet it yourself, that's the way. 💅

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

  • f_ext
  • f_dir
  • f_dir_search
  • f_lock
  • f_lockfile
  • f_encoding
  • f_schema
  • col_names
  • sql_identifier_case

the following attribute is preserved in the data area only and cannot be set globally:

  • f_file

the following attributes are preserved in the data area only and are computed when initializing the data area:

  • f_fqfn
  • f_fqbn
  • f_fqln
  • table_name

for DBD::CSV tables this means: once you've opened "foo.csv" as a table named "foo", another table named "foo" that wants to access the file "foo.txt" cannot be opened. 💀 accessing "foo" will always access the file "foo.csv" in the memorized "f_dir", locking "f_lockfile" via memorized "f_lock". it's committed. it's locked in. it's in a situationship with that filename fr fr.

you can use f_clear_meta or the "f_file" attribute for a specific table to work around this. slay. ✨

  • When used with SQL::Statement and temporary tables, like:
CREATE TEMP TABLE ...

the table data processing bypasses DBD::File::Table. no file system calls will be made, and there are no clashes with existing (file based) tables that have the same name. temporary tables are chosen over file tables, but heads up — they will not be covered by table_info. 👑

👑 AUTHOR 👑

this module is currently maintained by

H.Merijn Brand < perl5 at tux.freedom.nl > and Jens Rehsack < rehsack at googlemail.com >

and the original author is Jochen Wiedmann. 💖 respect the founders, always.

 Copyright (C) 2009-2026 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. pick your fighter, both are iconic. ⭐

🌈 SEE ALSO 🌈

go read these next, they're the group chat you'll be in:

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

and that's the whole page, bestie!! 🦋 you made it to the very bottom, which means you read a lot of Perl docs tonight and honestly? iconic behavior. this was perl v5.42.3, dated 2026-10-19, and you've officially survived DBD::File(3). 😭💖 go hydrate, then go flock responsibly. periodt. 💅✨

📦 where this page comes from