|
| 1 | +.. |
| 2 | + This page is pulled from the TransactionOption type, where this entire |
| 3 | + kaboodle is auto-generated. Sphinx does not particularly appreciate |
| 4 | + entire narrative documentation, complete with headers, in an arbitrary |
| 5 | + class docstring, and complains about this, so I (lukesneeringer@) |
| 6 | + manually copied it over here. |
| 7 | +
|
| 8 | + This should probably be updated when the Spanner code is re-generated. |
| 9 | + This will be easy to remember because the source that needs to be copied |
| 10 | + will be dropped in transaction_pb2.py and Sphinx will complain loudly |
| 11 | + about it. |
| 12 | + |
| 13 | + Internal Google ticket: b/65243734 |
| 14 | + |
| 15 | +:orphan: |
| 16 | + |
| 17 | +.. _spanner-txn: |
| 18 | + |
| 19 | +Transactions |
| 20 | +============ |
| 21 | + |
| 22 | +Each session can have at most one active transaction at a time. After |
| 23 | +the active transaction is completed, the session can immediately be |
| 24 | +re-used for the next transaction. It is not necessary to create a new |
| 25 | +session for each transaction. |
| 26 | + |
| 27 | +Transaction Modes |
| 28 | +================= |
| 29 | + |
| 30 | +Cloud Spanner supports two transaction modes: |
| 31 | + |
| 32 | +1. Locking read-write. This type of transaction is the only way to write |
| 33 | + data into Cloud Spanner. These transactions rely on pessimistic |
| 34 | + locking and, if necessary, two-phase commit. Locking read-write |
| 35 | + transactions may abort, requiring the application to retry. |
| 36 | + |
| 37 | +2. Snapshot read-only. This transaction type provides guaranteed |
| 38 | + consistency across several reads, but does not allow writes. Snapshot |
| 39 | + read-only transactions can be configured to read at timestamps in the |
| 40 | + past. Snapshot read-only transactions do not need to be committed. |
| 41 | + |
| 42 | +For transactions that only read, snapshot read-only transactions provide |
| 43 | +simpler semantics and are almost always faster. In particular, read-only |
| 44 | +transactions do not take locks, so they do not conflict with read-write |
| 45 | +transactions. As a consequence of not taking locks, they also do not |
| 46 | +abort, so retry loops are not needed. |
| 47 | + |
| 48 | +Transactions may only read/write data in a single database. They may, |
| 49 | +however, read/write data in different tables within that database. |
| 50 | + |
| 51 | +Locking Read-Write Transactions |
| 52 | +------------------------------- |
| 53 | + |
| 54 | +Locking transactions may be used to atomically read-modify-write data |
| 55 | +anywhere in a database. This type of transaction is externally |
| 56 | +consistent. |
| 57 | + |
| 58 | +Clients should attempt to minimize the amount of time a transaction is |
| 59 | +active. Faster transactions commit with higher probability and cause |
| 60 | +less contention. Cloud Spanner attempts to keep read locks active as |
| 61 | +long as the transaction continues to do reads, and the transaction has |
| 62 | +not been terminated by [Commit][google.spanner.v1.Spanner.Commit] or |
| 63 | +[Rollback][google.spanner.v1.Spanner.Rollback]. Long periods of |
| 64 | +inactivity at the client may cause Cloud Spanner to release a |
| 65 | +transaction's locks and abort it. |
| 66 | + |
| 67 | +Reads performed within a transaction acquire locks on the data being |
| 68 | +read. Writes can only be done at commit time, after all reads have been |
| 69 | +completed. Conceptually, a read-write transaction consists of zero or |
| 70 | +more reads or SQL queries followed by |
| 71 | +[Commit][google.spanner.v1.Spanner.Commit]. At any time before |
| 72 | +[Commit][google.spanner.v1.Spanner.Commit], the client can send a |
| 73 | +[Rollback][google.spanner.v1.Spanner.Rollback] request to abort the |
| 74 | +transaction. |
| 75 | + |
| 76 | +Semantics |
| 77 | +~~~~~~~~~ |
| 78 | + |
| 79 | +Cloud Spanner can commit the transaction if all read locks it acquired |
| 80 | +are still valid at commit time, and it is able to acquire write locks |
| 81 | +for all writes. Cloud Spanner can abort the transaction for any reason. |
| 82 | +If a commit attempt returns ``ABORTED``, Cloud Spanner guarantees that |
| 83 | +the transaction has not modified any user data in Cloud Spanner. |
| 84 | + |
| 85 | +Unless the transaction commits, Cloud Spanner makes no guarantees about |
| 86 | +how long the transaction's locks were held for. It is an error to use |
| 87 | +Cloud Spanner locks for any sort of mutual exclusion other than between |
| 88 | +Cloud Spanner transactions themselves. |
| 89 | + |
| 90 | +Retrying Aborted Transactions |
| 91 | +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 92 | + |
| 93 | +When a transaction aborts, the application can choose to retry the whole |
| 94 | +transaction again. To maximize the chances of successfully committing |
| 95 | +the retry, the client should execute the retry in the same session as |
| 96 | +the original attempt. The original session's lock priority increases |
| 97 | +with each consecutive abort, meaning that each attempt has a slightly |
| 98 | +better chance of success than the previous. |
| 99 | + |
| 100 | +Under some circumstances (e.g., many transactions attempting to modify |
| 101 | +the same row(s)), a transaction can abort many times in a short period |
| 102 | +before successfully committing. Thus, it is not a good idea to cap the |
| 103 | +number of retries a transaction can attempt; instead, it is better to |
| 104 | +limit the total amount of wall time spent retrying. |
| 105 | + |
| 106 | +Idle Transactions |
| 107 | +~~~~~~~~~~~~~~~~~ |
| 108 | + |
| 109 | +A transaction is considered idle if it has no outstanding reads or SQL |
| 110 | +queries and has not started a read or SQL query within the last 10 |
| 111 | +seconds. Idle transactions can be aborted by Cloud Spanner so that they |
| 112 | +don't hold on to locks indefinitely. In that case, the commit will fail |
| 113 | +with error ``ABORTED``. |
| 114 | + |
| 115 | +If this behavior is undesirable, periodically executing a simple SQL |
| 116 | +query in the transaction (e.g., ``SELECT 1``) prevents the transaction |
| 117 | +from becoming idle. |
| 118 | + |
| 119 | +Snapshot Read-Only Transactions |
| 120 | +------------------------------- |
| 121 | + |
| 122 | +Snapshot read-only transactions provides a simpler method than locking |
| 123 | +read-write transactions for doing several consistent reads. However, |
| 124 | +this type of transaction does not support writes. |
| 125 | + |
| 126 | +Snapshot transactions do not take locks. Instead, they work by choosing |
| 127 | +a Cloud Spanner timestamp, then executing all reads at that timestamp. |
| 128 | +Since they do not acquire locks, they do not block concurrent read-write |
| 129 | +transactions. |
| 130 | + |
| 131 | +Unlike locking read-write transactions, snapshot read-only transactions |
| 132 | +never abort. They can fail if the chosen read timestamp is garbage |
| 133 | +collected; however, the default garbage collection policy is generous |
| 134 | +enough that most applications do not need to worry about this in |
| 135 | +practice. |
| 136 | + |
| 137 | +Snapshot read-only transactions do not need to call |
| 138 | +[Commit][google.spanner.v1.Spanner.Commit] or |
| 139 | +[Rollback][google.spanner.v1.Spanner.Rollback] (and in fact are not |
| 140 | +permitted to do so). |
| 141 | + |
| 142 | +To execute a snapshot transaction, the client specifies a timestamp |
| 143 | +bound, which tells Cloud Spanner how to choose a read timestamp. |
| 144 | + |
| 145 | +The types of timestamp bound are: |
| 146 | + |
| 147 | +- Strong (the default). |
| 148 | +- Bounded staleness. |
| 149 | +- Exact staleness. |
| 150 | + |
| 151 | +If the Cloud Spanner database to be read is geographically distributed, |
| 152 | +stale read-only transactions can execute more quickly than strong or |
| 153 | +read-write transaction, because they are able to execute far from the |
| 154 | +leader replica. |
| 155 | + |
| 156 | +Each type of timestamp bound is discussed in detail below. |
| 157 | + |
| 158 | +Strong |
| 159 | +~~~~~~ |
| 160 | + |
| 161 | +Strong reads are guaranteed to see the effects of all transactions that |
| 162 | +have committed before the start of the read. Furthermore, all rows |
| 163 | +yielded by a single read are consistent with each other -- if any part |
| 164 | +of the read observes a transaction, all parts of the read see the |
| 165 | +transaction. |
| 166 | + |
| 167 | +Strong reads are not repeatable: two consecutive strong read-only |
| 168 | +transactions might return inconsistent results if there are concurrent |
| 169 | +writes. If consistency across reads is required, the reads should be |
| 170 | +executed within a transaction or at an exact read timestamp. |
| 171 | + |
| 172 | +See |
| 173 | +[TransactionOptions.ReadOnly.strong][google.spanner.v1.TransactionOptions.ReadOnly.strong]. |
| 174 | + |
| 175 | +Exact Staleness |
| 176 | +~~~~~~~~~~~~~~~ |
| 177 | + |
| 178 | +These timestamp bounds execute reads at a user-specified timestamp. |
| 179 | +Reads at a timestamp are guaranteed to see a consistent prefix of the |
| 180 | +global transaction history: they observe modifications done by all |
| 181 | +transactions with a commit timestamp <= the read timestamp, and observe |
| 182 | +none of the modifications done by transactions with a larger commit |
| 183 | +timestamp. They will block until all conflicting transactions that may |
| 184 | +be assigned commit timestamps <= the read timestamp have finished. |
| 185 | + |
| 186 | +The timestamp can either be expressed as an absolute Cloud Spanner |
| 187 | +commit timestamp or a staleness relative to the current time. |
| 188 | + |
| 189 | +These modes do not require a "negotiation phase" to pick a timestamp. As |
| 190 | +a result, they execute slightly faster than the equivalent boundedly |
| 191 | +stale concurrency modes. On the other hand, boundedly stale reads |
| 192 | +usually return fresher results. |
| 193 | + |
| 194 | +See |
| 195 | +[TransactionOptions.ReadOnly.read\_timestamp][google.spanner.v1.TransactionOptions.ReadOnly.read\_timestamp] |
| 196 | +and |
| 197 | +[TransactionOptions.ReadOnly.exact\_staleness][google.spanner.v1.TransactionOptions.ReadOnly.exact\_staleness]. |
| 198 | + |
| 199 | +Bounded Staleness |
| 200 | +~~~~~~~~~~~~~~~~~ |
| 201 | + |
| 202 | +Bounded staleness modes allow Cloud Spanner to pick the read timestamp, |
| 203 | +subject to a user-provided staleness bound. Cloud Spanner chooses the |
| 204 | +newest timestamp within the staleness bound that allows execution of the |
| 205 | +reads at the closest available replica without blocking. |
| 206 | + |
| 207 | +All rows yielded are consistent with each other -- if any part of the |
| 208 | +read observes a transaction, all parts of the read see the transaction. |
| 209 | +Boundedly stale reads are not repeatable: two stale reads, even if they |
| 210 | +use the same staleness bound, can execute at different timestamps and |
| 211 | +thus return inconsistent results. |
| 212 | + |
| 213 | +Boundedly stale reads execute in two phases: the first phase negotiates |
| 214 | +a timestamp among all replicas needed to serve the read. In the second |
| 215 | +phase, reads are executed at the negotiated timestamp. |
| 216 | + |
| 217 | +As a result of the two phase execution, bounded staleness reads are |
| 218 | +usually a little slower than comparable exact staleness reads. However, |
| 219 | +they are typically able to return fresher results, and are more likely |
| 220 | +to execute at the closest replica. |
| 221 | + |
| 222 | +Because the timestamp negotiation requires up-front knowledge of which |
| 223 | +rows will be read, it can only be used with single-use read-only |
| 224 | +transactions. |
| 225 | + |
| 226 | +See |
| 227 | +[TransactionOptions.ReadOnly.max\_staleness][google.spanner.v1.TransactionOptions.ReadOnly.max\_staleness] |
| 228 | +and |
| 229 | +[TransactionOptions.ReadOnly.min\_read\_timestamp][google.spanner.v1.TransactionOptions.ReadOnly.min\_read\_timestamp]. |
| 230 | + |
| 231 | +Old Read Timestamps and Garbage Collection |
| 232 | +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 233 | + |
| 234 | +Cloud Spanner continuously garbage collects deleted and overwritten data |
| 235 | +in the background to reclaim storage space. This process is known as |
| 236 | +"version GC". By default, version GC reclaims versions after they are |
| 237 | +one hour old. Because of this, Cloud Spanner cannot perform reads at |
| 238 | +read timestamps more than one hour in the past. This restriction also |
| 239 | +applies to in-progress reads and/or SQL queries whose timestamp become |
| 240 | +too old while executing. Reads and SQL queries with too-old read |
| 241 | +timestamps fail with the error ``FAILED_PRECONDITION``. |
0 commit comments