python-transaction 1.1.1-2 / usr / share / pyshared / transaction / tests / savepoint.txt

Savepoints
==========

Savepoints provide a way to save to disk intermediate work done during
a transaction allowing:

- partial transaction (subtransaction) rollback (abort)

- state of saved objects to be freed, freeing on-line memory for other
  uses

Savepoints make it possible to write atomic subroutines that don't
make top-level transaction commitments.


Applications
------------

To demonstrate how savepoints work with transactions, we've provided a sample
data manager implementation that provides savepoint support.  The primary
purpose of this data manager is to provide code that can be read to understand
how savepoints work.  The secondary purpose is to provide support for
demonstrating the correct operation of savepoint support within the
transaction system.  This data manager is very simple.  It provides flat
storage of named immutable values, like strings and numbers.

    >>> import transaction
    >>> from transaction.tests import savepointsample
    >>> dm = savepointsample.SampleSavepointDataManager()
    >>> dm['name'] = 'bob'

As with other data managers, we can commit changes:

    >>> transaction.commit()
    >>> dm['name']
    'bob'

and abort changes:

    >>> dm['name'] = 'sally'
    >>> dm['name']
    'sally'
    >>> transaction.abort()
    >>> dm['name']
    'bob'

Now, let's look at an application that manages funds for people.  It allows
deposits and debits to be entered for multiple people.  It accepts a sequence
of entries and generates a sequence of status messages.  For each entry, it
applies the change and then validates the user's account.  If the user's
account is invalid, we roll back the change for that entry.  The success or
failure of an entry is indicated in the output status.  First we'll initialize
some accounts:

    >>> dm['bob-balance'] = 0.0
    >>> dm['bob-credit'] = 0.0
    >>> dm['sally-balance'] = 0.0
    >>> dm['sally-credit'] = 100.0
    >>> transaction.commit()

Now, we'll define a validation function to validate an account:

    >>> def validate_account(name):
    ...     if dm[name+'-balance'] + dm[name+'-credit'] < 0:
    ...         raise ValueError('Overdrawn', name)

And a function to apply entries.  If the function fails in some unexpected
way, it rolls back all of its changes and prints the error:

    >>> def apply_entries(entries):
    ...     savepoint = transaction.savepoint()
    ...     try:
    ...         for name, amount in entries:
    ...             entry_savepoint = transaction.savepoint()
    ...             try:
    ...                 dm[name+'-balance'] += amount
    ...                 validate_account(name)
    ...             except ValueError, error:
    ...                 entry_savepoint.rollback()
    ...                 print 'Error', str(error)
    ...             else:
    ...                 print 'Updated', name
    ...     except Exception, error:
    ...         savepoint.rollback()
    ...         print 'Unexpected exception', error

Now let's try applying some entries:

    >>> apply_entries([
    ...     ('bob',   10.0),
    ...     ('sally', 10.0),
    ...     ('bob',   20.0),
    ...     ('sally', 10.0),
    ...     ('bob',   -100.0),
    ...     ('sally', -100.0),
    ...     ])
    Updated bob
    Updated sally
    Updated bob
    Updated sally
    Error ('Overdrawn', 'bob')
    Updated sally

    >>> dm['bob-balance']
    30.0

    >>> dm['sally-balance']
    -80.0

If we provide entries that cause an unexpected error:

    >>> apply_entries([
    ...     ('bob',   10.0),
    ...     ('sally', 10.0),
    ...     ('bob',   '20.0'),
    ...     ('sally', 10.0),
    ...     ])
    Updated bob
    Updated sally
    Unexpected exception unsupported operand type(s) for +=: 'float' and 'str'

Because the apply_entries used a savepoint for the entire function, it was
able to rollback the partial changes without rolling back changes made in the
previous call to ``apply_entries``:

    >>> dm['bob-balance']
    30.0

    >>> dm['sally-balance']
    -80.0

If we now abort the outer transactions, the earlier changes will go
away:

    >>> transaction.abort()

    >>> dm['bob-balance']
    0.0

    >>> dm['sally-balance']
    0.0

Savepoint invalidation
----------------------

