ZODB APIs

ZODB module functions

DB(storage, *args, **kw)

Create a database. See ZODB.DB.

ZODB.connection(*args, **kw)

Create a database connection.

A database is created using the given arguments and opened to create the returned connection. The database will be closed when the connection is closed. This is a convenience function to avoid managing a separate database object.

Databases

class ZODB.DB(storage, pool_size=7, pool_timeout=2147483648, cache_size=400, cache_size_bytes=0, historical_pool_size=3, historical_cache_size=1000, historical_cache_size_bytes=0, historical_timeout=300, database_name='unnamed', databases=None, xrefs=True, large_record_size=16777216, **storage_args)

The Object Database

The DB class coordinates the activities of multiple database Connection instances. Most of the work is done by the Connections created via the open method.

The DB instance manages a pool of connections. If a connection is closed, it is returned to the pool and its object cache is preserved. A subsequent call to open() will reuse the connection. There is no hard limit on the pool size. If more than pool_size connections are opened, a warning is logged, and if more than twice that many, a critical problem is logged.

The database provides a few methods intended for application code – open, close, undo, and pack – and a large collection of methods for inspecting the database and its connections’ caches.

__init__(storage, pool_size=7, pool_timeout=2147483648, cache_size=400, cache_size_bytes=0, historical_pool_size=3, historical_cache_size=1000, historical_cache_size_bytes=0, historical_timeout=300, database_name='unnamed', databases=None, xrefs=True, large_record_size=16777216, **storage_args)

Create an object database.

Parameters:

• storage – the storage used by the database, such as a FileStorage. This can be a string path name to use a constructed FileStorage storage or None to use a constructed MappingStorage.

• pool_size (int) – expected maximum number of open connections. Warnings are logged when this is exceeded and critical messages are logged if twice the pool size is exceeded.

• pool_timeout (seconds) – Maximum age of inactive connections When a connection has remained unused in a connection pool for more than pool_timeout seconds, it will be discarded and it’s resources released.

• cache_size (objects) – target maximum number of non-ghost objects in each connection object cache.

• cache_size_bytes (int) – target total memory usage of non-ghost objects in each connection object cache.

• historical_pool_size (int) – expected maximum number of total historical connections

• historical_cache_size (objects) – target maximum number of non-ghost objects in each historical connection object cache.

• historical_cache_size_bytes (int) – target total memory usage of non-ghost objects in each historical connection object cache.

• historical_timeout (seconds) – Maximum age of inactive historical connections. When a connection has remained unused in a historical connection pool for more than pool_timeout seconds, it will be discarded and it’s resources released.

• database_name (str) – The name of this database in a multi-database configuration. The name is used when constructing cross-database references ans when accessing database connections fron other databases.

• databases (dict) – dictionary of database name to databases in a multi-database configuration. The new database will add itself to this dictionary. The dictionary is used when getting connections in other databases.

• xrefs (boolean) – Flag indicating whether cross-database references are allowed from this database to other databases in a multi-database configuration.

• large_record_size (int) – When object records are saved that are larger than this, a warning is issued, suggesting that blobs should be used instead.

• storage_args – Extra keywork arguments passed to a storage constructor if a path name or None is passed as the storage argument.

cacheDetail()

Return object counts by class accross all connections.

cacheDetailSize()

Return non-ghost counts sizes for all connections.

cacheExtremeDetail()

Return information about all of the objects in the object caches.

Information includes a connection number, class, object id, reference count and state. The reference count returned excludes references help by ZODB itself.

cacheMinimize()

Minimize cache sizes for all connections

cacheSize()

Return the total count of non-ghost objects in all object caches

close()

Close the database and its underlying storage.

It is important to close the database, because the storage may flush in-memory data structures to disk when it is closed. Leaving the storage open with the process exits can cause the next open to be slow.

What effect does closing the database have on existing connections? Technically, they remain open, but their storage is closed, so they stop behaving usefully. Perhaps close() should also close all the Connections.

connectionDebugInfo()

Get debugging information about connections

This is especially useful to debug connections that seem to be leaking or open too long. Information includes connection info, the connection before setting, and, if a connection is open, the time it was opened. The info is the result of calling getDebugInfo() on the connection, and the connection’s cache size.

getCacheSize()

Get the configured cache size (objects).

getCacheSizeBytes()

Get the configured cache size in bytes.

getHistoricalCacheSize()

