1MongoDB::ClientSession(U3s)er Contributed Perl DocumentatMioonngoDB::ClientSession(3)
2
6 MongoDB::ClientSession - MongoDB session and transaction management
7
9 version v2.2.2
10
12 my $session = $client->start_session( $options );
13 # use session in operations
15 my $result = $collection->find( { id => 1 }, { session => $session } );
16 # 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
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 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 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 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 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 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 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
65 client
66 The client this session was created using. Sessions may only be used
67 with the client that created them.
68 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 options
74 Options provided for this particular session. Available options
75 include:
76 • "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 • "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 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
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 get_latest_cluster_time
103 my $cluster_time = $session->get_latest_cluster_time;
104 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 advance_cluster_time
110 $session->advance_cluster_time( $cluster_time );
111 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 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 advance_operation_time
122 $session->advance_operation_time( $operation_time );
123 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 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 start_transaction
133 $session->start_transaction;
134 $session->start_transaction( $options );
135 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 A hash reference of options may be provided. Valid keys include:
142 • "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 • "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 • "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 • "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 commit_transaction
165 $session->commit_transaction;
166 Commit the current transaction. This will use the writeConcern set on
168 this transaction.
169 If called when no transaction is in progress, then this method will
171 throw an error.
172 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 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 abort_transaction
194 $session->abort_transaction;
195 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 end_session
201 $session->end_session;
202 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 This will be called automatically by the object destructor.
208 with_transaction
210 $session->with_transaction($callback, $options);
211 Execute a callback in a transaction.
213 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 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 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 • If the error has a "TransientTransactionError" label, the
229 transaction will be restarted.
230 • If the error has an "UnknownTransactionCommitResult" label, and is
232 not a "MaxTimeMSExpired" error, then the commit will be retried.
233 If the $callback aborts or commits the transaction, no other actions
235 are taken and the return value of the $callback is returned.
236 The callback is called with the first (and only) argument being the
238 session, after starting the transaction:
239 $session->with_transaction( sub {
241 # this is the same session as used for with_transaction
242 my $cb_session = shift;
243 ...
244 }, $options);
245 To pass arbitrary arguments to the $callback, wrap your callback in a
247 coderef:
248 $session->with_transaction(sub { $callback->($session, $foo, ...) }, $options);
250 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 Warning: The $callback can be called multiple times, so it is
257 recommended to make it idempotent.
258 A hash reference of options may be provided. these are the same as for
260 "start_transaction".
261
263 • David Golden <david@mongodb.com>
264 • Rassi <rassi@mongodb.com>
266 • Mike Friedman <friedo@friedo.com>
268 • Kristina Chodorow <k.chodorow@gmail.com>
270 • Florian Ragwitz <rafl@debian.org>
272
274 This software is Copyright (c) 2020 by MongoDB, Inc.
275 This is free software, licensed under:
277 The Apache License, Version 2.0, January 2004
279perl v5.38.0 2023-07-20 MongoDB::ClientSession(3)