{ "content": [ { "type": "text", "text": "# MongoDB::ClientSession (perldoc)\n\n## NAME\n\nMongoDB::ClientSession - MongoDB session and transaction management\n\n## SYNOPSIS\n\nmy $session = $client->startsession( $options );\n# use session in operations\nmy $result = $collection->find( { id => 1 }, { session => $session } );\n# use sessions for transactions\n$session->starttransaction;\n...\nif ( $ok ) {\n$session->committransaction;\n}\nelse {\n$session->aborttransaction;\n}\n\n## DESCRIPTION\n\nThis class encapsulates an active session for use with the current client. Sessions support is\nnew with MongoDB 3.6, and can be used in replica set and sharded MongoDB clusters.\n\n## Sections\n\n- **NAME**\n- **VERSION**\n- **SYNOPSIS**\n- **DESCRIPTION** (4 subsections)\n- **ATTRIBUTES**\n- **METHODS**\n- **AUTHORS**\n- **COPYRIGHT AND LICENSE**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "MongoDB::ClientSession", "section": "", "mode": "perldoc", "summary": "MongoDB::ClientSession - MongoDB session and transaction management", "synopsis": "my $session = $client->startsession( $options );\n# use session in operations\nmy $result = $collection->find( { id => 1 }, { session => $session } );\n# use sessions for transactions\n$session->starttransaction;\n...\nif ( $ok ) {\n$session->committransaction;\n}\nelse {\n$session->aborttransaction;\n}", "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [], "examples": [], "see_also": [], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "VERSION", "lines": 2, "subsections": [] }, { "name": "SYNOPSIS", "lines": 15, "subsections": [] }, { "name": "DESCRIPTION", "lines": 3, "subsections": [ { "name": "Explicit and Implicit Sessions", "lines": 7 }, { "name": "Cursors", "lines": 4 }, { "name": "Thread Safety", "lines": 7 }, { "name": "Transactions", "lines": 4 } ] }, { "name": "ATTRIBUTES", "lines": 25, "subsections": [] }, { "name": "METHODS", "lines": 145, "subsections": [] }, { "name": "AUTHORS", "lines": 10, "subsections": [] }, { "name": "COPYRIGHT AND LICENSE", "lines": 6, "subsections": [] } ], "sections": { "NAME": { "content": "MongoDB::ClientSession - MongoDB session and transaction management\n", "subsections": [] }, "VERSION": { "content": "version v2.2.2\n", "subsections": [] }, "SYNOPSIS": { "content": "my $session = $client->startsession( $options );\n\n# use session in operations\nmy $result = $collection->find( { id => 1 }, { session => $session } );\n\n# use sessions for transactions\n$session->starttransaction;\n...\nif ( $ok ) {\n$session->committransaction;\n}\nelse {\n$session->aborttransaction;\n}\n", "subsections": [] }, "DESCRIPTION": { "content": "This class encapsulates an active session for use with the current client. Sessions support is\nnew with MongoDB 3.6, and can be used in replica set and sharded MongoDB clusters.\n", "subsections": [ { "name": "Explicit and Implicit Sessions", "content": "If you specifically apply a session to an operation, then the operation will be performed with\nthat session id. If you do not provide a session for an operation, and the server supports\nsessions, then an implicit session will be created and used for this operation.\n\nThe only exception to this is for unacknowledged writes - the driver will not provide an\nimplicit session for this, and if you provide a session then the driver will raise an error.\n" }, { "name": "Cursors", "content": "During cursors, if a session is not provided then an implicit session will be created which is\nthen used for the lifetime of the cursor. If you provide a session, then note that ending the\nsession and then continuing to use the cursor will raise an error.\n" }, { "name": "Thread Safety", "content": "NOTE: Per threads documentation, use of Perl threads is discouraged by the maintainers of Perl\nand the MongoDB Perl driver does not test or provide support for use with threads.\n\nSessions are NOT thread safe, and should only be used by one thread at a time. Using a session\nacross multiple threads is unsupported and unexpected issues and errors may occur. Note that the\ndriver does not check for multi-threaded use.\n" }, { "name": "Transactions", "content": "A session may be associated with at most one open transaction (on MongoDB 4.0+). For detailed\ninstructions on how to use transactions with drivers, see the MongoDB manual page: Transactions\n.\n" } ] }, "ATTRIBUTES": { "content": "client\nThe client this session was created using. Sessions may only be used with the client that\ncreated them.\n\nclustertime\nStores the last received $clusterTime for the client session. This is an opaque value, to set it\nuse the advanceclustertime function.\n\noptions\nOptions provided for this particular session. Available options include:\n\n* \"causalConsistency\" - If true, will enable causalConsistency for this session. For more\ninformation, see MongoDB documentation on Causal Consistency\n. Note that causalConsistency does not apply for unacknowledged writes. Defaults to true.\n\n* \"defaultTransactionOptions\" - Options to use by default for transactions created with this\nsession. If when creating a transaction, none or only some of the transaction options are\ndefined, these options will be used as a fallback. Defaults to inheriting from the parent\nclient. See \"starttransaction\" for available options.\n\noperationtime\nThe last operation time. This is updated when an operation is performed during this session, or\nwhen \"advanceoperationtime\" is called. Used for causal consistency.\n", "subsections": [] }, "METHODS": { "content": "sessionid\nThe session id for this particular session. This should be considered an opaque value. If\n\"endsession\" has been called, this returns \"undef\".\n\ngetlatestclustertime\nmy $clustertime = $session->getlatestclustertime;\n\nReturns the latest cluster time, when compared with this session's recorded cluster time and the\nmain client cluster time. If neither is defined, returns undef.\n\nadvanceclustertime\n$session->advanceclustertime( $clustertime );\n\nUpdate the $clusterTime for this session. Stores the value in \"clustertime\". If the cluster\ntime provided is more recent than the sessions current cluster time, then the session will be\nupdated to this provided value.\n\nSetting the $clusterTime with a manually crafted value may cause a server error. It is\nrecommended to only use $clusterTime values retrieved from database calls.\n\nadvanceoperationtime\n$session->advanceoperationtime( $operationtime );\n\nUpdate the \"operationtime\" for this session. If the value provided is more recent than the\nsessions current operation time, then the session will be updated to this provided value.\n\nSetting \"operationtime\" with a manually crafted value may cause a server error. It is\nrecommended to only use an \"operationtime\" retrieved from another session or directly from a\ndatabase call.\n\nstarttransaction\n$session->starttransaction;\n$session->starttransaction( $options );\n\nStart a transaction in this session. If a transaction is already in progress or if the driver\ncan detect that the client is connected to a topology that does not support transactions, this\nmethod will throw an error.\n\nA hash reference of options may be provided. Valid keys include:\n\n* \"readConcern\" - The read concern to use for the first command in this transaction. If not\ndefined here or in the \"defaultTransactionOptions\" in \"options\", will inherit from the\nparent client.\n\n* \"writeConcern\" - The write concern to use for committing or aborting this transaction. As\nper \"readConcern\", if not defined here then the value defined in \"defaultTransactionOptions\"\nwill be used, or the parent client if not defined.\n\n* \"readPreference\" - The read preference to use for all read operations in this transaction.\nIf not defined, then will inherit from \"defaultTransactionOptions\" or from the parent\nclient. This value will override all other read preferences set in any subsequent commands\ninside this transaction.\n\n* \"maxCommitTimeMS\" - The \"maxCommitTimeMS\" specifies a cumulative time limit in milliseconds\nfor processing operations on the cursor. MongoDB interrupts the operation at the earliest\nfollowing interrupt point.\n\ncommittransaction\n$session->committransaction;\n\nCommit the current transaction. This will use the writeConcern set on this transaction.\n\nIf called when no transaction is in progress, then this method will throw an error.\n\nIf the commit operation encounters an error, an error is thrown. If the error is a transient\ncommit error, the error object will have a label containing \"UnknownTransactionCommitResult\" as\nan element and the commit operation can be retried. This can be checked via the\n\"haserrorlabel\":\n\nLOOP: {\neval {\n$session->committransaction;\n};\nif ( my $error = $@ ) {\nif ( $error->haserrorlabel(\"UnknownTransactionCommitResult\") ) {\nredo LOOP;\n}\nelse {\ndie $error;\n}\n}\n}\n\naborttransaction\n$session->aborttransaction;\n\nAborts the current transaction. If no transaction is in progress, then this method will throw an\nerror. Otherwise, this method will suppress all other errors (including network and database\nerrors).\n\nendsession\n$session->endsession;\n\nClose this particular session and release the session ID for reuse or recycling. If a\ntransaction is in progress, it will be aborted. Has no effect after calling for the first time.\n\nThis will be called automatically by the object destructor.\n\nwithtransaction\n$session->withtransaction($callback, $options);\n\nExecute a callback in a transaction.\n\nThis method starts a transaction on this session, executes $callback, and then commits the\ntransaction, returning the return value of the $callback. The $callback will be executed at\nleast once.\n\nIf the $callback throws an error, the transaction will be aborted. If less than 120 seconds have\npassed since calling \"withtransaction\", and the error has a \"TransientTransactionError\" label,\nthe transaction will be restarted and the callback will be executed again. Otherwise, the error\nwill be thrown.\n\nIf the $callback succeeds, then the transaction will be committed. If an error is thrown from\ncommitting the transaction, and it is less than 120 seconds since calling \"withtransaction\",\nthen:\n\n* If the error has a \"TransientTransactionError\" label, the transaction will be restarted.\n\n* If the error has an \"UnknownTransactionCommitResult\" label, and is not a \"MaxTimeMSExpired\"\nerror, then the commit will be retried.\n\nIf the $callback aborts or commits the transaction, no other actions are taken and the return\nvalue of the $callback is returned.\n\nThe callback is called with the first (and only) argument being the session, after starting the\ntransaction:\n\n$session->withtransaction( sub {\n# this is the same session as used for withtransaction\nmy $cbsession = shift;\n...\n}, $options);\n\nTo pass arbitrary arguments to the $callback, wrap your callback in a coderef:\n\n$session->withtransaction(sub { $callback->($session, $foo, ...) }, $options);\n\nWarning: you must either use the provided session within the callback, or otherwise pass the\nsession in use to the callback. You must pass the $session as an option to all database\noperations that need to be included in the transaction.\n\nWarning: The $callback can be called multiple times, so it is recommended to make it idempotent.\n\nA hash reference of options may be provided. these are the same as for \"starttransaction\".\n", "subsections": [] }, "AUTHORS": { "content": "* David Golden \n\n* Rassi \n\n* Mike Friedman \n\n* Kristina Chodorow \n\n* Florian Ragwitz \n", "subsections": [] }, "COPYRIGHT AND LICENSE": { "content": "This software is Copyright (c) 2020 by MongoDB, Inc.\n\nThis is free software, licensed under:\n\nThe Apache License, Version 2.0, January 2004\n", "subsections": [] } } } }