NAME
MongoDB::ClientSession - MongoDB session management
VERSION
version v1.999.0
SYNOPSIS
my $session = $client->start_session( $options );
# use session in operations
my $result = $collection->find( { id => 1 }, { session => $session } );DESCRIPTION
This class encapsulates an active session for use with the current client. Sessions support is new with MongoDB 3.6, and can be used in replica set and sharded MongoDB clusters.
Explicit and Implicit Sessions
If you specifically apply a session to an operation, then the operation will be performed with that session id. If you do not provide a session for an operation, and the server supports sessions, then an implicit session will be created and used for this operation.
The only exception to this is for unacknowledged writes - the driver will not provide an implicit session for this, and if you provide a session then the driver will raise an error.
Cursors
During cursors, if a session is not provided then an implicit session will be created which is then used for the lifetime of the cursor. If you provide a session, then note that ending the session and then continuing to use the cursor will raise an error.
Thread Safety
Sessions are NOT thread safe, and should only be used by one thread at a time. Using a session across multiple threads is unsupported and unexpected issues and errors may occur. Note that the driver does not check for multi-threaded use.
ATTRIBUTES
client
The client this session was created using. Sessions may only be used with the client that created them.
cluster_time
Stores the last received $clusterTime for the client session. This is an opaque value, to set it use the advance_cluster_time function.
options
Options provided for this particular session. Available options include:
causalConsistency- If true, will enable causalConsistency for this session. For more information, see MongoDB documentation on Causal Consistency. Note that causalConsistency does not apply for unacknowledged writes. Defaults to true.
operation_time
The last operation time. This is updated when an operation is performed during this session, or when "advance_operation_time" is called. Used for causal consistency.
METHODS
session_id
The session id for this particular session. This should be considered an opaque value. If end_session has been called, this returns undef.
get_latest_cluster_time
my $cluster_time = $session->get_latest_cluster_time;Returns the latest cluster time, when compared with this session's recorded cluster time and the main client cluster time. If neither is defined, returns undef.
advance_cluster_time
$session->advance_cluster_time( $cluster_time );Update the $clusterTime for this session. Stores the value in "cluster_time". If the cluster time provided is more recent than the sessions current cluster time, then the session will be updated to this provided value.
Setting the $clusterTime with a manually crafted value may cause a server error. It is reccomended to only use $clusterTime values retrieved from database calls.
advance_operation_time
$session->advance_operation_time( $operation_time );Update the "operation_time" for this session. If the value provided is more recent than the sessions current operation time, then the session will be updated to this provided value.
Setting operation_time with a manually crafted value may cause a server error. It is recommended to only use an operation_time retreived from another session or directly from a database call.
end_session
$session->end_session;Close this particular session and release the session ID for reuse or recycling. Has no effect after calling for the first time.
AUTHORS
David Golden <david@mongodb.com>
Rassi <rassi@mongodb.com>
Mike Friedman <friedo@friedo.com>
Kristina Chodorow <k.chodorow@gmail.com>
Florian Ragwitz <rafl@debian.org>
COPYRIGHT AND LICENSE
This software is Copyright (c) 2018 by MongoDB, Inc.
This is free software, licensed under:
The Apache License, Version 2.0, January 2004