view release on metacpan or  search on metacpan

lib/DBD/DBM.pm  view on Meta::CPAN

If your DBM type uses an extension other than one of the recognized
types of extensions, you should set the I<f_ext> attribute to the
extension B<and> file a bug report as described in DBI with the name
of the implementation and extension so we can add it to DBD::DBM.
Thanks in advance for that :-).

  $dbh = DBI->connect('dbi:DBM:f_ext=.db');  # .db extension is used
  $dbh = DBI->connect('dbi:DBM:f_ext=');     # no extension is used

  # or
  $dbh->{f_ext}='.db';                       # global setting
  $dbh->{f_meta}->{'qux'}->{f_ext}='.db';    # setting for table 'qux'

By default files are assumed to be in the current working directory.
To use other directories specify the I<f_dir> attribute in either the
connect string or by setting the database handle attribute.

For example, this will look for the file /foo/bar/fruit (or
/foo/bar/fruit.pag for DBM types that use that extension)

  my $dbh = DBI->connect('dbi:DBM:f_dir=/foo/bar');
  # and this will too:
  my $dbh = DBI->connect('dbi:DBM:');
  $dbh->{f_dir} = '/foo/bar';
  # but this is recommended
  my $dbh = DBI->connect('dbi:DBM:', undef, undef, { f_dir => '/foo/bar' } );

  # now you can do
  my $ary = $dbh->selectall_arrayref(q{ SELECT x FROM fruit });

You can also use delimited identifiers to specify paths directly in SQL
statements.  This looks in the same place as the two examples above but
without setting I<f_dir>:

   my $dbh = DBI->connect('dbi:DBM:');
   my $ary = $dbh->selectall_arrayref(q{
       SELECT x FROM "/foo/bar/fruit"
   });

You can also tell DBD::DBM to use a specified path for a specific table:

  $dbh->{dbm_tables}->{f}->{file} = q(/foo/bar/fruit);

Please be aware that you cannot specify this during connection.

If you have SQL::Statement installed, you can use table aliases:

   my $dbh = DBI->connect('dbi:DBM:');
   my $ary = $dbh->selectall_arrayref(q{
       SELECT f.x FROM "/foo/bar/fruit" AS f
   });

See the L<GOTCHAS AND WARNINGS> for using DROP on tables.

=head2 Table locking and flock()

Table locking is accomplished using a lockfile which has the same
basename as the table's file but with the file extension '.lck' (or a
lockfile extension that you supply, see below).  This lock file is
created with the table during a CREATE and removed during a DROP.
Every time the table itself is opened, the lockfile is flocked().  For
SELECT, this is a shared lock.  For all other operations, it is an
exclusive lock (except when you specify something different using the
I<f_lock> attribute).

Since the locking depends on flock(), it only works on operating
systems that support flock().  In cases where flock() is not
implemented, DBD::DBM will simply behave as if the flock() had
occurred although no actual locking will happen.  Read the
documentation for flock() for more information.

Even on those systems that do support flock(), locking is only
advisory - as is always the case with flock().  This means that if
another program tries to access the table file while DBD::DBM has the
table locked, that other program will *succeed* at opening unless
it is also using flock on the '.lck' file.  As a result DBD::DBM's
locking only really applies to other programs using DBD::DBM or other
program written to cooperate with DBD::DBM locking.

=head2 Specifying the DBM type

Each "flavor" of DBM stores its files in a different format and has
different capabilities and limitations. See L<AnyDBM_File> for a
comparison of DBM types.

By default, DBD::DBM uses the C<< SDBM_File >> type of storage since
C<< SDBM_File >> comes with Perl itself. If you have other types of
DBM storage available, you can use any of them with DBD::DBM. It is
strongly recommended to use at least C<< DB_File >>, because C<<
SDBM_File >> has quirks and limitations and C<< ODBM_file >>, C<<
NDBM_File >> and C<< GDBM_File >> are not always available.

You can specify the DBM type using the I<dbm_type> attribute which can
be set in the connection string or with C<< $dbh->{dbm_type} >> and
C<< $dbh->{f_meta}->{$table_name}->{type} >> for per-table settings in
cases where a single script is accessing more than one kind of DBM
file.

In the connection string, just set C<< dbm_type=TYPENAME >> where
C<< TYPENAME >> is any DBM type such as GDBM_File, DB_File, etc. Do I<not>
use MLDBM as your I<dbm_type> as that is set differently, see below.

 my $dbh=DBI->connect('dbi:DBM:');                # uses the default SDBM_File
 my $dbh=DBI->connect('dbi:DBM:dbm_type=GDBM_File'); # uses the GDBM_File

 # You can also use $dbh->{dbm_type} to set the DBM type for the connection:
 $dbh->{dbm_type} = 'DB_File';    # set the global DBM type
 print $dbh->{dbm_type};          # display the global DBM type

If you have several tables in your script that use different DBM
types, you can use the $dbh->{dbm_tables} hash to store different
settings for the various tables.  You can even use this to perform
joins on files that have completely different storage mechanisms.

 # sets global default of GDBM_File
 my $dbh->('dbi:DBM:type=GDBM_File');

 # overrides the global setting, but only for the tables called
 # I<foo> and I<bar>
 my $dbh->{f_meta}->{foo}->{dbm_type} = 'DB_File';
 my $dbh->{f_meta}->{bar}->{dbm_type} = 'BerkeleyDB';

 # prints the dbm_type for the table "foo"
 print $dbh->{f_meta}->{foo}->{dbm_type};

B<Note> that you must change the I<dbm_type> of a table before you access
it for first time.

=head2 Adding multi-column support with MLDBM

Most of the DBM types only support two columns and even if it would
support more, DBD::DBM would only use two. However a CPAN module
called MLDBM overcomes this limitation by allowing more than two
columns.  MLDBM does this by serializing the data - basically it puts
a reference to an array into the second column. It can also put almost