Get the configured historical cache size (objects).

getHistoricalCacheSizeBytes()

Get the configured historical cache size in bytes.

getHistoricalPoolSize()

Get the configured historical pool size

getHistoricalTimeout()

Get the configured historical pool timeout

getName()

Get the storage name

getPoolSize()

Get the configured pool size

getSize()

Get the approximate database size, in bytes

history(oid, size=1)

Get revision history information for an object.

See ZODB.interfaces.IStorage.history().

lastTransaction()

Get the storage last transaction id.

objectCount()

Get the approximate object count

open(transaction_manager=None, at=None, before=None)

Return a database Connection for use by application code.

Note that the connection pool is managed as a stack, to increase the likelihood that the connection’s stack will include useful objects.

Parameters:

• transaction_manager: transaction manager to use. None means use the default transaction manager.

• at: a datetime.datetime or 8 character transaction id of the time to open the database with a read-only connection. Passing both at and before raises a ValueError, and passing neither opens a standard writable transaction of the newest state. A timezone-naive datetime.datetime is treated as a UTC value.

• before: like at, but opens the readonly state before the tid or datetime.

pack(t=None, days=0)

Pack the storage, deleting unused object revisions.

A pack is always performed relative to a particular time, by default the current time. All object revisions that are not reachable as of the pack time are deleted from the storage.

The cost of this operation varies by storage, but it is usually an expensive operation.

There are two optional arguments that can be used to set the pack time: t, pack time in seconds since the epcoh, and days, the number of days to subtract from t or from the current time if t is not specified.

setCacheSize(size)

Reconfigure the cache size (non-ghost object count)

setCacheSizeBytes(size)

Reconfigure the cache total size in bytes

setHistoricalCacheSize(size)

Reconfigure the historical cache size (non-ghost object count)

setHistoricalCacheSizeBytes(size)

Reconfigure the historical cache total size in bytes

setHistoricalPoolSize(size)

Reconfigure the connection historical pool size

setHistoricalTimeout(timeout)

Reconfigure the connection historical pool timeout

setPoolSize(size)

Reconfigure the connection pool size

storage = storage object

Database storage, implementing IStorage

supportsUndo()

Return whether the database supports undo.

transaction(note=None)

Execute a block of code as a transaction.

If a note is given, it will be added to the transaction’s description.

The transaction method returns a context manager that can be used with the with statement.

undo(id, txn=None)

Undo a transaction identified by id.

A transaction can be undone if all of the objects involved in the transaction were not modified subsequently, if any modifications can be resolved by conflict resolution, or if subsequent changes resulted in the same object state.

The value of id should be generated by calling undoLog() or undoInfo(). The value of id is not the same as a transaction id used by other methods; it is unique to undo().

Parameters:

• id: a transaction identifier

• txn: transaction context to use for undo(). By default, uses the current transaction.

undoInfo(*args, **kw)

Return a sequence of descriptions for transactions.

See ZODB.interfaces.IStorageUndoable.undoInfo().

undoLog(*args, **kw)

Return a sequence of descriptions for transactions.

See ZODB.interfaces.IStorageUndoable.undoLog().

undoMultiple(ids, txn=None)

Undo multiple transactions identified by ids.

A transaction can be undone if all of the objects involved in the transaction were not modified subsequently, if any modifications can be resolved by conflict resolution, or if subsequent changes resulted in the same object state.

The values in ids should be generated by calling undoLog() or undoInfo(). The value of ids are not the same as a transaction ids used by other methods; they are unique to undo().

Parameters:

• ids: a sequence of storage-specific transaction identifiers

• txn: transaction context to use for undo(). By default, uses the current transaction.

Database text configuration

Databases are configured with zodb sections:

<zodb>
  cache-size-bytes 100MB
  <mappingstorage>
  </mappingstorage>
</zodb>

A zodb section must have a storage sub-section specifying a storage and any of the following options:

allow-implicit-cross-references (boolean)

If set to false, implicit cross references (the only kind currently possible) are disallowed.

cache-size (integer, default: 5000)

Target size, in number of objects, of each connection’s object cache.

cache-size-bytes (byte-size, default: 0)

Target size, in total estimated size for objects, of each connection’s object cache. “0” means no limit.

database-name (string)

When multi-databases are in use, this is the name given to this database in the collection. The name must be unique across all databases in the collection. The collection must also be given a mapping from its databases’ names to their databases, but that cannot be specified in a ZODB config file. Applications using multi-databases typical supply a way to configure the mapping in their own config files, using the “databases” parameter of a DB constructor.

historical-cache-size (integer, default: 1000)

Target size, in number of objects, of each historical connection’s object cache.

historical-cache-size-bytes (byte-size, default: 0)

Target size, in total estimated size of objects, of each historical connection’s object cache.

historical-pool-size (integer, default: 3)

The expected maximum total number of historical connections simultaneously open.

historical-timeout (time-interval, default: 5m)

The minimum interval that an unused historical connection should be kept.

large-record-size (byte-size, default: 16MB)

When object records are saved that are larger than this, a warning is issued, suggesting that blobs should be used instead.

pool-size (integer, default: 7)

The expected maximum number of simultaneously open connections. There is no hard limit (as many connections as are requested will be opened, until system resources are exhausted). Exceeding pool-size connections causes a warning message to be logged, and exceeding twice pool-size connections causes a critical message to be logged.

pool-timeout (time-interval)

The minimum interval that an unused (non-historical) connection should be kept.

For a multi-database configuration, use multiple zodb sections and give the sections names:

<zodb first>
  cache-size-bytes 100MB
  <mappingstorage>
  </mappingstorage>
</zodb>

<zodb second>
  <mappingstorage>
  </mappingstorage>
</zodb>

When the configuration is loaded, a single database will be returned, but all of the databases will be available through the returned database’s databases attribute.

Connections

class ZODB.Connection.Connection(db, cache_size=400, before=None, cache_size_bytes=0)

Connection to ZODB for loading and storing objects.

Connections manage object state in collaboration with transaction managers. They’re created by calling the open() method on database objects.

add(obj)

Add a new object ‘obj’ to the database and assign it an oid.

cacheGC()

Reduce cache size to target size.

cacheMinimize()

Deactivate all unmodified objects in the cache.

close(primary=True)

Close the Connection.

db()

Returns a handle to the database this connection belongs to.

get(oid)

Return the persistent object with oid ‘oid’.

getDebugInfo()

Returns a tuple with different items for debugging the connection.

get_connection(database_name)

Return a Connection for the named database.

isReadOnly()

Returns True if this connection is read only.

oldstate(obj, tid)

Return copy of ‘obj’ that was written by transaction ‘tid’.

onCloseCallback(f)

Register a callable, f, to be called by close().

property root

Return the database root object.

setDebugInfo(*args)

Add the given items to the debug information of this connection.

sync()

Manually update the view on the database.

transaction_manager = current transaction manager

Transaction manager associated with the connection when it was opened.

TimeStamp (transaction ids)

class ZODB.TimeStamp.TimeStamp(year, month, day, hour, minute, seconds)

Create a time-stamp object. Time stamps facilitate the computation of transaction ids, which are based on times. The arguments are integers, except for seconds, which may be a floating-point number. Time stamps have microsecond precision. Time stamps are implicitly UTC based.

Time stamps are orderable and hashable.

day()

Return the time stamp’s day.

hour()

Return the time stamp’s hour.

laterThan(other)

Return a timestamp instance which is later than ‘other’.

If self already qualifies, return self.

Otherwise, return a new instance one moment later than ‘other’.

minute()

Return the time stamp’s minute.

month()

Return the time stamp’s month.

raw()

Get an 8-byte representation of the time stamp for use in APIs that require a time stamp.

second()

Return the time stamp’s second.

timeTime()

Return the time stamp as seconds since the epoc, as used by the time module.

year()

Return the time stamp’s year.

Loading configuration

Open database and storage from a configuration.

ZODB.config.databaseFromFile(f)

Create a database from a file object that provides configuration.

See databaseFromString().

ZODB.config.databaseFromString(s)

Create a database from a database-configuration string.

The string must contain one or more zodb sections.

The database defined by the first section is returned.

If more than one zodb section is provided, a multi-database configuration will be created and all of the databases will be available in the returned database’s databases attribute.

ZODB.config.databaseFromURL(url)

Load a database from URL (or file name) that provides configuration.

See databaseFromString().

ZODB.config.storageFromFile(f)

Create a storage from a file object providing storage-configuration.

ZODB.config.storageFromString(s)

Create a storage from a storage-configuration string.

ZODB.config.storageFromURL(url)

Create a storage from a URL (or file name) providing storage-configuration.