Connection to ZODB for loading and storing objects.

The Connection object serves as a data manager. The root() method on a Connection returns the root object for the database. This object and all objects reachable from it are associated with the Connection that loaded them. When a transaction commits, it uses the Connection to store modified objects.

Typical use of ZODB is for each thread to have its own Connection and that no thread should have more than one Connection to the same database. A thread is associated with a Connection by loading objects from that Connection. Objects loaded by one thread should not be used by another thread.

A Connection can be associated with a single version when it is created. By default, a Connection is not associated with a version; it uses non-version data.

Each Connection provides an isolated, consistent view of the database, by managing independent copies of objects in the database. At transaction boundaries, these copies are updated to reflect the current state of the database.

You should not instantiate this class directly; instead call the open() method of a DB instance.

In many applications, root() is the only method of the Connection that you will need to use.

Synchronization ---------------

A Connection instance is not thread-safe. It is designed to support a thread model where each thread has its own transaction. If an application has more than one thread that uses the connection or the transaction the connection is registered with, the application should provide locking.

The Connection manages movement of objects in and out of object storage.

TODO: We should document an intended API for using a Connection via multiple threads.

TODO: We should explain that the Connection has a cache and that multiple calls to get() will return a reference to the same object, provided that one of the earlier objects is still referenced. Object identity is preserved within a connection, but not across connections.

TODO: Mention the database pool.

A database connection always presents a consistent view of the objects in the database, although it may not always present the most current revision of any particular object. Modifications made by concurrent transactions are not visible until the next transaction boundary (abort or commit).

Two options affect consistency. By default, the mvcc and synch options are enabled by default.

If you pass mvcc=False to, the Connection will never read non-current revisions of an object. Instead it will raise a ReadConflictError to indicate that the current revision is unavailable because it was written after the current transaction began.

The logic for handling modifications assumes that the thread that opened a Connection (called is the thread that will use the Connection. If this is not true, you should pass synch=False to When the synch option is disabled, some transaction boundaries will be missed by the Connection; in particular, if a transaction does not involve any modifications to objects loaded from the Connection and synch is disabled, the Connection will miss the transaction boundary. Two examples of this behavior are db.undo() and read-only transactions.

Groups of methods:

User Methods: root, get, add, close, db, sync, isReadOnly, cacheGC, cacheFullSweep, cacheMinimize, getVersion, modifiedInVersion

Experimental Methods: onCloseCallbacks

Database Invalidation Methods: invalidate

Other Methods: exchange, getDebugInfo, setDebugInfo, getTransferCounts

Base interfaces


* = required



Adapters for objects providing this interface:

Specific Adapters

There are no specific adapters registered for this interface.

Extended Adapters

There are no extended adapters registered for this interface.

Generic Adapters

Adapters that provide this interface:



Specific views

There are no views available.

Extended views

Generic views





Other Information


A list of classes that implement this interface. This might duplicate the entries in Utilities.