{
    "mode": "perldoc",
    "parameter": "DBD::File",
    "section": "",
    "url": "https://www.chedong.com/phpMan.php/perldoc/DBD%3A%3AFile/json",
    "generated": "2026-06-14T12:49:22Z",
    "synopsis": "This module is a base class for writing other DBDs. It is not intended to function as a DBD\nitself (though it is possible). If you want to access flat files, use DBD::AnyData, or DBD::CSV\n(both of which are subclasses of DBD::File).",
    "sections": {
        "NAME": {
            "content": "DBD::File - Base class for writing file based DBI drivers\n",
            "subsections": []
        },
        "SYNOPSIS": {
            "content": "This module is a base class for writing other DBDs. It is not intended to function as a DBD\nitself (though it is possible). If you want to access flat files, use DBD::AnyData, or DBD::CSV\n(both of which are subclasses of DBD::File).\n",
            "subsections": []
        },
        "DESCRIPTION": {
            "content": "The DBD::File module is not a true DBI driver, but an abstract base class for deriving concrete\nDBI drivers from it. The implication is, that these drivers work with plain files, for example\nCSV files or INI files. The module is based on the SQL::Statement module, a simple SQL engine.\n\nSee DBI for details on DBI, SQL::Statement for details on SQL::Statement and DBD::CSV, DBD::DBM\nor DBD::AnyData for example drivers.\n",
            "subsections": [
                {
                    "name": "Metadata",
                    "content": "The following attributes are handled by DBI itself and not by DBD::File, thus they all work as\nexpected:\n\nActive\nActiveKids\nCachedKids\nCompatMode             (Not used)\nInactiveDestroy\nAutoInactiveDestroy\nKids\nPrintError\nRaiseError\nWarn                   (Not used)\n\nThe following DBI attributes are handled by DBD::File:\nAutoCommit\nAlways on.\n\nChopBlanks\nWorks.\n\nNUMOFFIELDS\nValid after \"$sth->execute\".\n\nNUMOFPARAMS\nValid after \"$sth->prepare\".\n\nNAME\nValid after \"$sth->execute\"; undef for Non-Select statements.\n\nNULLABLE\nNot really working, always returns an array ref of ones, except the affected table has been\ncreated in this session. Valid after \"$sth->execute\"; undef for non-select statements.\n\nUnsupported DBI attributes and methods\nbindparaminout\nCursorName\nLongReadLen\nLongTruncOk\nDBD::File specific attributes\nIn addition to the DBI attributes, you can use the following dbh attributes:\n\nfdir\nThis attribute is used for setting the directory where the files are opened and it defaults to\nthe current directory (.). Usually you set it on the dbh but it may be overridden per table (see\nfmeta).\n\nWhen the value for \"fdir\" is a relative path, it is converted into the appropriate absolute\npath name (based on the current working directory) when the dbh attribute is set.\n\nfdir => \"/data/foo/csv\",\n\nSee \"KNOWN BUGS AND LIMITATIONS\".\n\nfdirsearch\nThis optional attribute can be set to pass a list of folders to also find existing tables. It\nwill not be used to create new files.\n\nfdirsearch => [ \"/data/bar/csv\", \"/dump/blargh/data\" ],\n\nfext\nThis attribute is used for setting the file extension. The format is:\n\nextension{/flag}\n\nwhere the /flag is optional and the extension is case-insensitive. \"fext\" allows you to specify\nan extension which:\n\nfext => \".csv/r\",\n\n*   makes DBD::File prefer table.extension over table.\n\n*   makes the table name the filename minus the extension.\n\nDBI:CSV:fdir=data;fext=.csv\n\nIn the above example and when \"fdir\" contains both table.csv and table, DBD::File will open\ntable.csv and the table will be named \"table\". If table.csv does not exist but table does that\nfile is opened and the table is also called \"table\".\n\nIf \"fext\" is not specified and table.csv exists it will be opened and the table will be called\n\"table.csv\" which is probably not what you want.\n\nNOTE: even though extensions are case-insensitive, table names are not.\n\nDBI:CSV:fdir=data;fext=.csv/r\n\nThe \"r\" flag means the file extension is required and any filename that does not match the\nextension is ignored.\n\nUsually you set it on the dbh but it may be overridden per table (see fmeta).\n\nfschema\nThis will set the schema name and defaults to the owner of the directory in which the table file\nresides. You can set \"fschema\" to \"undef\".\n\nmy $dbh = DBI->connect (\"dbi:CSV:\", \"\", \"\", {\nfschema => undef,\nfdir    => \"data\",\nfext    => \".csv/r\",\n}) or die $DBI::errstr;\n\nBy setting the schema you affect the results from the tables call:\n\nmy @tables = $dbh->tables ();\n\n# no fschema\n\"merijn\".foo\n\"merijn\".bar\n\n# fschema => \"dbi\"\n\"dbi\".foo\n\"dbi\".bar\n\n# fschema => undef\nfoo\nbar\n\nDefining \"fschema\" to the empty string is equal to setting it to \"undef\" so the DSN can be\n\"dbi:CSV:fschema=;fdir=.\".\n\nflock\nThe \"flock\" attribute is used to set the locking mode on the opened table files. Note that not\nall platforms support locking. By default, tables are opened with a shared lock for reading, and\nwith an exclusive lock for writing. The supported modes are:\n\n0: No locking at all.\n\n1: Shared locks will be used.\n\n2: Exclusive locks will be used.\n\nBut see KNOWN BUGS below.\n\nflockfile\nIf you wish to use a lockfile extension other than \".lck\", simply specify the \"flockfile\"\nattribute:\n\n$dbh = DBI->connect (\"dbi:DBM:flockfile=.foo\");\n$dbh->{flockfile} = \".foo\";\n$dbh->{dbmtables}{qux}{flockfile} = \".foo\";\n\nIf you wish to disable locking, set the \"flockfile\" to 0.\n\n$dbh = DBI->connect (\"dbi:DBM:flockfile=0\");\n$dbh->{flockfile} = 0;\n$dbh->{dbmtables}{qux}{flockfile} = 0;\n\nfencoding\nWith this attribute, you can set the encoding in which the file is opened. This is implemented\nusing \"binmode $fh, \":encoding(<fencoding>)\"\".\n\nfmeta\nPrivate data area aliasing \"sqlmeta\" in DBI::DBD::SqlEngine which contains information about\nthe tables this module handles. Table meta data might not be available until the table has been\naccessed for the first time e.g., by issuing a select on it however it is possible to\npre-initialize attributes for each table you use.\n\nDBD::File recognizes the (public) attributes \"fext\", \"fdir\", \"ffile\", \"fencoding\", \"flock\",\n\"flockfile\", \"fschema\", in addition to the attributes \"sqlmeta\" in DBI::DBD::SqlEngine\nalready supports. Be very careful when modifying attributes you do not know, the consequence\nmight be a destroyed or corrupted table.\n\n\"ffile\" is an attribute applicable to table meta data only and you will not find a\ncorresponding attribute in the dbh. Whilst it may be reasonable to have several tables with the\nsame column names, it is not for the same file name. If you need access to the same file using\ndifferent table names, use \"SQL::Statement\" as the SQL engine and the \"AS\" keyword:\n\nSELECT * FROM tbl AS t1, tbl AS t2 WHERE t1.id = t2.id\n\n\"ffile\" can be an absolute path name or a relative path name but if it is relative, it is\ninterpreted as being relative to the \"fdir\" attribute of the table meta data. When \"ffile\" is\nset DBD::File will use \"ffile\" as specified and will not attempt to work out an alternative for\n\"ffile\" using the \"table name\" and \"fext\" attribute.\n\nWhile \"fmeta\" is a private and readonly attribute (which means, you cannot modify it's values),\nderived drivers might provide restricted write access through another attribute. Well known\naccessors are \"csvtables\" for DBD::CSV, \"adtables\" for DBD::AnyData and \"dbmtables\" for\nDBD::DBM.\n\nNew opportunities for attributes from DBI::DBD::SqlEngine\nsqltablesource\n\"$dbh->{sqltablesource}\" can be set to *DBD::File::TableSource::FileSystem* (and is the\ndefault setting of DBD::File). This provides usual behaviour of previous DBD::File releases on\n\n@ary = DBI->datasources ($driver);\n@ary = DBI->datasources ($driver, \\%attr);\n\n@ary = $dbh->datasources ();\n@ary = $dbh->datasources (\\%attr);\n\n@names = $dbh->tables ($catalog, $schema, $table, $type);\n\n$sth = $dbh->tableinfo ($catalog, $schema, $table, $type);\n$sth = $dbh->tableinfo ($catalog, $schema, $table, $type, \\%attr);\n\n$dbh->func (\"listtables\");\n\nsqldatasource\n\"$dbh->{sqldatasource}\" can be set to either *DBD::File::DataSource::File*, which is default\nand provides the well known behavior of DBD::File releases prior to 0.41, or\n*DBD::File::DataSource::Stream*, which reuses already opened file-handle for operations.\n\nInternally private attributes to deal with SQL backends\nDo not modify any of these private attributes unless you understand the implications of doing\nso. The behavior of DBD::File and derived DBDs might be unpredictable when one or more of those\nattributes are modified.\n\nsqlnanoversion\nContains the version of loaded DBI::SQL::Nano.\n\nsqlstatementversion\nContains the version of loaded SQL::Statement.\n\nsqlhandler\nContains either the text 'SQL::Statement' or 'DBI::SQL::Nano'.\n\nsqlramtables\nContains optionally temporary tables.\n\nsqlflags\nContains optional flags to instantiate the SQL::Parser parsing engine when SQL::Statement is\nused as SQL engine. See SQL::Parser for valid flags.\n"
                },
                {
                    "name": "Driver private methods",
                    "content": "Default DBI methods\ndatasources\nThe \"datasources\" method returns a list of subdirectories of the current directory in the form\n\"dbi:CSV:fdir=$dirname\".\n\nIf you want to read the subdirectories of another directory, use\n\nmy ($drh)  = DBI->installdriver (\"CSV\");\nmy (@list) = $drh->datasources (fdir => \"/usr/local/csvdata\");\n\nAdditional methods\nThe following methods are only available via their documented name when DBD::File is used\ndirectly. Because this is only reasonable for testing purposes, the real names must be used\ninstead. Those names can be computed by replacing the \"f\" in the method name with the driver\nprefix.\n\nfversions\nSignature:\n\nsub fversions (;$)\n{\nmy ($tablename) = @;\n$tablename ||= \".\";\n...\n}\n\nReturns the versions of the driver, including the DBI version, the Perl version, DBI::PurePerl\nversion (if DBI::PurePerl is active) and the version of the SQL engine in use.\n\nmy $dbh = DBI->connect (\"dbi:File:\");\nmy $fversions = $dbh->func (\"fversions\");\nprint \"$fversions\\n\";\nEND\n# DBD::File              0.41 using IO::File (1.16)\n#   DBI::DBD::SqlEngine  0.05 using SQL::Statement 1.406\n# DBI                    1.623\n# OS                     darwin (12.2.1)\n# Perl                   5.017006 (darwin-thread-multi-ld-2level)\n\nCalled in list context, fversions will return an array containing each line as single entry.\n\nSome drivers might use the optional (table name) argument and modify version information related\nto the table (e.g. DBD::DBM provides storage backend information for the requested table, when\nit has a table name).\n"
                }
            ]
        },
        "KNOWN BUGS AND LIMITATIONS": {
            "content": "*   This module uses flock () internally but flock is not available on all platforms. On MacOS\nand Windows 95 there is no locking at all (perhaps not so important on MacOS and Windows 95,\nas there is only a single user).\n\n*   The module stores details about the handled tables in a private area of the driver handle\n($drh). This data area is not shared between different driver instances, so several\n\"DBI->connect ()\" calls will cause different table instances and private data areas.\n\nThis data area is filled for the first time when a table is accessed, either via an SQL\nstatement or via \"tableinfo\" and is not destroyed until the table is dropped or the driver\nhandle is released. Manual destruction is possible via fclearmeta.\n\nThe following attributes are preserved in the data area and will evaluated instead of driver\nglobals:\n\nfext\nfdir\nfdirsearch\nflock\nflockfile\nfencoding\nfschema\ncolnames\nsqlidentifiercase\n\nThe following attributes are preserved in the data area only and cannot be set globally.\n\nffile\n\nThe following attributes are preserved in the data area only and are computed when\ninitializing the data area:\n\nffqfn\nffqbn\nffqln\ntablename\n\nFor DBD::CSV tables this means, once opened \"foo.csv\" as table named \"foo\", another table\nnamed \"foo\" accessing the file \"foo.txt\" cannot be opened. Accessing \"foo\" will always\naccess the file \"foo.csv\" in memorized \"fdir\", locking \"flockfile\" via memorized \"flock\".\n\nYou can use fclearmeta or the \"ffile\" attribute for a specific table to work around this.\n\n*   When used with SQL::Statement and temporary tables e.g.,\n\nCREATE TEMP TABLE ...\n\nthe table data processing bypasses DBD::File::Table. No file system calls will be made and\nthere are no clashes with existing (file based) tables with the same name. Temporary tables\nare chosen over file tables, but they will not covered by \"tableinfo\".\n",
            "subsections": []
        },
        "AUTHOR": {
            "content": "This module is currently maintained by\n\nH.Merijn Brand < h.m.brand at xs4all.nl > and Jens Rehsack < rehsack at googlemail.com >\n\nThe original author is Jochen Wiedmann.\n",
            "subsections": []
        },
        "COPYRIGHT AND LICENSE": {
            "content": "Copyright (C) 2009-2013 by H.Merijn Brand & Jens Rehsack\nCopyright (C) 2004-2009 by Jeff Zucker\nCopyright (C) 1998-2004 by Jochen Wiedmann\n\nAll rights reserved.\n\nYou may freely distribute and/or modify this module under the terms of either the GNU General\nPublic License (GPL) or the Artistic License, as specified in the Perl README file.\n",
            "subsections": []
        },
        "SEE ALSO": {
            "content": "DBI, DBD::DBM, DBD::CSV, Text::CSV, Text::CSVXS, SQL::Statement, and DBI::SQL::Nano\n",
            "subsections": []
        }
    },
    "summary": "DBD::File - Base class for writing file based DBI drivers",
    "flags": [],
    "examples": [],
    "see_also": []
}