1DBIx::Class::OptimisticULsoecrkiCnogn(t3r)ibuted Perl DoDcBuImxe:n:tCaltaisosn::OptimisticLocking(3)
2
3
4

NAME

6       DBIx::Class::OptimisticLocking - Optimistic locking support for
7       DBIx::Class
8

VERSION

10       version 0.02
11

SYNOPSIS

13       This module allows the user to utilize optimistic locking when updating
14       a row.
15
16       Example usage:
17
18               package DB::Main::Orders;
19
20               use base qw/DBIx::Class/;
21
22               __PACKAGE__->load_components(qw/OptimisticLocking Core/);
23
24               __PACKAGE__->optimistic_locking_strategy('dirty'); # this is the default behavior
25

PURPOSE

27       Optimistic locking is an alternative to using exclusive locks when you
28       have the possibility of concurrent, conflicting updates in your
29       database.  The basic principle is you allow any and all clients to
30       issue updates and rather than preemptively synchronizing all data
31       modifications (which is what happens with exclusive locks) you are
32       "optimistic" that updates won't interfere with one another and the
33       updates will only fail when they do in fact interfere with one another.
34
35       Consider the following scenario (in timeline order, not in the same
36       block of code):
37
38               my $order = $schema->resultset('Orders')->find(1);
39
40               # some other different, concurrent process loads the same object
41               my $other_order = $schema->resultset('Orders')->find(1);
42
43               $order->status('fraud review');
44               $other_order->status('processed');
45
46               $order->update; # this succeeds
47               $other_order->update; # this fails when using optimistic locking
48
49       Without locking (optimistic or exclusive ), the example order would
50       have two sequential updates issued with the second essentially erasing
51       the results of the first.  With optimistic locking, the second update
52       (on $other_order) would fail.
53
54       This optimistic locking is typically done by adding additional
55       restrictions to the "WHERE" clause of the "UPDATE" statement.  These
56       additional restrictions ensure the data is still in the expected state
57       before applying the update.  This DBIx::Class::OptimisticLocking
58       component provides a few different strategies for providing this
59       functionality.
60

CONFIGURATION

62   optimistic_locking_strategy
63       This configuration controls the main functionality of this component.
64       The current recognized optimistic locking modes supported are:
65
66       •   dirty
67
68           When issuing an update, the "WHERE" clause of the update will
69           include all of the original values of the columns that are being
70           updated.  Any columns that are not being updated will be ignored.
71
72       •   version
73
74           When issuing an update, the "WHERE" clause of the update will
75           include a check of the "version" column (or otherwise configured
76           column using optimistic_locking_version_column).  The "version"
77           column will also be incremented on each update as well.  The
78           exception is if all of the updated columns are in the
79           optimistic_locking_ignore_columns configuration.
80
81       •   all
82
83           When issuing an update, the "WHERE" clause of the update will
84           include a check on each column in the object regardless of whether
85           they were updated or not.
86
87       •   none (or any other value)
88
89           This turns off the functionality of this component.  But why would
90           you load it if you don't need it? :-)
91
92   optimistic_locking_ignore_columns
93       Occassionally you may elect to ignore certain columns that are not
94       significant enough to detect colisions and cause the update to fail.
95       For instance, if you have a timestamp column, you may want to add that
96       to this list so that it is ignored when generating the "UPDATE" where
97       clause for the update.
98
99   optimistic_locking_version_column
100       If you are using 'version' as your optimistic_locking_strategy, you can
101       optionally specify a different name for the column used for version
102       tracking.  If an alternate name is not passed, the component will look
103       for a column named "version" in your model.
104

EXTENDED METHODS

106   update
107       See DBIx::Class::Row::update for basic usage.
108
109       Before issuing the actual update, this component injects additional
110       criteria that will be used in the "WHERE" clause in the "UPDATE". The
111       criteria that is used depends on the CONFIGURATION defined in the model
112       class.
113
114   _track_storage_value
115       This is a method internal to DBIx::Class::Row that basically serves as
116       a predicate method that indicates whether or not the orginal value of
117       the row (as loaded from storage) should be recorded when it is updated.
118
119       Typically, only primary key values are persisted but for
120       DBIx::Class::OptimisticLocking, this list is augmented to include other
121       columns based on the optimistic locking strategy that is configured for
122       this DBIx::Class::ResultSource.  For instance, if the chosen strategy
123       is '"dirty"' (the default), every column's original value will be
124       tracked in order to generate the appropriate "WHERE" clause in any
125       subsequent "UPDATE" operations.
126
127   _storage_ident_condition
128       This is an internal method to DBIx::Class::PK that generates the
129       "WHERE" clause for update and delete operations.
130

BUGS

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

SUPPORT

140       You can find documentation for this module with the perldoc command.
141
142           perldoc DBIx::Class::OptimisticLocking
143

ACKNOWLEDGEMENTS

145       Credit goes to the Java ORM package Hibernate <http://hibernate.org>
146       for inspiring me to write this for DBIx::Class.
147

AUTHOR

149         Brian Phillips <bphillips@cpan.org>
150
152       This software is copyright (c) 2011 by Brian Phillips.
153
154       This is free software; you can redistribute it and/or modify it under
155       the same terms as the Perl 5 programming language system itself.
156
157
158
159perl v5.34.0                      2021-07-22 DBIx::Class::OptimisticLocking(3)
Impressum