def set_bt_compare(self, compareFunc):
"""Set the B-Tree database comparison function. This can only be called once before the database has
been opened. compareFunc takes two arguments: (left key string, right key string) It must
return a -1, 0, 1 integer similar to cmp. You can shoot your database in the foot, beware!
Read the Berkeley DB docs for the full details of how the comparison function MUST behave.
"""
return pool.invoke(self.__db.set_bt_compare, compareFunc)
def repmgr_add_remote_site(self, host, port, flags=0):
"""Adds a new replication site to the replication manager's list of known sites.
It is not necessary for all sites in a replication group to know about all other sites in the group.
Method returns the environment ID assigned to the remote site.
"""
return pool.invoke(self.__dbenv.repmgr_add_remote_site, host, port, flags)
def set_range(self, key, flags=0, dlen=-1, doff=-1):
"""Identical to set() except that in the case of the BTree access method,
the returned key/data pair is the smallest key greater than or equal to the
specified key (as determined by the comparison function), permitting partial
key matches and range searches.
"""
return pool.invoke(self.__cursor.set_range, key, flags, dlen, doff)
def set_shm_key(self, key):
"""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.
"""
return pool.invoke(self.__dbenv.set_shm_key, key)
def prepare(self, gid):
"""Initiates the beginning of a two-phase commit. Begining with
Berkeley DB 3.3 a global identifier paramater is required, which
is a value unique across all processes involved in the commit. It
must be a string of DB_XIDDATASIZE bytes.
"""
return pool.invoke(self.__txn.prepare, gid)
def consume_wait(self, txn=None, flags=0):
"""For a database with the Queue access method, returns the record number
and data from the first available record and deletes it from the queue.
If the Queue database is empty, the thread of control will wait until there
is data in the queue before returning.
"""
return pool.invoke(self.__db.consume_wait, txn and txn._ADBTxn__txn, flags)
def compact(self, start=None, stop=None, flags=0, compact_fillpercent=0, compact_pages=0, compact_timeout=0):
"""Compacts Btree and Recno access method databases, and optionally returns
unused Btree, Hash or Recno database pages to the underlying filesystem.
The method returns the number of pages returned to the filesystem.
"""
return pool.invoke(self.__db.compact, start, stop, flags, compact_fillpercent, compact_pages, compact_timeout)
def log_archive(self, flags=0):
"""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.
"""
return pool.invoke(self.__dbenv.log_archive, flags)
def rep_process_messsage(self, 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.
"""
return pool.invoke(self.__dbenv.rep_process_messsage, control, rec, envid)
def consume(self, flags=0, dlen=-1, doff=-1):
""" For a database with the Queue access method, returns the record
number and data from the first available record and deletes it from the queue.
NOTE: This method is deprecated in Berkeley DB version 3.2 in favor of the
new consume method in the DB class.
"""
return pool.invoke(self.__cursor.consume, flags, dlen, doff)
def cursor(self, txn=None, flags=0):
"""Create a cursor on the DB and returns a DBCursor object. If a transaction
is passed then the cursor can only be used within that transaction and you must
be sure to close the cursor before commiting the transaction.
"""
def cursor_sync(txn, flags):
return ADBCursor(self.__db.cursor(txn and txn._ADBTxn__txn, flags))
return pool.invoke(cursor_sync, txn, flags)
def associate(self, secondaryDB, callback, flags=0, txn=None):
"""Used to associate secondaryDB to act as a secondary index for
this (primary) database. The callback parameter should be a reference
to a Python callable object that will construct and return the secondary
key or DB_DONOTINDEX if the item should not be indexed. The parameters
the callback will receive are the primaryKey and primaryData values.
"""
return pool.invoke(self.__db.associate, secondaryDB and secondaryDB._ADB__db, callback, flags, txn and txn._ADBTxn__txn)
def rep_set_request(self, 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.
"""
return pool.invoke(self.__dbenv.rep_set_request, minimum, maximum)
def fileid_reset(self, 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.
"""
return pool.invoke(self.__dbenv.fileid_reset, file, flags)
def rep_start(self, 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.
"""
return pool.invoke(self.__dbenv.rep_start, flags, cdata)
def get(self, key, default=None, txn=None, flags=0, dlen=-1, doff=-1):
"""Returns the data object associated with key. If key is an integer then
the DB_SET_RECNO flag is automatically set for BTree databases and the actual
key and the data value are returned as a tuple. If default is given then it
is returned if the key is not found in the database. Partial records can be read
using dlen and doff, however be sure to not read beyond the end of the actual
data or you may get garbage.
"""
return pool.invoke(self.__db.get, key, default, txn and txn._ADBTxn__txn, flags, dlen, doff)
def repmgr_site_list(self):
"""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.
"""
return pool.invoke(self.__dbenv.repmgr_site_list)
def txn_recover(self):
"""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.
"""
def txn_recover_sync():
return map(self.__dbenv.txn_recover(), lambda (gid, txn): (gid, ADBTxn(txn)))
return pool.invoke(txn_recover_sync)
def get(self, key, data, flags, dlen=-1, doff=-1):
"""Retrieves key/data pairs from the database using the cursor.
All the specific functionalities of the get method are actually
provided by the various methods below, which are the preferred way
to fetch data using the cursor. These generic interfaces are only
provided as an inconvenience. Partial data records are returned if
dlen and doff are used in this method and in many of the specific
methods below.
"""
return pool.invoke(self.__cursor.get, key, data, flags, dlen, doff)
def set_get_returns_none(self, flag):
"""By default when ADB.get or ADBCursor.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 ADBCursor.set, set_both, set_range, and
set_recno methods.
"""
return pool.invoke(self.__dbenv.set_get_returns_none, flag)
def set_mp_mmapsize(self, size):
"""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.
"""
return pool.invoke(self.__dbenv.set_mp_mmapsize, size)
def discard(self):
"""This method frees up all the per-process resources associated with
the specified transaction, neither committing nor aborting the transaction.
The transaction will be keep in "unresolved" state. This call may be used
only after calls to "dbenv.txn_recover()". A "unresolved" transaction will
be returned again thru new calls to "dbenv.txn_recover()".
For example, when there are multiple global transaction managers recovering
transactions in a single Berkeley DB environment, any transactions returned
by "dbenv.txn_recover()" that are not handled by the current global transaction
manager should be discarded using "txn.discard()"
"""
return pool.invoke(self.__txn.discard)
def get_range(self):
"""Returns a tuple representing the range of values in the sequence.
"""
return pool.invoke(self.__seq.get_range)
def stat(self, flags=0):
"""Returns a dictionary of sequence statistics.
"""
return pool.invoke(self.__seq.stat, flags)
def stat_print(self, flags=0):
"""Prints diagnostic information.
"""
return pool.invoke(self.__seq.stat_print, flags)
def set_flags(self, flags):
"""Configure a sequence.
"""
return pool.invoke(self.__seq.set_flags, flags)
def get_flags(self):
"""Returns the current flags.
"""
return pool.invoke(self.__seq.get_flags)
def set_cachesize(self, size):
"""Configure the number of elements cached by a sequence handle.
"""
return pool.invoke(self.__seq.set_cachesize, size)
def get_cachesize(self):
"""Returns the current cache size.
"""
return pool.invoke(self.__seq.get_cachesize)
def remove(self, txn=None, flags=0):
"""Removes the sequence from the database. This method should not be called if there
are other open handles on this sequence.
"""
return pool.invoke(self.__seq.remove, txn and txn._ADBTxn__txn, flags)