Skip to content

Commit 17074d6

Browse files
rustagirrustagir
authored
Merge pull request #137 from rustagir/DOCSP-41995-txn
DOCSP-41995: transaction
2 parents c14727a + baf5e13 commit 17074d6

File tree

3 files changed

+259
-0
lines changed

3 files changed

+259
-0
lines changed

‎source/includes/write/transaction.php

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
<?php
2+
require 'vendor/autoload.php';
3+
4+
$uri = getenv('MONGODB_URI') ?: throw new RuntimeException('Set the MONGODB_URI variable to your connection URI');
5+
$client = new MongoDB\Client($uri);
6+
7+
// begin-callback
8+
$receipts = $client->bank->receipts;
9+
$checking = $client->bank->checking_accounts;
10+
$saving = $client->bank->saving_accounts;
11+
12+
$accountId = "5678";
13+
$transferAmount = 1000.0;
14+
15+
$callback = function (MongoDB\Driver\Session $session) use (
16+
$checking,
17+
$saving,
18+
$receipts,
19+
$accountId,
20+
$transferAmount
21+
): void {
22+
$checking->updateOne(
23+
["account_id" => $accountId],
24+
['$inc' => ["balance" => -$transferAmount]],
25+
["session" => $session]
26+
);
27+
28+
$saving->updateOne(
29+
["account_id" => $accountId],
30+
['$inc' => ["balance" => $transferAmount]],
31+
["session" => $session]
32+
);
33+
34+
$summary = sprintf('SAVINGS +%1$u CHECKING -%1$u', $transferAmount);
35+
36+
$receipts->insertOne(
37+
[
38+
"account_id" => $accountId,
39+
"summary" => $summary,
40+
"timestamp" => new MongoDB\BSON\UTCDateTime(),
41+
],
42+
["session" => $session]
43+
);
44+
45+
echo "Successfully performed transaction!", PHP_EOL;
46+
echo "Summary: ", $summary, PHP_EOL;
47+
};
48+
// end-callback
49+
50+
// begin-txn
51+
$session = $client->startSession();
52+
53+
try {
54+
MongoDB\with_transaction($session, $callback);
55+
} catch (MongoDB\Driver\Exception\RuntimeException $e) {
56+
echo "Caught exception: ", $e->getMessage(), PHP_EOL;
57+
}
58+
// end-txn

‎source/write.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,7 @@ Write Data to MongoDB
2727
/write/delete
2828
/write/replace
2929
/write/bulk-write
30+
/write/transaction
3031
/write/gridfs
3132

3233
Overview

‎source/write/transaction.txt

