I dropped the ball a bit on this.
I took the last round of feedback and integrated it into a new version
of the specification. If people are happy with this, what is the next
step?
James.
Abstract
========
Many databases have support for two-phase commit. Adapters for some
of these databases expose this support, but often through mutually
incompatible extensions to the DB-API standard.
Standardising the API for two-phase commit would make it easier for
applications and libraries to support two-phase commit with multiple
databases.
Connection Methods
------------------
A database adapter that supports two phase commit (2PC) shall provide
the following additional methods on its connection object:
.tpc_begin(xid)
Begins a 2PC transaction with the given ID. This method
should be called outside of a transaction (i.e. nothing may
have executed since the last .commit() or .rollback()).
Furthermore, it is an error to call .commit() or .rollback()
within the 2PC transaction (what error?).
If the database does not support 2PC, a NotSupportedError will
be raised.
.tpc_prepare()
Performs the first phase of a transaction started with
tpc_begin(). It is an error to call this method outside of a
2PC transaction.
After calling tpc_prepare(), no statements can be executed
until tpc_commit() or tpc_rollback() have been called.
.tpc_commit(xid=None)
When called with no arguments, tpc_commit() commits a 2PC
transaction previously prepared with tpc_prepare().
If tpc_commit() is called prior to tpc_prepare(), a single
phase commit is performed. A transaction manager may choose
to do this if only a single resource is participating in the
global transaction.
When called as tpc_commit(xid), it commits the given
transaction. If an invalid transaction ID is provided, a
DatabaseError will be raised. This form should be called
outside of a transaction, and is intended for use in recovery.
On return, the 2PC transaction is ended.
.tpc_rollback(xid=None)
When called with no arguments, tpc_rollback() rolls back a 2PC
transaction. It may be called before or after tpc_prepare().
When called as tpc_commit(xid), it rolls back the given
transaction. If an invalid transaction ID is provided, a
DatabaseError will be raised. This form should be called
outside of a transaction, and is intended for use in recovery.
On return, the 2PC transaction is ended.
.tpc_recover()
Returns a list of pending transaction IDs suitable for use
with tpc_commit(xid) or tpc_rollback(xid).
If the database does not support transaction recovery, it may
return an empty list or NotSupportedError.
Transaction IDs
---------------
As many databases follow the XA specification, transaction IDs are
formed from three components:
* a format ID
* a global transaction ID
* a branch qualifier
For a particular global transaction, the first two components should
be the same for all resources. Each resource in the global
transaction should be assigned a different branch qualifier.
The various components must satisfy the following criteria:
* formatID: a non-negative 32-bit integer.
* global transaction ID and branch qualifier: byte strings no longer
than 64 characters.
Transaction IDs are created with the .xid connection method:
.xid(formatID, gtrid, bqual)
Returns a transaction ID object suitable for passing to the
tpc_*() methods of this connection.
The type of the object returned by xid() is not defined, but it must
provide sequence behaviour, allowing access to the three components.
A conforming database module could choose to represent transaction IDs
with tuples rather than a custom object.
_______________________________________________
DB-SIG maillist - DB-SIG@python.org
http://mail.python.org/mailman/listinfo/db-sig
