z3c.zalchemy 0.2.2

Important

Zope uses the transaction module to handle transactions. zalchemy plugs into this mechanism and uses its own data manager to use Zope’s transaction module.

zalchemy provides the method z3c.zalchemy.getSession to obtain a SQLAlchemy session object. This method makes sure the session is connected to Zope’s transactions.

Never get a session directly from SQLAlchemy!

It is also important to never store an instance of a session. Always directly use z3c.zalchemy.getSession. This is necessary because you never know when a transaction is commited. A commit always invalidates the current session. A new call to getSession makes sure a new session is created.

zalchemy Class Implementation

There is no difference between the usage of SQLAlchemy together with Zope.

zalchemy provides a transparent way to connect a table to a database (engine).

A SQLAlchemy engine is represented as a utility:

>>> from z3c.zalchemy.datamanager import AlchemyEngineUtility
>>> engineUtility = AlchemyEngineUtility(
...       'database',
...       'sqlite:///%s'%dbFilename,
...       echo=False,
...       )

We create our table as a normal SQLAlchemy table. The important thing here is, that the metadata from zalchemy must be used. Please note that you need to call z3c.zalchemy.metadata.

>>> import sqlalchemy
>>> import z3c.zalchemy
>>> table3 = sqlalchemy.Table(
...     'table3',
...     z3c.zalchemy.metadata(),
...     sqlalchemy.Column('id', sqlalchemy.Integer,
...         sqlalchemy.Sequence('atable_id'), primary_key=True),
...     sqlalchemy.Column('value', sqlalchemy.Integer),
...     )

Define a simple class which will be used later to map to a database table.

>>> class A(object):
...     pass

Now we map the table to our class.

>>> sqlalchemy.mapper(A, table3) is not None
True

To let zalchemy do its work we need to register our database utility.

>>> from z3c.zalchemy.interfaces import IAlchemyEngineUtility
>>> from zope.component import provideUtility
>>> provideUtility(engineUtility, IAlchemyEngineUtility)

Tables can be created without an open transaction or session. If no session is created then the table creation is deferred to the next call to zalchemy.getSession.

>>> z3c.zalchemy.createTable('table3', '')

zalchemy automatically coordinates Zope’s transaction manager with SQLAlchemy’s sessions. All mapped classes are automatically associated with thread-local session, which in turn is automatically connected to a special data manager that coordinates with Zope’s transactions.

>>> a = A()
>>> a.value = 1

Committing a transaction will automatically trigger a flush and clear the session.

>>> import transaction
>>> transaction.commit()

Now let’s try to get the object back in a new transaction (we’re in a new transaction already because the old transaction was committed):

>>> from z3c.zalchemy.datamanager import getSession as session
>>> a = session().get(A, 1)
>>> a.value
1

>>> transaction.commit()

0.2.2 (2011-08-05)

• Fix packaging problem: Declare namespace package ‘z3c’.

0.2.1 - 2007-11-13

• Conflict detection did not work with savepoints.

0.2 - 2007-09-27

• Added a way to register database specific adapters for conflict detection and possible re-do by the publisher.

• Using the threadlocal strategy of sqlalchemy instead of doing that ourselves.

• Added support for optimistic savepoints. This can be used, similarly to what happens with ZODB, to flush intermediary work without committing.

• Provide a tighter integration with Zope’s transaction mechanism. Sessions are now automatically associated with new objects. We rely on SQLAlchemy’s SessionContext object which hands out a session for each thread. Your code rarely should never have to call session.save(object) now.

  One incompatible change was introduced: You can not call getSession before registering an (unnamed) engine utility first. Doing so will raise a ValueError.

0.1.1 - 2007-06-27

• Fixed a failing test in TRANSACTION.txt where an exception demonstrated a string being returned but it was a unicode string.

0.1 - never released

• This was supposed to be the first release, but we missed a broken test. See 0.1.1