Skip to content

Commit 44e0014

Browse files
author
James William Pye
committed
Remove two-phase commit documentation.
1 parent 9627f5a commit 44e0014

2 files changed

Lines changed: 4 additions & 160 deletions

File tree

‎postgresql/api.py‎

Lines changed: 2 additions & 74 deletions
Original file line numberDiff line numberDiff line change
@@ -651,21 +651,6 @@ class Transaction(Element):
651651
>>> with db.xact():
652652
... with db.xact():
653653
... ...
654-
655-
[DEPRECATED]
656-
657-
Or, in cases where two-phase commit is desired:
658-
659-
>>> with db.xact(gid = 'gid') as gxact:
660-
... with gxact:
661-
... # phase 1 block
662-
... ...
663-
>>> # fully committed at this point
664-
665-
Considering that transactions decide what's saved and what's not saved, it is
666-
important that they are used properly. In most situations, when an action is
667-
performed where state of the transaction is unexpected, an exception should
668-
occur.
669654
"""
670655
_e_label = 'XACT'
671656
_e_factors = ('database',)
@@ -694,20 +679,6 @@ def isolation(self) -> (None, str):
694679
the START TRANSACTION statement.
695680
"""
696681

697-
@propertydoc
698-
@abstractproperty
699-
def gid(self) -> (None, str):
700-
"""
701-
[DEPRECATED]
702-
703-
The global identifier of the transaction block:
704-
705-
PREPARE TRANSACTION <gid>;
706-
707-
The `gid` property is a string that indicates that the block is a prepared
708-
transaction.
709-
"""
710-
711682
@abstractmethod
712683
def start(self) -> None:
713684
"""
@@ -726,7 +697,7 @@ def start(self) -> None:
726697
`self.mode` specifies the mode of the transaction. Normally, ``READ
727698
ONLY`` or ``READ WRITE``.
728699
729-
If the transaction is open--started or prepared, do nothing.
700+
If the transaction is already open, do nothing.
730701
731702
If the transaction has been committed or aborted, raise an
732703
`postgresql.exceptions.OperationError`.
@@ -738,9 +709,6 @@ def commit(self) -> None:
738709
"""
739710
Commit the transaction.
740711
741-
If the transaction is configured with a `gid` issue a COMMIT PREPARED
742-
statement with the configured `gid`.
743-
744712
If the transaction is a block, issue a COMMIT statement.
745713
746714
If the transaction was started inside a transaction block, it should be
@@ -759,46 +727,9 @@ def rollback(self) -> None:
759727
If the transaction is a transaction block, issue an ABORT.
760728
761729
If the transaction has already been aborted, do nothing.
762-
763-
[DEPRECATED]
764-
If the transaction is configured with a `gid` *and* has been prepared, issue
765-
a ROLLBACK PREPARE statement with the configured `gid`.
766730
"""
767731
abort = rollback
768732

769-
@abstractmethod
770-
def recover(self) -> None:
771-
"""
772-
[DEPRECATED]
773-
774-
If the transaction is assigned a `gid`, recover may be used to identify
775-
the transaction as prepared and ready for committing or aborting.
776-
777-
This method is used in recovery procedures where a prepared transaction
778-
needs to be committed or rolled back.
779-
780-
If no prepared transaction with the configured `gid` exists, a
781-
`postgresql.exceptions.UndefinedObjectError` must be raised.
782-
[This is consistent with the error raised by ROLLBACK/COMMIT PREPARED]
783-
784-
Once this method has been ran, it should identify the transaction as being
785-
prepared so that subsequent invocations to `commit` or `rollback` should
786-
cause the appropriate ROLLBACK PREPARED or COMMIT PREPARED statements to
787-
be executed.
788-
"""
789-
790-
@abstractmethod
791-
def prepare(self) -> None:
792-
"""
793-
[DEPRECATED]
794-
795-
Explicitly prepare the transaction with the configured `gid` by issuing a
796-
PREPARE TRANSACTION statement with the configured `gid`.
797-
This *must* be called for the first phase of the commit.
798-
799-
If the transaction is already prepared, do nothing.
800-
"""
801-
802733
@abstractmethod
803734
def __enter__(self):
804735
"""
@@ -822,9 +753,7 @@ def __exit__(self, typ, obj, tb):
822753
unavailable, the `rollback` method should cause a
823754
`postgresql.exceptions.ConnectionDoesNotExistError` exception to occur.
824755
825-
Otherwise, run the transaction's `commit` method. If the commit fails,
826-
a `gid` is configured, and the connection is still available, run the
827-
transaction's `rollback` method.
756+
Otherwise, run the transaction's `commit` method.
828757
829758
When the `commit` is ultimately unsuccessful or not ran at all, the purpose
830759
of __exit__ is to resolve the error state of the database iff the
@@ -955,7 +884,6 @@ def client_port(self) -> (int, None):
955884
@propertydoc
956885
@abstractproperty
957886
def xact(self,
958-
gid : "global identifier to configure" = None,
959887
isolation : "ISOLATION LEVEL to use with the transaction" = None,
960888
mode : "Mode of the transaction, READ ONLY or READ WRITE" = None,
961889
) -> Transaction:

‎postgresql/documentation/driver.txt‎

