class BDB::Env

Berkeley DB environment is an encapsulation of one or more databases, log files and shared information about the database environment such as shared memory buffer cache pages.

The simplest way to administer a Berkeley DB application environment is to create a single home directory that stores the files for the applications that will share the environment. The environment home directory must be created before any Berkeley DB applications are run. Berkeley DB itself never creates the environment home directory. The environment can then be identified by the name of that directory.

Public Class Methods

create(home, flags = 0, mode = 0, options = {}) click to toggle source

same than open

# File env.rb, line 137
def  create(home, flags = 0, mode = 0, options = {})
end
new(home, flags = 0, mode = 0, options = {}) click to toggle source

same than open

# File env.rb, line 140
def  new(home, flags = 0, mode = 0, options = {})
end
open(home, flags = 0, mode = 0, options = {}) click to toggle source

open the Berkeley DB environment

  • home If this argument is non-NULL, its value may be used as the database home, and files named relative to its path.

  • mode mode for creation (see chmod(2))

  • flags must be set to 0 or by OR'ing with

    • BDB::INIT_CDB Initialize locking.

    • BDB::INIT_LOCK Initialize the locking subsystem.

    • BDB::INIT_LOG Initialize the logging subsystem.

    • BDB::INIT_MPOOL Initialize the shared memory buffer pool subsystem.

    • BDB::INIT_TXN Initialize the transaction subsystem.

    • BDB::INIT_TRANSACTION Equivalent to DB_INIT_LOCK|DB_INIT_MPOOL|DB_INIT_TXN|DB_INIT_LOG

    • BDB::RECOVER Run normal recovery on this environment before opening it for normal use. If this flag is set, the DB_CREATE flag must also be set since the regions will be removed and recreated.

    • BDB::RECOVER_FATAL Run catastrophic recovery on this environment before opening it for normal use. If this flag is set, the DB_CREATE flag must also be set since the regions will be removed and recreated.

    • BDB::USE_ENVIRON The Berkeley DB process' environment may be permitted to specify information to be used when naming files

    • BDB::USE_ENVIRON_ROOT The Berkeley DB process' environment may be permitted to specify information to be used when naming files; if the DB_USE_ENVIRON_ROOT flag is set, environment information will be used for file naming only for users with appropriate permissions

    • BDB::CREATE Cause Berkeley DB subsystems to create any underlying files, as necessary.

    • BDB::LOCKDOWN Lock shared Berkeley DB environment files and memory mapped databases into memory.

    • BDB::NOMMAP Always copy read-only database files in this environment into the local cache instead of potentially mapping them into process memory

    • BDB::PRIVATE Specify that the environment will only be accessed by a single process

    • BDB::SYSTEM_MEM Allocate memory from system shared memory instead of from memory backed by the filesystem.

    • BDB::TXN_NOSYNC Do not synchronously flush the log on transaction commit or prepare. This means that transactions exhibit the ACI (atomicity, consistency and isolation) properties, but not D (durability), i.e., database integrity will be maintained but it is possible that some number of the most recently committed transactions may be undone during recovery instead of being redone.

    • BDB::CDB_ALLDB For Berkeley DB Concurrent Data Store applications, perform locking on an environment-wide basis rather than per-database.

  • options Hash, Possible options are (see the documentation of Berkeley DB for more informations)

    • set_app_dispatch : configure application recovery interface (DB >= 4.1)

    • set_cachesize : set the database cache size

    • set_data_dir : set the environment data directory (DB >= 3)

    • set_encrypt : set the environment cryptographic key (DB >= 4.1)

    • set_feedback : set feedback callback (DB >= 3)

    • set_flags : environment configuration (DB >= 3.2)

    • set_lg_bsize : set log buffer size (DB >= 3)

    • set_lg_dir : set the environment logging directory (DB >= 3)

    • set_lg_max : set log file size

    • set_lg_regionmax : set logging region size (DB >= 3)

    • set_lk_conflicts : set lock conflicts matrix (DB >= 3)

    • set_lk_detect : set automatic deadlock detection

    • set_lk_max_lockers : set maximum number of lockers

    • set_lk_max_locks : set maximum number of locks

    • set_lk_max_objects : set maximum number of lock objects

    • set_rep_transport : configure replication transport (DB >= 4)

    • set_rep_limit : limit data sent in response to a single message (DB >= 4.1)

    • set_rep_nsites : configure replication group site count (DB >= 4.5)

    • set_rep_priority : configure replication site priority (DB >= 4.5)

    • set_rep_config : configure the replication subsystem (DB >= 4.5)

    • set_rep_timeout : configure replication timeouts (DB >= 4.5)

    • set_rpc_server : establish an RPC server connection (DB >= 3.1)

    • set_tas_spins : set the number of test-and-set spins (DB >= 3)

    • set_tmp_dir : set the environment temporary file directory (DB >= 3)

    • set_timeout : set lock and transaction timeout (DB >= 4)

    • set_tx_max : set maximum number of transactions (DB >= 3)

    • set_tx_timestamp : set recovery timestamp (DB >= 3.1)

    • set_verbose : set verbose messages

    • set_verb_chkpoint :display checkpoint location information when searching the log for checkpoints. (DB >= 3)

    • set_verb_deadlock : display additional information when doing deadlock detection. (DB >= 3)

    • set_verb_recovery : display additional information when performing recovery. (DB >= 3)

    • set_verb_replication : display additional information when processing replication messages. (DB >= 4)

    • set_verb_waitsfor : display the waits-for table when doing deadlock detection. (DB >= 3)

    Proc given to set_feedback, set_app_dispatch and set_rep_transport can be also specified as a method (replace the prefix set_ with bdb_)

    For bdb_rep_transport the constant ENVID must be defined

    The constant BDB::ENCRYPT can be used to replace set_encrypt