A savepoint can be used any number of times:

    >>> dm['bob-balance'] = 100.0
    >>> dm['bob-balance']
    100.0
    >>> savepoint = transaction.savepoint()

    >>> dm['bob-balance'] = 200.0
    >>> dm['bob-balance']
    200.0
    >>> savepoint.rollback()
    >>> dm['bob-balance']
    100.0

    >>> savepoint.rollback()  # redundant, but should be harmless
    >>> dm['bob-balance']
    100.0

    >>> dm['bob-balance'] = 300.0
    >>> dm['bob-balance']
    300.0
    >>> savepoint.rollback()
    >>> dm['bob-balance']
    100.0

However, using a savepoint invalidates any savepoints that come after it:

    >>> dm['bob-balance'] = 200.0
    >>> dm['bob-balance']
    200.0
    >>> savepoint1 = transaction.savepoint()

    >>> dm['bob-balance'] = 300.0
    >>> dm['bob-balance']
    300.0
    >>> savepoint2 = transaction.savepoint()

    >>> savepoint.rollback()
    >>> dm['bob-balance']
    100.0

    >>> savepoint2.rollback()
    Traceback (most recent call last):
    ...
    InvalidSavepointRollbackError

    >>> savepoint1.rollback()
    Traceback (most recent call last):
    ...
    InvalidSavepointRollbackError

    >>> transaction.abort()


Databases without savepoint support
-----------------------------------

Normally it's an error to use savepoints with databases that don't support
savepoints:

    >>> dm_no_sp = savepointsample.SampleDataManager()
    >>> dm_no_sp['name'] = 'bob'
    >>> transaction.commit()
    >>> dm_no_sp['name'] = 'sally'
    >>> savepoint = transaction.savepoint()
    Traceback (most recent call last):
    ...
    TypeError: ('Savepoints unsupported', {'name': 'bob'})

    >>> transaction.abort()

However, a flag can be passed to the transaction savepoint method to indicate
that databases without savepoint support should be tolerated until a savepoint
is rolled back.  This allows transactions to proceed if there are no reasons
to roll back:

    >>> dm_no_sp['name'] = 'sally'
    >>> savepoint = transaction.savepoint(1)
    >>> dm_no_sp['name'] = 'sue'
    >>> transaction.commit()
    >>> dm_no_sp['name']
    'sue'

    >>> dm_no_sp['name'] = 'sam'
    >>> savepoint = transaction.savepoint(1)
    >>> savepoint.rollback()
    Traceback (most recent call last):
    ...
    TypeError: ('Savepoints unsupported', {'name': 'sam'})


Failures
--------

If a failure occurs when creating or rolling back a savepoint, the transaction
state will be uncertain and the transaction will become uncommitable.  From
that point on, most transaction operations, including commit, will fail until
the transaction is aborted.

In the previous example, we got an error when we tried to rollback the
savepoint.  If we try to commit the transaction, the commit will fail:

    >>> transaction.commit() # doctest: +ELLIPSIS
    Traceback (most recent call last):
    ...
    TransactionFailedError: An operation previously failed, with traceback:
    ...
    TypeError: ('Savepoints unsupported', {'name': 'sam'})
    <BLANKLINE>

We have to abort it to make any progress:

    >>> transaction.abort()

Similarly, in our earlier example, where we tried to take a savepoint with a
data manager that didn't support savepoints:

    >>> dm_no_sp['name'] = 'sally'
    >>> dm['name'] = 'sally'
    >>> savepoint = transaction.savepoint()
    Traceback (most recent call last):
    ...
    TypeError: ('Savepoints unsupported', {'name': 'sue'})

    >>> transaction.commit() # doctest: +ELLIPSIS
    Traceback (most recent call last):
    ...
    TransactionFailedError: An operation previously failed, with traceback:
    ...
    TypeError: ('Savepoints unsupported', {'name': 'sue'})
    <BLANKLINE>

    >>> transaction.abort()

After clearing the transaction with an abort, we can get on with new
transactions:

    >>> dm_no_sp['name'] = 'sally'
    >>> dm['name'] = 'sally'
    >>> transaction.commit()
    >>> dm_no_sp['name']
    'sally'
    >>> dm['name']
    'sally'