View on
MetaCPAN
Brian Phillips > DBIx-Class-OptimisticLocking-0.02 > DBIx::Class::OptimisticLocking

Download:
DBIx-Class-OptimisticLocking-0.02.tar.gz

Dependencies

Annotate this POD

CPAN RT

New  1
Open  0
View/Report Bugs
Module Version: 0.02   Source  

NAME ^

DBIx::Class::OptimisticLocking - Optimistic locking support for DBIx::Class

VERSION ^

version 0.02

SYNOPSIS ^

This module allows the user to utilize optimistic locking when updating a row.

Example usage:

        package DB::Main::Orders;

        use base qw/DBIx::Class/;

        __PACKAGE__->load_components(qw/OptimisticLocking Core/);

        __PACKAGE__->optimistic_locking_strategy('dirty'); # this is the default behavior

PURPOSE ^

Optimistic locking is an alternative to using exclusive locks when you have the possibility of concurrent, conflicting updates in your database. The basic principle is you allow any and all clients to issue updates and rather than preemptively synchronizing all data modifications (which is what happens with exclusive locks) you are "optimistic" that updates won't interfere with one another and the updates will only fail when they do in fact interfere with one another.

Consider the following scenario (in timeline order, not in the same block of code):

        my $order = $schema->resultset('Orders')->find(1);

        # some other different, concurrent process loads the same object
        my $other_order = $schema->resultset('Orders')->find(1);

        $order->status('fraud review');
        $other_order->status('processed');

        $order->update; # this succeeds
        $other_order->update; # this fails when using optimistic locking

Without locking (optimistic or exclusive ), the example order would have two sequential updates issued with the second essentially erasing the results of the first. With optimistic locking, the second update (on $other_order) would fail.

This optimistic locking is typically done by adding additional restrictions to the WHERE clause of the UPDATE statement. These additional restrictions ensure the data is still in the expected state before applying the update. This DBIx::Class::OptimisticLocking component provides a few different strategies for providing this functionality.

CONFIGURATION ^

optimistic_locking_strategy

This configuration controls the main functionality of this component. The current recognized optimistic locking modes supported are:

optimistic_locking_ignore_columns

Occassionally you may elect to ignore certain columns that are not significant enough to detect colisions and cause the update to fail. For instance, if you have a timestamp column, you may want to add that to this list so that it is ignored when generating the UPDATE where clause for the update.

optimistic_locking_version_column

If you are using 'version' as your optimistic_locking_strategy, you can optionally specify a different name for the column used for version tracking. If an alternate name is not passed, the component will look for a column named version in your model.

EXTENDED METHODS ^

update

See DBIx::Class::Row::update for basic usage.

Before issuing the actual update, this component injects additional criteria that will be used in the WHERE clause in the UPDATE. The criteria that is used depends on the CONFIGURATION defined in the model class.

_track_storage_value

This is a method internal to DBIx::Class::Row that basically serves as a predicate method that indicates whether or not the orginal value of the row (as loaded from storage) should be recorded when it is updated.

Typically, only primary key values are persisted but for DBIx::Class::OptimisticLocking, this list is augmented to include other columns based on the optimistic locking strategy that is configured for this DBIx::Class::ResultSource. For instance, if the chosen strategy is 'dirty' (the default), every column's original value will be tracked in order to generate the appropriate WHERE clause in any subsequent UPDATE operations.

_storage_ident_condition

This is an internal method to DBIx::Class::PK that generates the WHERE clause for update and delete operations.

BUGS ^

Please report any bugs or feature requests to bug-dbix-class-optimisticlocking at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=DBIx-Class-OptimisticLocking. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT ^

You can find documentation for this module with the perldoc command.

    perldoc DBIx::Class::OptimisticLocking

ACKNOWLEDGEMENTS ^

Credit goes to the Java ORM package Hibernate for inspiring me to write this for DBIx::Class.

AUTHOR ^

  Brian Phillips <bphillips@cpan.org>

COPYRIGHT AND LICENSE ^

This software is copyright (c) 2011 by Brian Phillips.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

syntax highlighting: