diff options
author | Etienne Petrel <etienne.petrel@mongodb.com> | 2022-06-21 23:16:02 +0000 |
---|---|---|
committer | Evergreen Agent <no-reply@evergreen.mongodb.com> | 2022-06-21 23:44:39 +0000 |
commit | 0078fd5939294a80e4104389e9f1ed50861e85a2 (patch) | |
tree | 478bc7970e0cc117aafbf3d2964931452a341c13 | |
parent | 43efa77bd3107e1f72f7efbb0ef11fc2b07e2c13 (diff) | |
download | mongo-0078fd5939294a80e4104389e9f1ed50861e85a2.tar.gz |
Import wiredtiger: 994aabd96c7c28ffd7c15e3b81bda3e41ca33005 from branch mongodb-master
ref: 2666d037c9..994aabd96c
for: 6.1.0-rc0
WT-9404 Review updated transactional documentation
4 files changed, 69 insertions, 54 deletions
diff --git a/src/third_party/wiredtiger/import.data b/src/third_party/wiredtiger/import.data index d9d35bf20c1..92eaf0db2ff 100644 --- a/src/third_party/wiredtiger/import.data +++ b/src/third_party/wiredtiger/import.data @@ -2,5 +2,5 @@ "vendor": "wiredtiger", "github": "wiredtiger/wiredtiger.git", "branch": "mongodb-master", - "commit": "2666d037c9ebfc84db2c739dfc10dab0e28b3e02" + "commit": "994aabd96c7c28ffd7c15e3b81bda3e41ca33005" } diff --git a/src/third_party/wiredtiger/src/docs/explain-isolation.dox b/src/third_party/wiredtiger/src/docs/explain-isolation.dox index ecb8175e51c..d07074f8e31 100644 --- a/src/third_party/wiredtiger/src/docs/explain-isolation.dox +++ b/src/third_party/wiredtiger/src/docs/explain-isolation.dox @@ -10,8 +10,8 @@ phantoms are possible. Transactions cannot see changes made by other transactions before those transactions are committed. Dirty reads are not possible; non-repeatable reads and phantoms are possible. Committed changes from -concurrent transactions become visible when no cursor is positioned in -the read-committed transaction. +concurrent transactions become visible periodically during the lifecycle +of the transaction. - <code>snapshot</code>: Transactions read the versions of records committed before the transaction diff --git a/src/third_party/wiredtiger/src/docs/timestamp-txn.dox b/src/third_party/wiredtiger/src/docs/timestamp-txn.dox index 9bafa55f2f8..a900ed763fd 100644 --- a/src/third_party/wiredtiger/src/docs/timestamp-txn.dox +++ b/src/third_party/wiredtiger/src/docs/timestamp-txn.dox @@ -65,6 +65,66 @@ the library will log an error message and drop core at the failing check. These are best-effort checks by WiredTiger, and there are cases where application misbehavior will not be detected. +@section timestamp_txn_api_commit_timestamp Setting the transaction's commit timestamp + +The \c commit time is the time at which other transactions with appropriately set +read timestamps will see the transaction's updates. + +The commit timestamp can be set at any point in the transaction's lifecycle. +For prepared transactions, however, it can only be set after the transaction +has been successfully prepared. + +\warning Commit (and prepare) timestamps must not be set in the past +of any read timestamp +that has ever been used. This rule is enforced by assertions in diagnostic +builds, but if applications violate this rule in non-diagnostic builds, data +consistency can be violated. +Similarly, because reading without a read timestamp reads the latest +values for all keys, one must not commit into the past of such a +transaction. + +Applications using timestamps usually specify a timestamp to the +WT_SESSION::commit_transaction method to set the commit time for all updates in +the transaction. + +For prepared transactions, the commit timestamp must not be before the prepare +timestamp. Otherwise, the commit timestamp must be after the stable timestamp. + +@section timestamp_txn_api_commit_multi_timestamp Setting multiple commit timestamps + +Applications may set different commit timestamps for different updates in a +single transaction by calling WT_SESSION::timestamp_transaction repeatedly to +set a new commit timestamp between updates in the transaction. Each new commit +timestamp is applied to any subsequent updates. This gives applications the +ability to commit updates that take effect at different times; +that is, it is possible to create chains of updates where each +update appears at a different time to readers. For transactions that set +multiple commit timestamps, the first commit timestamp set is also required to +be the earliest: the second and subsequent commit timestamps may not be +earlier than the first commit timestamp. This feature is not compatible with +prepared transactions, which must use only a single commit timestamp. + +This functionality is generally available as a mechanism to allow an optimized +implementation of re-creating a timestamp view of a data set. For example, in +a MongoDB replica set, content is generated on one node where transactions are +assigned a single commit timestamp, that content is re-created on each other +member in a replica set. When re-creating the content multiple changes from +the original node are batched together into a single WiredTiger transaction. + +@section timestamp_txn_api_read_timestamp Setting the transaction's read timestamp + +Setting the transaction's read timestamp causes a transaction to not see any +commits with a newer timestamp. (Updates may still conflict with commits having +a newer timestamp, of course.), + +The read timestamp may be set to any time equal to or after the system's +\c oldest timestamp. + +This restriction is enforced and applications can rely on an error return to +detect attempts to set the read timestamp older than the \c oldest timestamp. + +The read timestamp may only be set once in the lifetime of a transaction. + @section timestamp_txn_api_query Querying transaction timestamp information The following table lists the timestamps that can be queried using @@ -119,55 +179,4 @@ points in the transaction's lifetime, using WT_SESSION::timestamp_transaction: | prepare_timestamp | > stable and >= any system read timestamp | the transaction's prepare timestamp, see @ref timestamp_prepare for details | | read_timestamp | >= oldest | the transaction's read timestamp, see @ref timestamp_txn_api_read_timestamp for details | -@section timestamp_txn_api_commit_timestamp Setting the transaction's commit timestamp - -The \c commit time is the time at which other transactions with appropriately set -read timestamps will see the transaction's updates. - -The commit timestamp can be set at any point in the transaction's lifecycle. -For prepared transactions, however, it can only be set after the transaction -has been successfully prepared. - -\warning Commit (and prepare) timestamps must not be set in the past -of any read timestamp -that has ever been used. This rule is enforced by assertions in diagnostic -builds, but if applications violate this rule in non-diagnostic builds, data -consistency can be violated. -Similarly, because reading without a read timestamp reads the latest -values for all keys, one must not commit into the past of such a -transaction. - -Applications using timestamps usually specify a timestamp to the -WT_SESSION::commit_transaction method to set the commit time for all updates in -the transaction. - -Applications may set different commit timestamps for different updates in a -single transaction by calling WT_SESSION::timestamp_transaction repeatedly to -set a new commit timestamp between updates in the transaction. Each new commit -timestamp is applied to any subsequent updates. This gives applications the -ability to commit updates that take effect at different times; -that is, it is possible to create chains of updates where each -update appears at a different time to readers. For transactions that set -multiple commit timestamps, the first commit timestamp set is also required to -be the earliest: the second and subsequent commit timestamps may not be -earlier than the first commit timestamp. This feature is not compatible with -prepared transactions, which must use only a single commit timestamp. - -For prepared transactions, the commit timestamp must not be before the prepare -timestamp. Otherwise, the commit timestamp must be after the stable timestamp. - -@section timestamp_txn_api_read_timestamp Setting the transaction's read timestamp - -Setting the transaction's read timestamp causes a transaction to not see any -commits with a newer timestamp. (Updates may still conflict with commits having -a newer timestamp, of course.), - -The read timestamp may be set to any time equal to or after the system's -\c oldest timestamp. - -This restriction is enforced and applications can rely on an error return to -detect attempts to set the read timestamp older than the \c oldest timestamp. - -The read timestamp may only be set once in the lifetime of a transaction. - */ diff --git a/src/third_party/wiredtiger/src/docs/transactions_api.dox b/src/third_party/wiredtiger/src/docs/transactions_api.dox index 3ccf2776fea..641ba2e8ed2 100644 --- a/src/third_party/wiredtiger/src/docs/transactions_api.dox +++ b/src/third_party/wiredtiger/src/docs/transactions_api.dox @@ -25,6 +25,12 @@ effects may be discarded by calling WT_SESSION::rollback_transaction. If WT_SESSION::commit_transaction returns any error, the transaction was rolled back, not committed. +Schema changing operations are not generally transactional in WiredTiger, they +can't be grouped together within the scope of a transaction and atomically +committed or aborted. Think of them as one-shot transactions where the operation +will either succeed or fail. Examples of schema changing operations are table +create, drop and rename. + A data operation executed within a transaction can fail if it conflicts with an operation in another concurrently running transaction. (A conflict occurs between two operations when letting both of them continue would lead to a |