Lines changed: 2 additions & 86 deletions
Original file line numberDiff line numberDiff line change
@@ -341,7 +341,7 @@ The methods and properties on the connection object are ready for use:
341341
The `postgresql.api.Transaction` constructor for creating transactions.
342342
This method creates a transaction reference. The transaction will not be
343343
started until it's instructed to do so. See `Transactions`_ for more
344-
information. (**gid keyword is deprecated**)
344+
information.
345345

346346
``db.settings``
347347
A property providing a `collections.MutableMapping` interface to the
@@ -1270,17 +1270,12 @@ Transaction Configuration
12701270
Keyword arguments given to ``xact()`` provide the means for configuring the
12711271
properties of the transaction. Only three points of configuration are available:
12721272

1273-
``gid``
1274-
The global identifier to use. Identifies the transaction as using two-phase
1275-
commit. The ``prepare()`` method *must* be called prior to ``commit()`` or
1276-
``__exit__()``. (**Deprecated**)
1277-
12781273
``isolation``
12791274
The isolation level of the transaction. This must be a string. It will be
12801275
interpolated directly into the START TRANSACTION statement. Normally,
12811276
'SERIALIZABLE' or 'READ COMMITTED':
12821277

1283-
>>> with db.xact(isolation = 'SERIALIZABLE'):
1278+
>>> with db.xact('SERIALIZABLE'):
12841279
... ...
12851280

12861281
``mode``
@@ -1311,14 +1306,6 @@ that change of state.
13111306

13121307
``x.rollback()``
13131308
Abort the transaction.
1314-
(Deprecated: For prepared transactions, this can be called at any phase.)
1315-
1316-
``x.recover()``
1317-
Identify the existence of the prepared transaction. (**Deprecated**)
1318-
1319-
``x.prepare()``
1320-
Prepare the transaction for the final commit. Once prepared, the second commit
1321-
may be ran to finalize the transaction, ``x.commit()``. (**Deprecated**)
13221309

13231310
These methods are primarily provided for applications that manage transactions
13241311
in a way that cannot be formed around single, sequential blocks of code.
@@ -1371,77 +1358,6 @@ error state. The distinction between the two cases is made using the ``source``
13711358
property on the raised exception.
13721359

13731360

1374-
Prepared Transactions
1375-
---------------------
1376-
1377-
.. warning::
1378-
**The two phase commit interfaces are being deprecated.**
1379-
**Use should be discontinued.**
1380-
1381-
Transactions configured with the ``gid`` keyword will require two steps to fully
1382-
commit the transaction. First, ``prepare()``, then ``commit()``. The prepare
1383-
method will issue the necessary PREPARE TRANSACTION statement, and commit will
1384-
finalize the operation with the issuance of the COMMIT PREPARED statement. At
1385-
any state of the transaction, ``rollback()`` may be used to abort the
1386-
transaction. If the transaction has yet to be prepared, it will issue the ABORT
1387-
statement, and if it has, it will issue ROLLBACK PREPARED instead.
1388-
1389-
Prepared transactions can be used with with-statements:
1390-
1391-
>>> with db.xact(gid='global-id') as gxact:
1392-
... ...
1393-
... gxact.prepare()
1394-
1395-
Transactions always call ``commit()`` on exit. This requires transaction objects
1396-
representing a prepared transaction to be prepared prior to the block's exit.
1397-
If the transaction is not prepared, the attempt to ``COMMIT PREPARED`` is still
1398-
made::
1399-
1400-
>>> with db.xact(gid='notprepared'):
1401-
... pass
1402-
...
1403-
Traceback (most recent call last):
1404-
...
1405-
postgresql.exceptions.ActiveTransactionError: COMMIT PREPARED cannot run inside a transaction block
1406-
CAUSE: The prepared transaction was not prepared prior to the block's exit.
1407-
CODE: 25001
1408-
SEVERITY: ERROR
1409-
LOCATION: File 'xact.c', line 2648, in PreventTransactionChain
1410-
1411-
1412-
When a prepared transaction is prepared, the transaction should be
1413-
rolled-back or committed at some point in time. It is possible
1414-
for a transaction to be prepared, but the connection lost before the final
1415-
commit or rollback. Cases where this occurs require a recovery operation to
1416-
determine the ultimate fate of the transaction.
1417-
1418-
In order to recover a prepared transaction, the ``recover()`` method can be
1419-
used:
1420-
1421-
>>> gxact = db.xact(gid='a-lost-transaction')
1422-
>>> gxact.recover()
1423-
1424-
Once recovered, it may then be committed or rolled-back using the appropriate
1425-
methods:
1426-
1427-
>>> gxact.commit()
1428-
1429-
When a transaction is recovered and the configured ``gid`` does not exist, the
1430-
driver will throw a `postgresql.exceptions.UndefinedObjectError`. This is
1431-
consistent with the error that is caused by ROLLBACK PREPARED and COMMIT
1432-
PREPARED when the global identifier does not exist.
1433-
1434-
>>> gxact = db.xact(gid='a-non-existing-gid')
1435-
>>> gxact.recover()
1436-
Traceback (most recent call last):
1437-
...
1438-
postgresql.exceptions.UndefinedObjectError: ...
1439-
1440-
This allows recovery operations to identify the existence of the prepared
1441-
transaction. Transaction managers should trap this exception in order to
1442-
determine how to proceed.
1443-
1444-
14451361
Settings
14461362
========
14471363

0 commit comments

Comments
 (0)