# File env.rb, line 134
def  open(home, flags = 0, mode = 0, options = {})
end
remove() click to toggle source

remove the environnement

# File env.rb, line 145
def  remove()
end

Public Instance Methods

begin(flags = 0) click to toggle source

begin a transaction (the transaction manager must be enabled). flags can have the value DBD::TXN_COMMIT, in this case the transaction will be commited at end.

# File env.rb, line 325
def  begin(flags = 0)
end
checkpoint(kbyte, min = 0) click to toggle source

The #txn_checkpoint function flushes the underlying memory pool, writes a checkpoint record to the log and then flushes the log.

If either kbyte or min is non-zero, the checkpoint is only done if more than min minutes have passed since the last checkpoint, or if more than kbyte kilobytes of log data have been written since the last checkpoint.

# File env.rb, line 339
def  checkpoint(kbyte, min = 0)
end
close() click to toggle source

close the environnement

# File env.rb, line 154
def  close()
end
dbremove(file, database = nil, flags = 0) click to toggle source

only with BDB::VERSION_MAJOR == 4 && BDB::VERSION_MINOR >= 1

remove the database specified by file and database. If no database is nil, the underlying file represented by file is removed, incidentally removing all databases that it contained.

The flags value must be set to 0 or BDB::AUTO_COMMIT

# File env.rb, line 166
def  dbremove(file, database = nil, flags = 0)
end
dbrename(file, database, newname, flags = 0) click to toggle source

only with BDB::VERSION_MAJOR == 4 && BDB::VERSION_MINOR >= 1

rename the database specified by file and database to newname. If database is nil, the underlying file represented by file is renamed, incidentally renaming all databases that it contained.

The flags value must be set to 0 or BDB::AUTO_COMMIT

# File env.rb, line 178
def  dbrename(file, database, newname, flags = 0)
end
elect(sites, priority, timeout) click to toggle source

Only for DB >= 4

Holds an election for the master of a replication group, returning the new master's ID

Raise BDB::RepUnavail if the timeout expires

# File env.rb, line 361
def  elect(sites, priority, timeout)
end
failcheck(flag = 0) click to toggle source

Only for DB >= 4.4

The method checks for threads of control (either a true thread or a process) that have exited while manipulating Berkeley DB library data structures

flag is actually unused and must be set to 0

# File env.rb, line 467
def failcheck(flag = 0)
end
feedback=(proc) click to toggle source

monitor the progress of some operations

# File env.rb, line 183
def  feedback=(proc)
end
fileid_reset(file, flags = 0) click to toggle source

Only for DB >= 4.4

Reset database file ID

The #fileid_reset method allows database files to be copied, and then the copy used in the same database environment as the original.

fileThe name of the physical file in which new file IDs are to be created. flags must be set to 0 or BDB::ENCRYPT

# File env.rb, line 413
def fileid_reset(file, flags = 0)
end
home() click to toggle source

return the name of the directory

# File env.rb, line 188
def  home()
end
is_alive=(call_proc) click to toggle source

Only for DB >= 4.4

Declare a proc that returns if a thread of control (either a true thread or a process) is still running.

The proc will be called with 2 arguments (pid, tid)

# File env.rb, line 456
def is_alive=(call_proc)
end
lock() click to toggle source

Acquire a locker ID

# File env.rb, line 193
def  lock()
end
lock_detect(type, flags = 0) click to toggle source

The #lock_detect function runs one iteration of the deadlock detector. The deadlock detector traverses the lock table, and for each deadlock it finds, marks one of the participating transactions for abort.

type can have one the value BDB::LOCK_OLDEST, BDB::LOCK_RANDOM or BDB::LOCK_YOUNGUEST

flags can have the value BDB::LOCK_CONFLICT, in this case the deadlock detector is run only if a lock conflict has occurred since the last time that the deadlock detector was run.

return the number of transactions aborted by the #lock_detect function if BDB::VERSION_MAJOR >= 3 or zero

# File env.rb, line 214
def  lock_detect(type, flags = 0)
end
lock_id() click to toggle source

same than lock

# File env.rb, line 196
def  lock_id()
end
lock_stat() click to toggle source

Return lock subsystem statistics

# File env.rb, line 220
def  lock_stat()
end
log_archive(flags = 0) click to toggle source

The #log_archive function return an array of log or database file names.

flags value must be set to 0 or the value BDB::ARCH_DATA, BDB::ARCH_ABS, BDB::ARCH_LOG

# File env.rb, line 228
def  log_archive(flags = 0)
end
log_checkpoint(string) click to toggle source

same as log_put(string, BDB::CHECKPOINT)

# File env.rb, line 234
def  log_checkpoint(string)
end
log_curlsn(string) click to toggle source

same as log_put(string, BDB::CURLSN)

# File env.rb, line 240
def  log_curlsn(string)
end
log_each() { |string, lsn| ... } click to toggle source

Implement an iterator inside of the log

# File env.rb, line 246
def  log_each 
   yield string, lsn
end
log_flush(string = nil) click to toggle source

same as log_put(string, BDB::FLUSH)

Without argument, garantee that all records are written to the disk

# File env.rb, line 255
def  log_flush(string = nil)
end
log_get(flag) click to toggle source

The log_get return an array [String, BDB::Lsn] according to the flag value.

flag can has the value BDB::CHECKPOINT, BDB::FIRST, BDB::LAST, BDB::NEXT, BDB::PREV, BDB::CURRENT

# File env.rb, line 265
def  log_get(flag)
end
log_put(string, flag = 0) click to toggle source

The log_put function appends records to the log. It return an object BDB::Lsn

flag can have the value BDB::CHECKPOINT, BDB::CURLSN, BDB::FLUSH

# File env.rb, line 275
def  log_put(string, flag = 0)
end
log_reverse_each() { |string, lsn| ... } click to toggle source

Implement an iterator inside of the log

# File env.rb, line 281
def  log_reverse_each 
   yield string, lsn
end
log_stat() click to toggle source

return log statistics

# File env.rb, line 288
def  log_stat
end
lsn_reset(file, flags = 0) click to toggle source

Only for DB >= 4.4

Reset database file LSN

The #lsn_reset method allows database files to be moved from one transactional database environment to another.

fileThe name of the physical file in which the LSNs are to be cleared. flags must be set to 0 or BDB::ENCRYPT

# File env.rb, line 400
def lsn_reset(file, flags = 0)
end
msgcall=(call_proc) click to toggle source

Only for DB >= 4.4

There are interfaces in the Berkeley DB library which either directly output informational messages or statistical information : Env#msgcall is used to set callback which will called by BDB

The value given must be nil to unconfigure the callback, or and object which respond to #call : it will called with a String as argument

# File env.rb, line 425
def msgcall=(call_proc)
end
open_db(type, name = nil, subname = nil, flags = 0, mode = 0) click to toggle source

open the database in the current environment. type must be one of the constant BDB::BTREE, BDB::HASH, BDB::RECNO, BDB::QUEUE. See open for other arguments

# File env.rb, line 296
def  open_db(type, name = nil, subname = nil, flags = 0, mode = 0)
end
process_message(control, rec, envid) click to toggle source

Only for DB >= 4

Processes an incoming replication message sent by a member of the replication group to the local database environment

# File env.rb, line 372
def  process_message(control, rec, envid)
end
recover() { |txn, id| ... } click to toggle source

only with BDB::VERSION_MAJOR == 3 && BDB::VERSION_MINOR >= 3

iterate over all prepared transactions. The transaction txn must be made a call to abort, commit, discard

id is the global transaction ID for the transaction

# File env.rb, line 306
def  recover 
   yield txn, id
end
rep_config([]=(which, onoff)) click to toggle source

Only for DB >= 4.5

Configures the Berkeley DB replication subsystem.

which can have the value BDB::REP_CONF_BULK, BDB::REP_CONF_DELAYCLIENT, BDB::REP_CONF_NOAUTOINIT, BDB::REP_CONF_NOWAIT

onoff can have the value true or false

# File env.rb, line 524
def rep_config[]=(which, onoff)
end
rep_config?([](which)) click to toggle source

Only for DB >= 4.5

Returns true if the specified which parameter is currently set or not.

# File env.rb, line 530
def rep_config?[](which)
end
rep_elect(sites, priority, timeout) click to toggle source

same than elect

# File env.rb, line 364
def  rep_elect(sites, priority, timeout)
end
rep_nsites() click to toggle source

Only for DB >= 4.5

Returns the total number of sites in a replication group.

# File env.rb, line 542
def rep_nsites
end
rep_nsites=(sites) click to toggle source

Only for DB >= 4.5

Specifies the total number of sites in a replication group.

# File env.rb, line 536
def rep_nsites=(sites)
end
rep_priority() click to toggle source

Only for DB >= 4.5

Returns the database environment priority.

# File env.rb, line 554
def rep_priority
end
rep_priority=(priority) click to toggle source

Only for DB >= 4.5

Specifies the priority in the replication group elections.

# File env.rb, line 548
def rep_priority=(priority)
end
rep_process_message(control, rec, envid) click to toggle source

same than #process_message

# File env.rb, line 375
def  rep_process_message(control, rec, envid)
end
rep_start(cdata, flags) click to toggle source

same than start

# File env.rb, line 387
def  rep_start(cdata, flags)
end
rep_timeout([]=(which, timeout)) click to toggle source

Only for DB >= 4.5

Specifies the timeout in the replication group elections.

which can have the value BDB::REP_ACK_TIMEOUT, BDB::REP_ELECTION_TIMEOUT, BDB::REP_ELECTION_RETRY, BDB::REP_CONNECTION_RETRY

# File env.rb, line 564
def rep_timeout[]=(which, timeout)
end
repmgr_ack_policy() click to toggle source

Only for DB >= 4.5

Returns the replication manager's client acknowledgment policy.

# File env.rb, line 493
def repmgr_ack_policy
end
repmgr_ack_policy=(policy) click to toggle source

Only for DB >= 4.5

Specifies how master and client sites will handle acknowledgment of replication messages which are necessary for “permanent” records.

policy must be set to one of the following values BDB::REPMGR_ACKS_ALL, BDB::REPMGR_ACKS_ALL_PEERS, BDB::REPMGR_ACKS_NONE, BDB::REPMGR_ACKS_ONE, BDB::REPMGR_ACKS_ONE_PEER, BDB::REPMGR_ACKS_QUORUM

# File env.rb, line 487
def repmgr_ack_policy=(policy)
end
repmgr_add_remote(host, port, flag = 0) click to toggle source

Only for DB >= 4.5

Adds a new replication site to the replication manager's list of known sites.

Return the environment ID assigned to the remote site

# File env.rb, line 475
def repmgr_add_remote(host, port, flag = 0)
end
repmgr_set_local_site(host, port, flag = 0) click to toggle source

Only for DB >= 4.5

Specifies the host identification string and port number for the local system.

# File env.rb, line 506
def repmgr_set_local_site(host, port, flag = 0)
end
repmgr_site_list() click to toggle source

Only for DB >= 4.5

Returns an array with the status of the sites currently known by the replication manager.

# File env.rb, line 500
def repmgr_site_list
end
repmgr_start(count, flag) click to toggle source

Only for DB >= 4.5

Starts the replication manager.

# File env.rb, line 512
def repmgr_start(count, flag)
end
set_flags(flags, onoff = true) click to toggle source

only with BDB::VERSION_MAJOR == 3 && BDB::VERSION_MINOR >= 2

flags can have the value BDB::CDB_ALLDB, BDB::NOMMAP BDB::TXN_NOSYNC

if onoff is false, the specified flags are cleared

# File env.rb, line 318
def  set_flags(flags, onoff = true) 
end
start(cdata, flags) click to toggle source

Only for DB >= 4

cdata is an identifier flags must be one of BDB::REP_CLIENT, BDB::REP_MASTER or BDB::REP_LOGSONLY

# File env.rb, line 384
def  start(cdata, flags)
end
stat() click to toggle source

Return transaction subsystem statistics

# File env.rb, line 348
def  stat()
end
thread_id=(call_proc) click to toggle source

Only for DB >= 4.4

Declare a proc object which returns a unique identifier pair for the current thread of control.

The proc must return a pair

*<em>pid</em>: process ID of the current thread
*<em>tid</em>: thread ID of the current thread
# File env.rb, line 437
def thread_id=(call_proc)
end
thread_id_string=(call_proc) click to toggle source

Only for DB >= 4.4

Declare a proc that formats a process ID and thread ID identifier pair for display.

The proc will be called with 2 arguments and must return a String

# File env.rb, line 446
def thread_id_string=(call_proc)
end
txn_begin(flags = 0) click to toggle source

same than begin

# File env.rb, line 328
def  txn_begin(flags = 0)
end
txn_checkpoint(kbyte, min = 0) click to toggle source

same than checkpoint

# File env.rb, line 342
def  txn_checkpoint(kbyte, min = 0)
end
txn_stat() click to toggle source

same than stat

# File env.rb, line 351
def  txn_stat()
end