1MongoDB::ClientSession(U3s)er Contributed Perl DocumentatMioonngoDB::ClientSession(3)
2
3
4

NAME

6       MongoDB::ClientSession - MongoDB session and transaction management
7

VERSION

9       version v2.2.2
10

SYNOPSIS

12           my $session = $client->start_session( $options );
13
14           # use session in operations
15           my $result = $collection->find( { id => 1 }, { session => $session } );
16
17           # use sessions for transactions
18           $session->start_transaction;
19           ...
20           if ( $ok ) {
21               $session->commit_transaction;
22           }
23           else {
24               $session->abort_transaction;
25           }
26

DESCRIPTION

28       This class encapsulates an active session for use with the current
29       client.  Sessions support is new with MongoDB 3.6, and can be used in
30       replica set and sharded MongoDB clusters.
31
32   Explicit and Implicit Sessions
33       If you specifically apply a session to an operation, then the operation
34       will be performed with that session id. If you do not provide a session
35       for an operation, and the server supports sessions, then an implicit
36       session will be created and used for this operation.
37
38       The only exception to this is for unacknowledged writes - the driver
39       will not provide an implicit session for this, and if you provide a
40       session then the driver will raise an error.
41
42   Cursors
43       During cursors, if a session is not provided then an implicit session
44       will be created which is then used for the lifetime of the cursor. If
45       you provide a session, then note that ending the session and then
46       continuing to use the cursor will raise an error.
47
48   Thread Safety
49       NOTE: Per threads documentation, use of Perl threads is discouraged by
50       the maintainers of Perl and the MongoDB Perl driver does not test or
51       provide support for use with threads.
52
53       Sessions are NOT thread safe, and should only be used by one thread at
54       a time.  Using a session across multiple threads is unsupported and
55       unexpected issues and errors may occur. Note that the driver does not
56       check for multi-threaded use.
57
58   Transactions
59       A session may be associated with at most one open transaction (on
60       MongoDB 4.0+).  For detailed instructions on how to use transactions
61       with drivers, see the MongoDB manual page: Transactions
62       <https://docs.mongodb.com/master/core/transactions>.
63

ATTRIBUTES

65   client
66       The client this session was created using.  Sessions may only be used
67       with the client that created them.
68
69   cluster_time
70       Stores the last received $clusterTime for the client session. This is
71       an opaque value, to set it use the advance_cluster_time function.
72
73   options
74       Options provided for this particular session. Available options
75       include:
76
77       •   "causalConsistency" - If true, will enable causalConsistency for
78           this session. For more information, see MongoDB documentation on
79           Causal Consistency <https://docs.mongodb.com/manual/core/read-
80           isolation-consistency-recency/#causal-consistency>. Note that
81           causalConsistency does not apply for unacknowledged writes.
82           Defaults to true.
83
84       •   "defaultTransactionOptions" - Options to use by default for
85           transactions created with this session. If when creating a
86           transaction, none or only some of the transaction options are
87           defined, these options will be used as a fallback. Defaults to
88           inheriting from the parent client. See "start_transaction" for
89           available options.
90
91   operation_time
92       The last operation time. This is updated when an operation is performed
93       during this session, or when "advance_operation_time" is called. Used
94       for causal consistency.
95

METHODS

