1MongoDB::ClientSession(U3s)er Contributed Perl DocumentatMioonngoDB::ClientSession(3)
2
6 MongoDB::ClientSession - MongoDB session and transaction management
7
9 version v2.0.3
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 Sessions are NOT thread safe, and should only be used by one thread at
50 a time. Using a session across multiple threads is unsupported and
51 unexpected issues and errors may occur. Note that the driver does not
52 check for multi-threaded use.
53 Transactions
55 A session may be associated with at most one open transaction (on
56 MongoDB 4.0+). For detailed instructions on how to use transactions
57 with drivers, see the MongoDB manual page: Transactions
58 <https://docs.mongodb.com/master/core/transactions>.
59
61 client
62 The client this session was created using. Sessions may only be used
63 with the client that created them.
64 cluster_time
66 Stores the last received $clusterTime for the client session. This is
67 an opaque value, to set it use the advance_cluster_time function.
68 options
70 Options provided for this particular session. Available options
71 include:
72 · "causalConsistency" - If true, will enable causalConsistency for
74 this session. For more information, see MongoDB documentation on
75 Causal Consistency <https://docs.mongodb.com/manual/core/read-
76 isolation-consistency-recency/#causal-consistency>. Note that
77 causalConsistency does not apply for unacknowledged writes.
78 Defaults to true.
79 · "defaultTransactionOptions" - Options to use by default for
81 transactions created with this session. If when creating a
82 transaction, none or only some of the transaction options are
83 defined, these options will be used as a fallback. Defaults to
84 inheriting from the parent client. See "start_transaction" for
85 available options.
86 operation_time
88 The last operation time. This is updated when an operation is performed
89 during this session, or when "advance_operation_time" is called. Used
90 for causal consistency.
91
93 session_id
94 The session id for this particular session. This should be considered
95 an opaque value. If "end_session" has been called, this returns
96 "undef".
97 get_latest_cluster_time
99 my $cluster_time = $session->get_latest_cluster_time;
100 Returns the latest cluster time, when compared with this session's
102 recorded cluster time and the main client cluster time. If neither is
103 defined, returns undef.
104 advance_cluster_time
106 $session->advance_cluster_time( $cluster_time );
107 Update the $clusterTime for this session. Stores the value in
109 "cluster_time". If the cluster time provided is more recent than the
110 sessions current cluster time, then the session will be updated to this
111 provided value.
112 Setting the $clusterTime with a manually crafted value may cause a
114 server error. It is recommended to only use $clusterTime values
115 retrieved from database calls.
116 advance_operation_time
118 $session->advance_operation_time( $operation_time );
119 Update the "operation_time" for this session. If the value provided is
121 more recent than the sessions current operation time, then the session
122 will be updated to this provided value.
123 Setting "operation_time" with a manually crafted value may cause a
125 server error. It is recommended to only use an "operation_time"
126 retrieved from another session or directly from a database call.
127 start_transaction
129 $session->start_transaction;
130 $session->start_transaction( $options );
131 Start a transaction in this session. If a transaction is already in
133 progress or if the driver can detect that the client is connected to a
134 topology that does not support transactions, this method will throw an
135 error.
136 A hash reference of options may be provided. Valid keys include:
138 · "readConcern" - The read concern to use for the first command in
140 this transaction. If not defined here or in the
141 "defaultTransactionOptions" in "options", will inherit from the
142 parent client.
143 · "writeConcern" - The write concern to use for committing or
145 aborting this transaction. As per "readConcern", if not defined
146 here then the value defined in "defaultTransactionOptions" will be
147 used, or the parent client if not defined.
148 · "readPreference" - The read preference to use for all read
150 operations in this transaction. If not defined, then will inherit
151 from "defaultTransactionOptions" or from the parent client. This
152 value will override all other read preferences set in any
153 subsequent commands inside this transaction.
154 commit_transaction
156 $session->commit_transaction;
157 Commit the current transaction. This will use the writeConcern set on
159 this transaction.
160 If called when no transaction is in progress, then this method will
162 throw an error.
163 If the commit operation encounters an error, an error is thrown. If
165 the error is a transient commit error, the error object will have a
166 label containing "UnknownTransactionCommitResult" as an element and the
167 commit operation can be retried. This can be checked via the
168 "has_error_label":
169 LOOP: {
171 eval {
172 $session->commit_transaction;
173 };
174 if ( my $error = $@ ) {
175 if ( $error->has_error_label("UnknownTransactionCommitResult") ) {
176 redo LOOP;
177 }
178 else {
179 die $error;
180 }
181 }
182 }
183 abort_transaction
185 $session->abort_transaction;
186 Aborts the current transaction. If no transaction is in progress, then
188 this method will throw an error. Otherwise, this method will suppress
189 all other errors (including network and database errors).
190 end_session
192 $session->end_session;
193 Close this particular session and release the session ID for reuse or
195 recycling. If a transaction is in progress, it will be aborted. Has
196 no effect after calling for the first time.
197 This will be called automatically by the object destructor.
199
201 · David Golden <david@mongodb.com>
202 · Rassi <rassi@mongodb.com>
204 · Mike Friedman <friedo@friedo.com>
206 · Kristina Chodorow <k.chodorow@gmail.com>
208 · Florian Ragwitz <rafl@debian.org>
210
212 This software is Copyright (c) 2019 by MongoDB, Inc.
213 This is free software, licensed under:
215 The Apache License, Version 2.0, January 2004
217perl v5.28.1 2019-02-07 MongoDB::ClientSession(3)