l.s.d.t.DatabaseTransactionPolicy : class documentation

Part of lp.services.database.transaction_policy View In Hierarchy

Context manager for read-only transaction policy.

Use this to define regions of code that explicitly allow or disallow
changes to the database:

    # We want to be sure that inspect_data does not inadvertently
    # make any changes in the database, but we can't run it on the
    # slave store because it doesn't tolerate replication lag.
    with DatabaseTransactionPolicy(read_only=True):
        inspect_data()

The simplest way to use this is as a special transaction:
 * You must commit/abort before entering the policy.
 * Exiting the policy through an exception aborts its changes.
 * Before completing a read-write policy region, you must commit or abort.

You can also have multiple transactions inside one policy, however; the
policy still applies after a commit or abort.

Policies can be nested--a nested policy overrides the one it's nested in.
After the nested policy has exited, the previous policy applies again:

    # This code needs to control the database changes it makes very
    # carefully.  Most of it is just gathering data, with one quick
    # database update at the end.
    with DatabaseTransactionPolicy(read_only=True):
        data = gather_data()
        more_data = figure_stuff_out(data)

        # End the ongoing transaction so we can go into our update.
        transaction.commit()

        # This is the only part where we update the database!
        with DatabaseTransactionPolicy(read_only=False):
            update_model(data, more_data)
            transaction.commit()

        # We've got a bit more work to do here, but it doesn't
        # affect the database.
        write_logs(data)
        notify_user(more_data)