Digital Mages - Paranoid::BerkeleyDB::Env(3)

Paranoid::BerkeleyDB::Env

Section: User Contributed Perl Documentation (3)
Updated: 2022-03-08
Index

NAME

Paranoid::BerkeleyDB::Env -- BerkeleyDB CDS Env Object

VERSION

$Id: lib/Paranoid/BerkeleyDB/Env.pm, 2.06 2022/03/08 22:26:06 acorliss Exp $

SYNOPSIS

  $db = Paranoid::BerkeleyDB::Env->new(-Home => './dbdir');

  $home   = $dbe->home;
  %params = $dbe->params;
  $count  = $dbe->refc;
  $env    = $dbe->env;
  @dbs    = $dbe->dbs;

DESCRIPTION

This module provides an OO-based wrapper for the BerkeleyDB::Env(3) class with the standard Paranoid(3) API integration. This class supports all of the standard parameters that BerkeleyDB::Env(3) does.

If you're using the Paranoid::BerkeleyDB(3) API this object is created for you automatically. There is probably no value in using this module directly unless you need to tune BerkeleyDB::Btree's defaults.

While this class places no restrictions on the use of any available BerkeleyDB::Env(3) options it does automatically deploy some defaults options oriented towards CDS access. These can be overridden, but if you're focused on CDS this will simplify their use.

SUBROUTINES/METHODS

new

  $db = Paranoid::BerkeleyDB::Env->new(-Home => './dbdir');

The only required argument is -Home. For a complete list of all available options please see the BerkeleyDB(3) man page.

By default the following settings are applied unless overridden:

    Parameter   Value
    ---------------------------------------------------
    -Flags      DB_CREATE | DB_INIT_CDB | DB_INIT_MPOOL
    -ErrFile    {-Home}/db_err.log
    -Verbose    1

home

    $home = $dbe->home;

This method returns the canonical path to the environment's home directory.

params

    %params = $dbe->params;

This method returns the assembled parameters hash used to open the BerkeleyDB::Env object.

refc

    $count = $dbe->refc;

This method returns the current number of references to the underlying environment object. That count is essentially the number of objects all using the same environment.

env

  $env = $dbe->env;

This returns a handle to the current BerkeleyDB::Env(3) object.

DESTROY

A DESTROY method is provided which should sync and close an open database, as well as release any locks.

DEPENDENCIES

o: BerkeleyDB
o: Class::EHierarchy
o: Fcntl
o: Paranoid
o: Paranoid::Debug
o: Paranoid::Input
o: Paranoid::IO
o: Paranoid::IO::Lockfile

BUGS AND LIMITATIONS

Race conditions, particularly on environment creation/opens, are worked around by the use of external lock files and flock advisory file locks. Lockfiles are not used during normal operations on the environment.

While CDS allows for safe concurrent use of database files, it makes no allowances for recovery from stale locks. If a process exits badly and fails to release a write lock (which causes all other process operations to block indefinitely) you have to intervene manually. The brute force intervention would mean killing all accessing processes and deleting the environment files (files in the same directory call __db.*). Those will be recreated by the next process to access them.

Berkeley DB provides a handy CLI utility called db_stat(1). It can provide some statistics on your shared database environment via invocation like so:

  db_stat -m -h .

The last argument, of course, is the directory in which the environment was created. The example above would work fine if your working directory was that directory.

You can also show all existing locks via: