Read Oracle documentation for better understanding.
database home directory (read-only)
Returns the memory pool (that is, the buffer cache) subsystem statistics.
The returning value is a tuple. The first element is a dictionary with the general stats. The second element is another dictionary, keyed by filename, and the values are the stats for each file.
The first dictionary contains these data:
Gigabytes of cache (total cache size is st_gbytes + st_bytes).
Bytes of cache (total cache size is st_gbytes + st_bytes).
Number of caches.
Maximum number of caches, as configured with the DB_ENV->set_cache_max() method.
Individual cache size, in bytes.
Maximum memory-mapped file size.
Maximum open file descriptors.
Maximum sequential buffer writes.
Microseconds to pause after writing maximum sequential buffers.
Requested pages mapped into the process’ address space (there is no available information about whether or not this request caused disk I/O, although examining the application page fault rate may be helpful).
Requested pages found in the cache.
Requested pages not found in the cache.
Pages created in the cache.
Pages read into the cache.
Pages written from the cache to the backing file.
Clean pages forced from the cache.
Dirty pages forced from the cache.
Dirty pages written using the DB_ENV->memp_trickle() method.
Pages in the cache.
Clean pages currently in the cache.
Dirty pages currently in the cache.
Number of hash buckets in buffer hash table.
Total number of buffer hash table lookups.
Longest chain ever encountered in buffer hash table lookups.
Total number of hash elements traversed during hash table lookups.
Number of times that a thread of control was able to obtain a hash bucket lock without waiting.
Number of times that a thread of control was forced to wait before obtaining a hash bucket lock.
The number of times a thread of control was able to obtain the hash bucket lock without waiting on the bucket which had the maximum number of times that a thread of control needed to wait.
Maximum number of times any hash bucket lock was waited for by a thread of control.
Number of times that a thread of control was forced to wait before obtaining a cache region mutex.
Number of times that a thread of control was able to obtain a cache region mutex without waiting.
Number of buffers frozen.
Number of buffers thawed.
Number of frozen buffers freed.
Number of page allocations.
Number of hash buckets checked during allocation.
Maximum number of hash buckets checked during an allocation.
Number of pages checked during allocation.
Maximum number of pages checked during an allocation.
Number of operations blocked waiting for I/O to complete.
Number of mpool sync operations interrupted.
The second dictionary contains these data:
Page size in bytes.
Requested pages found in the cache.
Requested pages not found in the cache.
Requested pages mapped into the process’ address space.
Pages created in the cache.
Pages read into the cache.
Pages written from the cache to the backing file.
Flushes modified pages in the cache to their backing files. If provided, lsn is a tuple: (file, offset). More info…
Ensures that a specified percent of the pages in the cache are clean, by writing dirty pages to their backing files. More info…
- dbremove(file, database=None, txn=None, flags=0)¶
Removes the database specified by the file and database parameters. If no database is specified, the underlying file represented by file is removed, incidentally removing all of the databases it contained. More info…
- dbrename(file, database=None, newname, txn=None, flags=0)¶
Renames the database specified by the file and database parameters to newname. If no database is specified, the underlying file represented by file is renamed, incidentally renaming all of the databases it contained. More info…
- dbbackup(dbfile, target=None, flags=0)¶
Performs a hot backup of a single database file contained within the environment. More info…
- fileid_reset(file, flags=0)¶
All databases contain an ID string used to identify the database in the database environment cache. If a physical database file is copied, and used in the same environment as another file with the same ID strings, corruption can occur. The DB_ENV->fileid_reset method creates new ID strings for all of the databases in the physical file. More info…
Returns the thread count as set by the DB_ENV->set_thread_count() method. More info…
Declare an approximate number of threads in the database environment. The DB_ENV->set_thread_count() method must be called prior to opening the database environment if the DB_ENV->failchk() method will be used. The DB_ENV->set_thread_count() method does not set the maximum number of threads but is used to determine memory sizing and the thread control block reclamation policy. More info…
- set_encrypt(passwd, flags=0)¶
Set the password used by the Berkeley DB library to perform encryption and decryption. More info…
Returns the intermediate directory permissions.
Intermediate directories are directories needed for recovery. Normally, Berkeley DB does not create these directories and will do so only if the DB_ENV->set_intermediate_dir_mode() method is called.
By default, Berkeley DB does not create intermediate directories needed for recovery, that is, if the file /a/b/c/mydatabase is being recovered, and the directory path b/c does not exist, recovery will fail. This default behavior is because Berkeley DB does not know what permissions are appropriate for intermediate directory creation, and creating the directory might result in a security problem.
The DB_ENV->set_intermediate_dir_mode() method causes Berkeley DB to create any intermediate directories needed during recovery, using the specified permissions.
- set_timeout(timeout, flags)¶
Sets timeout values for locks or transactions in the database environment. More info…
Returns the maximum number of file descriptors the library will open concurrently when flushing dirty pages from the cache. More info…
Limits the number of file descriptors the library will open concurrently when flushing dirty pages from the cache. More info…
Returns a tuple with the current maximum number of sequential write operations and microseconds to pause that the library can schedule when flushing dirty pages from the cache. More info…
- set_mp_max_write(maxwrite, maxwrite_sleep)¶
Limits the number of sequential write operations scheduled by the library when flushing dirty pages from the cache. More info…
Specify a base segment ID for Berkeley DB environment shared memory regions created in system memory on VxWorks or systems supporting X/Open-style shared memory interfaces; for example, UNIX systems supporting shmget(2) and related System V IPC interfaces. More info…
- set_cache_max(gbytes, bytes)¶
Sets the maximum cache size, in bytes. The specified size is rounded to the nearest multiple of the cache region size, which is the initial cache size divided by the number of regions specified to the DB_ENV->set_cachesize() method. If no value is specified, it defaults to the initial cache size. More info…
Returns the maximum size of the cache as set using the DB_ENV->set_cache_max() method. More info…
Set the environment data directory. You can call this function multiple times, adding new directories. More info…
- set_flags(flags, onoff)¶
Set additional flags for the DBEnv. The onoff parameter specifes if the flag is set or cleared. More info…
By default when DB.get or DBCursor.get, get_both, first, last, next or prev encounter a DB_NOTFOUND error they return None instead of raising DBNotFoundError. This behaviour emulates Python dictionaries and is convenient for looping.
You can use this method to toggle that behaviour for all of the aformentioned methods or extend it to also apply to the DBCursor.set, set_both, set_range, and set_recno methods. Supported values of flag:
0 all DB and DBCursor get and set methods will raise a DBNotFoundError rather than returning None.
1 Default in module version <4.2.4 The DB.get and DBCursor.get, get_both, first, last, next and prev methods return None.
2 Default in module version >=4.2.4 Extends the behaviour of 1 to the DBCursor set, set_both, set_range and set_recno methods.
The default of returning None makes it easy to do things like this without having to catch DBNotFoundError (KeyError):
data = mydb.get(key) if data: doSomething(data)
rec = cursor.first() while rec: print rec rec = cursor.next()
Making the cursor set methods return None is useful in order to do this:
rec = mydb.set() while rec: key, val = rec doSomething(key, val) rec = mydb.next()
The downside to this it that it is inconsistent with the rest of the package and noticeably diverges from the Oracle Berkeley DB API. If you prefer to have the get and set methods raise an exception when a key is not found, use this method to tell them to do so.
Calling this method on a DBEnv object will set the default for all DB’s later created within that environment. Calling it on a DB object sets the behaviour for that DB only.
The previous setting is returned.
Link an object to the DBEnv object. This allows to pass around an arbitrary object. For instance, for callback context.
Give the object linked to the DBEnv.
Returns the current open method flags. That is, this method returns the flags that were specified when DB_ENV->open() was called. More info…
The path of a directory to be used as the location of logging files. Log files created by the Log Manager subsystem will be created in this directory. More info…
Returns the number of lock table partitions used in the Berkeley DB environment. More info…
Set the number of lock table partitions in the Berkeley DB environment. More info…
Set the maximum number of locks supported by the Berkeley DB lock subsystem. More info…
Set the maximum number of simultaneous locking entities supported by the Berkeley DB lock subsystem. More info…
Set the maximum number of simultaneously locked objects supported by the Berkeley DB lock subsystem. More info…
Returns the the maximum file size, in bytes, for a file to be mapped into the process address space. More info…
Files that are opened read-only in the memory pool (and that satisfy a few other criteria) are, by default, mapped into the process address space instead of being copied into the local cache. This can result in better-than-usual performance, as available virtual memory is normally much larger than the local cache, and page faults are faster than page copying on many systems. However, in the presence of limited virtual memory it can cause resource starvation, and in the presence of large databases, it can result in immense process sizes.
This method sets the maximum file size, in bytes, for a file to be mapped into the process address space. If no value is specified, it defaults to 10MB. More info…
Maps lsn to filenames, returning the name of the file containing the named record. More info…
- log_printf(string, txn=None)¶
Appends an informational message to the Berkeley DB database environment log files. More info…
Returns a list of log or database file names. By default, log_archive returns the names of all of the log files that are no longer in use (e.g., no longer involved in active transactions), and that may safely be archived for catastrophic recovery and then removed from the system. More info…
Force log records to disk. Useful if the environment, database or transactions are used as ACI, instead of ACID. For example, if the environment is opened as DB_TXN_NOSYNC. If provided, lsn is a tuple: (file, offset) More info…
Returns whether the specified which parameter is currently set or not. You can manage this value using the DB_ENV->log_set_config() method. More info…
- lock_detect(atype, flags=0)¶
Run one iteration of the deadlock detector, returns the number of transactions aborted. More info…
- lock_get(locker, obj, lock_mode, flags=0)¶
Acquires a lock and returns a handle to it as a DBLock object. The locker parameter is an integer representing the entity doing the locking, and obj is an object representing the item to be locked. More info…
Acquires a locker id, guaranteed to be unique across all threads and processes that have the DBEnv open. More info…
Returns a dictionary of locking subsystem statistics with the following keys:
Last allocated lock ID.
The current maximum unused locker ID.
Number of lock modes.
Maximum number of locks possible.
Maximum number of lockers possible.
Maximum number of objects possible.
Number of current locks.
Maximum number of locks at once.
Number of current lockers.
Number of current lock objects.
Maximum number of lock objects at once.
Maximum number of lockers at once.
Total number of locks requested.
Total number of locks released.
Total number of locks upgraded.
Total number of locks downgraded.
The number of lock requests not immediately available due to conflicts, for which the thread of control waited.
The number of lock requests not immediately available due to conflicts, for which the thread of control did not wait.
Number of deadlocks.
Lock timeout value.
The number of lock requests that have timed out.
Transaction timeout value.
The number of transactions that have timed out. This value is also a component of ndeadlocks, the total number of deadlocks detected.
The number of requests to allocate or deallocate an object for which the thread of control waited.
The number of requests to allocate or deallocate an object for which the thread of control did not wait.
The number of requests to allocate or deallocate a locker for which the thread of control waited.
The number of requests to allocate or deallocate a locker for which the thread of control did not wait.
The number of requests to allocate or deallocate a lock structure for which the thread of control waited.
The number of requests to allocate or deallocate a lock structure for which the thread of control did not wait.
Maximum length of a lock hash bucket.
Size of the region.
Number of times a thread of control was forced to wait before obtaining the region lock.
Number of times a thread of control was able to obtain the region lock without waiting.
Returns a DBTxn object referring to a new Berkeley DB Concurrent Data Store group. This creates a locker ID that is shared by all cursors opened in the group. More info…
Recover to the time specified by timestamp rather than to the most current possible date. More info…
- txn_begin(parent=None, flags=0)¶
Creates and begins a new transaction. A DBTxn object is returned. More info…
- txn_checkpoint(kbyte=0, min=0, flag=0)¶
Flushes the underlying memory pool, writes a checkpoint record to the log and then flushes the log. More info…
Return a dictionary of transaction statistics with the following keys:
The LSN of the last checkpoint.
Time the last completed checkpoint finished (as the number of seconds since the Epoch, returned by the IEEE/ANSI Std 1003.1 POSIX time interface).
Last transaction ID allocated.
Max number of active transactions possible.
Number of transactions currently active.
Max number of active transactions at once.
The number of transactions on the snapshot list. These are transactions which modified a database opened with DB_MULTIVERSION, and which have committed or aborted, but the copies of pages they created are still in the cache.
The maximum number of transactions on the snapshot list at any one time.
Number of transactions that have begun.
Number of transactions that have aborted.
Number of transactions that have committed.
Number of transactions that have been restored.
Size of the region.
Number of times that a thread of control was forced to wait before obtaining the region lock.
Number of times that a thread of control was able to obtain the region lock without waiting.
- lsn_reset(file, flags=0)¶
This method allows database files to be moved from one transactional database environment to another. More info…
Returns a dictionary of logging subsystem statistics with the following keys:
The magic number that identifies a file as a log file.
The version of the log file type.
The mode of any created log files.
The in-memory log record cache size.
The log file size.
The number of records written to this log.
The number of megabytes written to this log.
The number of bytes over and above w_mbytes written to this log.
The number of megabytes written to this log since the last checkpoint.
The number of bytes over and above wc_mbytes written to this log since the last checkpoint.
The number of times the log has been written to disk.
The number of times the log has been written to disk because the in-memory log record cache filled up.
The number of times the log has been read from disk.
The number of times the log has been flushed to disk.
The current log file number.
The byte offset in the current log file.
The log file number of the last record known to be on disk.
The byte offset of the last record known to be on disk.
The maximum number of commits contained in a single log flush.
The minimum number of commits contained in a single log flush that contained a commit.
The size of the log region, in bytes.
The number of times that a thread of control was forced to wait before obtaining the log region mutex.
The number of times that a thread of control was able to obtain the log region mutex without waiting.
Returns a list of tuples (GID, TXN) of transactions prepared but still unresolved. This is used while doing environment recovery in an application using distributed transactions.
This method must be called only from a single thread at a time. It should be called after DBEnv recovery. More info…
- set_verbose(which, onoff)¶
Turns specific additional informational and debugging messages in the Berkeley DB message output on and off. To see the additional messages, verbose messages must also be configured for the application. More info…
Returns whether the specified which parameter is currently set or not. More info…
Configures a callback function which is called to notify the process of specific Berkeley DB events. More info…
Returns a dictionary of mutex subsystem statistics with the following keys:
The mutex alignment, in bytes.
The number of times test-and-set mutexes will spin without blocking.
The total number of mutexes configured.
The number of mutexes currently available.
The number of mutexes currently in use.
The maximum number of mutexes ever in use.
The size of the mutex region, in bytes.
The number of times that a thread of control was forced to wait before obtaining the mutex region mutex.
The number of times that a thread of control was able to obtain the mutex region mutex without waiting.
Specify that test-and-set mutexes should spin tas_spins times without blocking. Check the default values in the Oracle webpage. More info…
DBEnv Replication Manager Methods¶
This module automates many of the tasks needed to provide replication abilities in a Berkeley DB system. The module is fairly limited, but enough in many cases. Users more demanding must use the full Base Replication API.
This module requires pthread support (in Unix), so you must compile Berkeley DB with it if you want to be able to use the Replication Manager.
- repmgr_site(host, port)¶
Returns a DB_SITE handle that defines a site’s host/port network address. You use the DB_SITE handle to configure and manage replication sites. More info…
Returns a DB_SITE handle based on the site’s Environment ID value. You use the DB_SITE handle to configure and manage replication sites. More info…
Specifies how master and client sites will handle acknowledgment of replication messages which are necessary for “permanent” records. More info…
Returns a dictionary with the status of the sites currently known by the replication manager.
The keys are the Environment ID assigned by the replication manager. This is the same value that is passed to the application’s event notification function for the DB_EVENT_REP_NEWMASTER event.
The values are tuples containing the hostname, the TCP/IP port number and the link status.
Returns a dictionary with the replication manager statistics. Keys are:
The number of times a message critical for maintaining database integrity (for example, a transaction commit), originating at this site, did not receive sufficient acknowledgement from clients, according to the configured acknowledgement policy and acknowledgement timeout.
The number of outgoing messages which could not be transmitted immediately, due to a full network buffer, and had to be queued for later delivery.
The number of outgoing messages that were completely dropped, because the outgoing message queue was full. (Berkeley DB replication is tolerant of dropped messages, and will automatically request retransmission of any missing messages as needed.)
The number of times an existing TCP/IP connection failed.
The number of times an attempt to open a new TCP/IP connection failed.
DBEnv Replication Methods¶
This section provides the raw methods for replication. If possible, it is recommended to use the Replication Manager.
- rep_set_transport(envid, transportFunc)¶
Initializes the communication infrastructure for a database environment participating in a replicated application. More info…
- rep_process_messsage(control, rec, envid)¶
Processes an incoming replication message sent by a member of the replication group to the local database environment.
Returns a two element tuple.
- rep_start(flags, cdata=None)¶
Configures the database environment as a client or master in a group of replicated database environments.
The DB_ENV->rep_start method is not called by most replication applications. It should only be called by applications implementing their own network transport layer, explicitly holding replication group elections and handling replication messages outside of the replication manager framework.
Forces master synchronization to begin for this client. This method is the other half of setting the DB_REP_CONF_DELAYCLIENT flag via the DB_ENV->rep_set_config method. More info…
Returns whether the specified which parameter is currently set or not. More info…
Sets a byte-count limit on the amount of data that will be transmitted from a site in response to a single message processed by the DB_ENV->rep_process_message method. The limit is not a hard limit, and the record that exceeds the limit is the last record to be sent. More info…
Gets a byte-count limit on the amount of data that will be transmitted from a site in response to a single message processed by the DB_ENV->rep_process_message method. The limit is not a hard limit, and the record that exceeds the limit is the last record to be sent. More info…
- rep_set_request(minimum, maximum)¶
Sets a threshold for the minimum and maximum time that a client waits before requesting retransmission of a missing message. Specifically, if the client detects a gap in the sequence of incoming log records or database pages, Berkeley DB will wait for at least min microseconds before requesting retransmission of the missing record. Berkeley DB will double that amount before requesting the same missing record again, and so on, up to a maximum threshold of max microseconds. More info…
Returns a tuple with the minimum and maximum number of microseconds a client waits before requesting retransmission. More info…
Specifies the database environment’s priority in replication group elections. The priority must be a positive integer, or 0 if this environment cannot be a replication group master. More info…
- rep_set_clockskew(fast, slow)¶
Sets the clock skew ratio among replication group members based on the fastest and slowest measurements among the group for use with master leases. More info…
Returns a dictionary with the replication subsystem statistics. Keys are:
The number of times the bulk buffer filled up, forcing the buffer content to be sent.
The number of times a record was bigger than the entire bulk buffer, and therefore had to be sent as a singleton.
The number of records added to a bulk buffer.
The number of bulk buffers transferred (via a call to the application’s send function).
The number of times this client site received a “re-request” message, indicating that a request it previously sent to another client could not be serviced by that client. (Compare to client_svc_miss.)
The number of “request” type messages received by this client that could not be processed, forcing the originating requester to try sending the request to the master (or another client).
The number of “request” type messages received by this client. (“Request” messages are usually sent from a client to the master, but a message marked with the DB_REP_ANYWHERE flag in the invocation of the application’s send function may be sent to another client instead.)
The number of duplicate master conditions originally detected at this site.
The current election generation number.
The election winner.
The election generation number.
The maximum LSN of election winner.
The number sites responding to this site during the last election.
The number of votes required in the last election.
The election priority.
The number of seconds the last election took (the total election time is election_sec plus election_usec).
The current election phase (0 if no election is in progress).
The election tiebreaker value.
The number of microseconds the last election took (the total election time is election_sec plus election_usec).
The number of votes received in the last election.
The number of elections held.
The number of elections won.
The current environment ID.
The current environment priority.
The current generation number.
The number of duplicate log records received.
The number of log records currently queued.
The maximum number of log records ever queued at once.
The total number of log records queued.
The number of log records received and appended to the log.
The number of times log records were missed and requested.
The current master environment ID.
The number of times the master has changed.
The number of seconds of the longest lease (the total lease time is max_lease_sec plus max_lease_usec).
The number of microseconds of the longest lease (the total lease time is max_lease_sec plus max_lease_usec).
The LSN of the maximum permanent log record, or 0 if there are no permanent log records.
The number of messages received with a bad generation number.
The number of messages received and processed.
The number of messages ignored due to pending recovery.
The number of failed message sends.
The number of messages sent.
The number of new site messages received.
In replication environments configured as masters, the next LSN expected. In replication environments configured as clients, the next LSN to be used.
The next page number we expect to receive.
The number of sites used in the last election.
Transmission limited. This indicates the number of times that data transmission was stopped to limit the amount of data sent in response to a single call to DB_ENV->rep_process_message.
The number of outdated conditions detected.
The number of duplicate pages received.
The number of pages received and stored.
The number of pages missed and requested from the master.
The number of times the client had to delay the start of a cache flush operation (initiated by the master for an impending checkpoint) because it was missing some previous log record(s).
The client site has completed its startup procedures and is now handling live records from the master.
- The current replication mode. Set to
DB_REP_MASTER if the environment is a replication master, DB_REP_CLIENT if the environment is a replication client, or 0 if replication is not configured.
The number of transactions applied.
The LSN of the first log record we have after missing log records being waited for, or 0 if no log records are currently missing.
The page number of the first page we have after missing pages being waited for, or 0 if no pages are currently missing.