Lines changed: 200 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,200 @@
1+
.. _php-transactions:
2+
3+
=====================
4+
Perform a Transaction
5+
=====================
6+
7+
.. facet::
8+
:name: genre
9+
:values: reference
10+
11+
.. meta::
12+
:keywords: code example, ACID compliance, multi-document
13+
14+
.. contents:: On this page
15+
:local:
16+
:backlinks: none
17+
:depth: 2
18+
:class: singlecol
19+
20+
Overview
21+
--------
22+
23+
In this guide, you can learn how to use the {+php-library+} to perform
24+
**transactions**. Transactions allow you to perform a series of operations
25+
that change data only if the entire transaction is committed.
26+
If any operation in the transaction does not succeed, the library stops the
27+
transaction and discards all data changes before they ever become
28+
visible. This feature is called **atomicity**.
29+
30+
In MongoDB, transactions run within logical sessions. A
31+
session is a grouping of related read or write operations that you
32+
want to run sequentially. Sessions enable causal consistency for a group
33+
of operations and allow you to run operations in an **ACID-compliant**
34+
transaction, which is a transaction that meets an expectation of
35+
atomicity, consistency, isolation, and durability. MongoDB guarantees
36+
that the data involved in your transaction operations remains
37+
consistent, even if the operations encounter unexpected errors.
38+
39+
When using the {+php-library+}, you can create a new session from a
40+
``MongoDB\Client`` instance. Then, you can use the resulting
41+
``MongoDB\Driver\Session`` instance to perform transactions.
42+
43+
.. warning::
44+
45+
Use a ``Session`` only in operations running on the
46+
``Client`` that created it. Using a ``Session`` with a
47+
different ``Client`` results in operation errors.
48+
49+
Transaction APIs
50+
----------------
51+
52+
In this section, you can learn about the transaction APIs provided by
53+
the {+php-library+}. Before you begin a transaction, you must create a
54+
``Session`` by using the ``MongoDB\Client::startSession()``
55+
method on your ``Client`` instance. Then, you can use either of the
56+
following APIs to perform a transaction:
57+
58+
- :ref:`php-convenient-txn`
59+
- :ref:`php-core-txn`
60+
61+
.. _php-convenient-txn:
62+
63+
Convenient API
64+
~~~~~~~~~~~~~~
65+
66+
The {+php-library+} provides a **Convenient Transaction API** to manage
67+
the transaction lifecyle. Implement this API by using the
68+
``MongoDB\with_transaction()`` function to run custom callback within a
69+
transaction. The ``with_transaction()`` function performs the following
70+
tasks:
71+
72+
- Starts the transaction
73+
- Handles errors by either ending the transaction or retrying it, such
74+
as when the operation returns a ``TransientTransactionError``
75+
- Commits the transaction
76+
77+
The :ref:`php-txn-example` section of this guide demonstrates how to use
78+
this API to perform a transaction.
79+
80+
.. _php-core-txn:
81+
82+
Core API
83+
~~~~~~~~
84+
85+
Alternatively, you can have more control over your transaction lifecyle
86+
by using the methods provided by the ``Session`` class. The
87+
following table describes these methods:
88+
89+
.. list-table::
90+
:widths: 25 75
91+
:stub-columns: 1
92+
:header-rows: 1
93+
94+
* - Method
95+
- Description
96+
97+
* - ``startTransaction()``
98+
- | Starts a new transaction on this session. The session
99+
must be passed into each operation within the transaction, or
100+
the operation will run outside of the transaction.
101+
|
102+
| You can set transaction options by passing an options parameter.
103+
104+
* - ``commitTransaction()``
105+
- | Commits the active transaction for this session. This method returns an
106+
error if there is no active transaction for the session, the
107+
transaction was previously ended, or if there is a write conflict.
108+
109+
* - ``abortTransaction()``
110+
- | Ends the active transaction for this session. This method returns an
111+
error if there is no active transaction for the session or if the
112+
transaction was committed or ended.
113+
114+
.. _php-txn-example:
115+
116+
Transaction Example
117+
-------------------
118+
119+
This example defines a callback function that
120+
modifies data in the collections of the ``bank`` database for a
121+
banking transaction. The code performs the following actions:
122+
123+
- Creates ``Collection`` instances to access the target
124+
collections.
125+
- Specifies the account number and amount to be transferred between
126+
accounts.
127+
- Defines the callback function, which receives the ``Session`` instance
128+
as a parameter.
129+
- Updates the customer's balances to reflect the money transfer.
130+
- Records a receipt of the transaction with a timestamp.
131+
- Prints a message if the transaction committed successfully.
132+
133+
.. literalinclude:: /includes/write/transaction.php
134+
:copyable:
135+
:language: php
136+
:dedent:
137+
:start-after: begin-callback
138+
:end-before: end-callback
139+
140+
Then, run the following code to perform the transaction. This code
141+
completes the following actions:
142+
143+
1. Creates a session from the client by using the ``startSession()`` method.
144+
#. Calls the ``with_transaction()`` function to manage the transaction,
145+
passing the session and the callback as parameters.
146+
147+
.. io-code-block::
148+
:copyable:
149+
150+
.. input:: /includes/write/transaction.php
151+
:language: php
152+
:dedent:
153+
:start-after: begin-txn
154+
:end-before: end-txn
155+
:emphasize-lines: 1, 4
156+
157+
.. output::
158+
:language: console
159+
:visible: false
160+
161+
Successfully performed transaction!
162+
Summary: SAVINGS +1000 CHECKING -1000
163+
164+
Additional Information
165+
----------------------
166+
167+
To learn more about the concepts mentioned in this guide, see the
168+
following pages in the {+mdb-server+} manual:
169+
170+
- :manual:`Transactions </core/transactions/>`
171+
- :manual:`Server Sessions </reference/server-sessions/>`
172+
- :manual:`Read Isolation, Consistency, and Recency
173+
</core/read-isolation-consistency-recency/>`
174+
175+
To learn more about ACID compliance, see the :website:`What are ACID
176+
Properties in Database Management Systems? </basics/acid-transactions>`
177+
article on the MongoDB website.
178+
179+
To learn more about insert operations, see the
180+
:ref:`php-write-insert` guide.
181+
182+
API Documentation
183+
~~~~~~~~~~~~~~~~~
184+
185+
To learn more about the methods and types mentioned in this
186+
guide, see the following API documentation:
187+
188+
- :phpclass:`MongoDB\Client`
189+
- :phpmethod:`MongoDB\Client::startSession()`
190+
- :phpmethod:`MongoDB\with_transaction()`
191+
- :phpmethod:`MongoDB\Collection::updateOne()`
192+
- :phpmethod:`MongoDB\Collection::insertOne()`
193+
194+
To learn more about the ``Session`` class and methods,
195+
see the following {+extension-short+} API documentation:
196+
197+
- :php:`MongoDB\Driver\Session <mongodb-driver-session>`
198+
- :php:`MongoDB\Driver\Session::abortTransaction() <mongodb-driver-session.aborttransaction>`
199+
- :php:`MongoDB\Driver\Session::commitTransaction() <mongodb-driver-session.committransaction>`
200+
- :php:`MongoDB\Driver\Session::startTransaction() <mongodb-driver-session.starttransaction>`

0 commit comments

Comments
 (0)