On 21/01/2008, James Henstridge <[EMAIL PROTECTED]> wrote:
> On 18/01/2008, James Henstridge <[EMAIL PROTECTED]> wrote:
> > So is there any recommendations for what a two-phase commit API should
> > look like?
>
> I did a bit of investigation into a few databases, and came up with a
> proposal for an extension to the DB-API.
Here is an updated version of the proposal. It removes the analysis
of the different databases, and updates the proposed API to match what
we've been discussing here.
I've added a section about what the "xid" arguments to the various
methods should look like. That could probably do with some more
discussion as I am not too sure about it.
I've also included support for transaction recovery in the form of an
xa_recover() method and calling the xa_commit()/xa_rollback() methods
with a transaction ID as an argument.
James.
= DB-API Two-Phase Commit =
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:
.xa_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.
.xa_prepare()
Performs the first phase of a transaction started with
xa_begin(). It is an error to call this method outside of a
2PC transaction.
After calling xa_prepare(), no statements can be executed
until xa_commit() or xa_rollback() have been called.
.xa_commit(xid=None, onephase=False)
When called with no arguments, xa_commit() commits a 2PC
transaction previously prepared with xa_prepare().
When called as xa_commit(onephase=True), it may be used to
commit the transaction prior to calling xa_prepare(). This
may occur if only a single resource ends up participating in
the global transaction.
When called as xa_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.
.xa_rollback(xid=None)
When called with no arguments, xa_rollback() rolls back a 2PC
transaction. It may be called before or after xa_prepare().
When called as xa_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.
.xa_recover()
Returns a list of pending transaction IDs suitable for use
with xa_commit(xid) or xa_rollback(xid).
If the database does not support transaction recovery, it may
return an empty list or NotSupportedError.
== Transaction IDs ==
XXX: This needs discussion.
Transaction IDs should probably be represented by an object holding
three quantities:
* global transaction ID
* branch qualifier
* format ID
The module shall provide the following constructor for transaction
IDs:
xid(gtrid [, bqual [, formatID]])
XXX: should this be at the module level, or a connection method?
_______________________________________________
DB-SIG maillist - DB-SIG@python.org
http://mail.python.org/mailman/listinfo/db-sig