97   session_id
98       The session id for this particular session.  This should be considered
99       an opaque value.  If "end_session" has been called, this returns
100       "undef".
101
102   get_latest_cluster_time
103           my $cluster_time = $session->get_latest_cluster_time;
104
105       Returns the latest cluster time, when compared with this session's
106       recorded cluster time and the main client cluster time. If neither is
107       defined, returns undef.
108
109   advance_cluster_time
110           $session->advance_cluster_time( $cluster_time );
111
112       Update the $clusterTime for this session. Stores the value in
113       "cluster_time". If the cluster time provided is more recent than the
114       sessions current cluster time, then the session will be updated to this
115       provided value.
116
117       Setting the $clusterTime with a manually crafted value may cause a
118       server error. It is recommended to only use $clusterTime values
119       retrieved from database calls.
120
121   advance_operation_time
122           $session->advance_operation_time( $operation_time );
123
124       Update the "operation_time" for this session. If the value provided is
125       more recent than the sessions current operation time, then the session
126       will be updated to this provided value.
127
128       Setting "operation_time" with a manually crafted value may cause a
129       server error. It is recommended to only use an "operation_time"
130       retrieved from another session or directly from a database call.
131
132   start_transaction
133           $session->start_transaction;
134           $session->start_transaction( $options );
135
136       Start a transaction in this session.  If a transaction is already in
137       progress or if the driver can detect that the client is connected to a
138       topology that does not support transactions, this method will throw an
139       error.
140
141       A hash reference of options may be provided. Valid keys include:
142
143       •   "readConcern" - The read concern to use for the first command in
144           this transaction. If not defined here or in the
145           "defaultTransactionOptions" in "options", will inherit from the
146           parent client.
147
148       •   "writeConcern" - The write concern to use for committing or
149           aborting this transaction. As per "readConcern", if not defined
150           here then the value defined in "defaultTransactionOptions" will be
151           used, or the parent client if not defined.
152
153       •   "readPreference" - The read preference to use for all read
154           operations in this transaction. If not defined, then will inherit
155           from "defaultTransactionOptions" or from the parent client. This
156           value will override all other read preferences set in any
157           subsequent commands inside this transaction.
158
159       •   "maxCommitTimeMS" - The "maxCommitTimeMS" specifies a cumulative
160           time limit in milliseconds for processing operations on the cursor.
161           MongoDB interrupts the operation at the earliest following
162           interrupt point.
163
164   commit_transaction
165           $session->commit_transaction;
166
167       Commit the current transaction. This will use the writeConcern set on
168       this transaction.
169
170       If called when no transaction is in progress, then this method will
171       throw an error.
172
173       If the commit operation encounters an error, an error is thrown.  If
174       the error is a transient commit error, the error object will have a
175       label containing "UnknownTransactionCommitResult" as an element and the
176       commit operation can be retried.  This can be checked via the
177       "has_error_label":
178
179           LOOP: {
180               eval {
181                   $session->commit_transaction;
182               };
183               if ( my $error = $@ ) {
184                   if ( $error->has_error_label("UnknownTransactionCommitResult") ) {
185                       redo LOOP;
186                   }
187                   else {
188                       die $error;
189                   }
190               }
191           }
192
193   abort_transaction
194           $session->abort_transaction;
195
196       Aborts the current transaction.  If no transaction is in progress, then
197       this method will throw an error.  Otherwise, this method will suppress
198       all other errors (including network and database errors).
199
200   end_session
201           $session->end_session;
202
203       Close this particular session and release the session ID for reuse or
204       recycling.  If a transaction is in progress, it will be aborted.  Has
205       no effect after calling for the first time.
206
207       This will be called automatically by the object destructor.
208
209   with_transaction
210           $session->with_transaction($callback, $options);
211
212       Execute a callback in a transaction.
213
214       This method starts a transaction on this session, executes $callback,
215       and then commits the transaction, returning the return value of the
216       $callback.  The $callback will be executed at least once.
217
218       If the $callback throws an error, the transaction will be aborted. If
219       less than 120 seconds have passed since calling "with_transaction", and
220       the error has a "TransientTransactionError" label, the transaction will
221       be restarted and the callback will be executed again. Otherwise, the
222       error will be thrown.
223
224       If the $callback succeeds, then the transaction will be committed. If
225       an error is thrown from committing the transaction, and it is less than
226       120 seconds since calling "with_transaction", then:
227
228       •   If the error has a "TransientTransactionError" label, the
229           transaction will be restarted.
230
231       •   If the error has an "UnknownTransactionCommitResult" label, and is
232           not a "MaxTimeMSExpired" error, then the commit will be retried.
233
234       If the $callback aborts or commits the transaction, no other actions
235       are taken and the return value of the $callback is returned.
236
237       The callback is called with the first (and only) argument being the
238       session, after starting the transaction:
239
240           $session->with_transaction( sub {
241               # this is the same session as used for with_transaction
242               my $cb_session = shift;
243               ...
244           }, $options);
245
246       To pass arbitrary arguments to the $callback, wrap your callback in a
247       coderef:
248
249           $session->with_transaction(sub { $callback->($session, $foo, ...) }, $options);
250
251       Warning: you must either use the provided session within the callback,
252       or otherwise pass the session in use to the callback. You must pass the
253       $session as an option to all database operations that need to be
254       included in the transaction.
255
256       Warning: The $callback can be called multiple times, so it is
257       recommended to make it idempotent.
258
259       A hash reference of options may be provided. these are the same as for
260       "start_transaction".
261

AUTHORS

263       •   David Golden <david@mongodb.com>
264
265       •   Rassi <rassi@mongodb.com>
266
267       •   Mike Friedman <friedo@friedo.com>
268
269       •   Kristina Chodorow <k.chodorow@gmail.com>
270
271       •   Florian Ragwitz <rafl@debian.org>
272
274       This software is Copyright (c) 2020 by MongoDB, Inc.
275
276       This is free software, licensed under:
277
278         The Apache License, Version 2.0, January 2004
279
280
281
282perl v5.38.0                      2023-07-20         MongoDB::ClientSession(3)
Impressum