google-cloud-spanner 1.16.1 → 2.3.0

Sign up to get free protection for your applications and to get access to all the features.
Files changed (108) hide show
  1. checksums.yaml +4 -4
  2. data/AUTHENTICATION.md +1 -1
  3. data/CHANGELOG.md +58 -0
  4. data/CONTRIBUTING.md +6 -6
  5. data/TROUBLESHOOTING.md +0 -6
  6. data/lib/google-cloud-spanner.rb +11 -13
  7. data/lib/google/cloud/spanner.rb +13 -13
  8. data/lib/google/cloud/spanner/admin/database/credentials.rb +2 -2
  9. data/lib/google/cloud/spanner/admin/instance/credentials.rb +2 -2
  10. data/lib/google/cloud/spanner/backup.rb +1 -1
  11. data/lib/google/cloud/spanner/backup/job.rb +2 -2
  12. data/lib/google/cloud/spanner/backup/job/list.rb +2 -2
  13. data/lib/google/cloud/spanner/backup/list.rb +1 -2
  14. data/lib/google/cloud/spanner/backup/restore/job.rb +2 -2
  15. data/lib/google/cloud/spanner/batch_client.rb +2 -2
  16. data/lib/google/cloud/spanner/batch_snapshot.rb +120 -23
  17. data/lib/google/cloud/spanner/batch_update.rb +1 -1
  18. data/lib/google/cloud/spanner/client.rb +388 -47
  19. data/lib/google/cloud/spanner/commit.rb +14 -14
  20. data/lib/google/cloud/spanner/commit_response.rb +87 -0
  21. data/lib/google/cloud/spanner/commit_response/commit_stats.rb +51 -0
  22. data/lib/google/cloud/spanner/convert.rb +16 -7
  23. data/lib/google/cloud/spanner/credentials.rb +2 -2
  24. data/lib/google/cloud/spanner/data.rb +2 -2
  25. data/lib/google/cloud/spanner/database.rb +22 -22
  26. data/lib/google/cloud/spanner/database/backup_info.rb +1 -1
  27. data/lib/google/cloud/spanner/database/job.rb +3 -3
  28. data/lib/google/cloud/spanner/database/job/list.rb +2 -2
  29. data/lib/google/cloud/spanner/database/list.rb +1 -1
  30. data/lib/google/cloud/spanner/database/restore_info.rb +1 -1
  31. data/lib/google/cloud/spanner/fields.rb +8 -8
  32. data/lib/google/cloud/spanner/instance.rb +5 -12
  33. data/lib/google/cloud/spanner/instance/config.rb +1 -1
  34. data/lib/google/cloud/spanner/instance/config/list.rb +1 -1
  35. data/lib/google/cloud/spanner/instance/job.rb +2 -2
  36. data/lib/google/cloud/spanner/instance/list.rb +1 -1
  37. data/lib/google/cloud/spanner/partition.rb +4 -4
  38. data/lib/google/cloud/spanner/policy.rb +2 -2
  39. data/lib/google/cloud/spanner/results.rb +103 -24
  40. data/lib/google/cloud/spanner/service.rb +367 -349
  41. data/lib/google/cloud/spanner/session.rb +370 -39
  42. data/lib/google/cloud/spanner/snapshot.rb +60 -6
  43. data/lib/google/cloud/spanner/transaction.rb +116 -10
  44. data/lib/google/cloud/spanner/version.rb +1 -1
  45. metadata +20 -107
  46. data/lib/google/cloud/spanner/admin/database.rb +0 -149
  47. data/lib/google/cloud/spanner/admin/database/v1.rb +0 -147
  48. data/lib/google/cloud/spanner/admin/database/v1/credentials.rb +0 -46
  49. data/lib/google/cloud/spanner/admin/database/v1/database_admin_client.rb +0 -1513
  50. data/lib/google/cloud/spanner/admin/database/v1/database_admin_client_config.json +0 -111
  51. data/lib/google/cloud/spanner/admin/database/v1/doc/google/iam/v1/iam_policy.rb +0 -64
  52. data/lib/google/cloud/spanner/admin/database/v1/doc/google/iam/v1/options.rb +0 -33
  53. data/lib/google/cloud/spanner/admin/database/v1/doc/google/iam/v1/policy.rb +0 -151
  54. data/lib/google/cloud/spanner/admin/database/v1/doc/google/longrunning/operations.rb +0 -51
  55. data/lib/google/cloud/spanner/admin/database/v1/doc/google/protobuf/any.rb +0 -131
  56. data/lib/google/cloud/spanner/admin/database/v1/doc/google/protobuf/empty.rb +0 -29
  57. data/lib/google/cloud/spanner/admin/database/v1/doc/google/protobuf/field_mask.rb +0 -222
  58. data/lib/google/cloud/spanner/admin/database/v1/doc/google/protobuf/timestamp.rb +0 -113
  59. data/lib/google/cloud/spanner/admin/database/v1/doc/google/rpc/status.rb +0 -39
  60. data/lib/google/cloud/spanner/admin/database/v1/doc/google/spanner/admin/database/v1/backup.rb +0 -325
  61. data/lib/google/cloud/spanner/admin/database/v1/doc/google/spanner/admin/database/v1/spanner_database_admin.rb +0 -368
  62. data/lib/google/cloud/spanner/admin/database/v1/doc/google/type/expr.rb +0 -45
  63. data/lib/google/cloud/spanner/admin/instance.rb +0 -164
  64. data/lib/google/cloud/spanner/admin/instance/v1.rb +0 -162
  65. data/lib/google/cloud/spanner/admin/instance/v1/credentials.rb +0 -46
  66. data/lib/google/cloud/spanner/admin/instance/v1/doc/google/iam/v1/iam_policy.rb +0 -64
  67. data/lib/google/cloud/spanner/admin/instance/v1/doc/google/iam/v1/options.rb +0 -33
  68. data/lib/google/cloud/spanner/admin/instance/v1/doc/google/iam/v1/policy.rb +0 -151
  69. data/lib/google/cloud/spanner/admin/instance/v1/doc/google/longrunning/operations.rb +0 -51
  70. data/lib/google/cloud/spanner/admin/instance/v1/doc/google/protobuf/any.rb +0 -131
  71. data/lib/google/cloud/spanner/admin/instance/v1/doc/google/protobuf/empty.rb +0 -29
  72. data/lib/google/cloud/spanner/admin/instance/v1/doc/google/protobuf/field_mask.rb +0 -222
  73. data/lib/google/cloud/spanner/admin/instance/v1/doc/google/rpc/status.rb +0 -39
  74. data/lib/google/cloud/spanner/admin/instance/v1/doc/google/spanner/admin/instance/v1/spanner_instance_admin.rb +0 -334
  75. data/lib/google/cloud/spanner/admin/instance/v1/doc/google/type/expr.rb +0 -45
  76. data/lib/google/cloud/spanner/admin/instance/v1/instance_admin_client.rb +0 -975
  77. data/lib/google/cloud/spanner/admin/instance/v1/instance_admin_client_config.json +0 -76
  78. data/lib/google/cloud/spanner/v1.rb +0 -16
  79. data/lib/google/cloud/spanner/v1/credentials.rb +0 -42
  80. data/lib/google/cloud/spanner/v1/doc/google/protobuf/any.rb +0 -131
  81. data/lib/google/cloud/spanner/v1/doc/google/protobuf/duration.rb +0 -91
  82. data/lib/google/cloud/spanner/v1/doc/google/protobuf/empty.rb +0 -29
  83. data/lib/google/cloud/spanner/v1/doc/google/protobuf/struct.rb +0 -74
  84. data/lib/google/cloud/spanner/v1/doc/google/protobuf/timestamp.rb +0 -113
  85. data/lib/google/cloud/spanner/v1/doc/google/rpc/status.rb +0 -39
  86. data/lib/google/cloud/spanner/v1/doc/google/spanner/v1/keys.rb +0 -150
  87. data/lib/google/cloud/spanner/v1/doc/google/spanner/v1/mutation.rb +0 -95
  88. data/lib/google/cloud/spanner/v1/doc/google/spanner/v1/query_plan.rb +0 -121
  89. data/lib/google/cloud/spanner/v1/doc/google/spanner/v1/result_set.rb +0 -190
  90. data/lib/google/cloud/spanner/v1/doc/google/spanner/v1/spanner.rb +0 -570
  91. data/lib/google/cloud/spanner/v1/doc/google/spanner/v1/transaction.rb +0 -432
  92. data/lib/google/cloud/spanner/v1/doc/google/spanner/v1/type.rb +0 -112
  93. data/lib/google/cloud/spanner/v1/spanner_client.rb +0 -1485
  94. data/lib/google/cloud/spanner/v1/spanner_client_config.json +0 -121
  95. data/lib/google/spanner/admin/database/v1/backup_pb.rb +0 -98
  96. data/lib/google/spanner/admin/database/v1/common_pb.rb +0 -28
  97. data/lib/google/spanner/admin/database/v1/spanner_database_admin_pb.rb +0 -141
  98. data/lib/google/spanner/admin/database/v1/spanner_database_admin_services_pb.rb +0 -169
  99. data/lib/google/spanner/admin/instance/v1/spanner_instance_admin_pb.rb +0 -125
  100. data/lib/google/spanner/admin/instance/v1/spanner_instance_admin_services_pb.rb +0 -181
  101. data/lib/google/spanner/v1/keys_pb.rb +0 -34
  102. data/lib/google/spanner/v1/mutation_pb.rb +0 -39
  103. data/lib/google/spanner/v1/query_plan_pb.rb +0 -48
  104. data/lib/google/spanner/v1/result_set_pb.rb +0 -48
  105. data/lib/google/spanner/v1/spanner_pb.rb +0 -179
  106. data/lib/google/spanner/v1/spanner_services_pb.rb +0 -179
  107. data/lib/google/spanner/v1/transaction_pb.rb +0 -56
  108. data/lib/google/spanner/v1/type_pb.rb +0 -44
@@ -1,432 +0,0 @@
1
- # Copyright 2020 Google LLC
2
- #
3
- # Licensed under the Apache License, Version 2.0 (the "License");
4
- # you may not use this file except in compliance with the License.
5
- # You may obtain a copy of the License at
6
- #
7
- # https://www.apache.org/licenses/LICENSE-2.0
8
- #
9
- # Unless required by applicable law or agreed to in writing, software
10
- # distributed under the License is distributed on an "AS IS" BASIS,
11
- # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12
- # See the License for the specific language governing permissions and
13
- # limitations under the License.
14
-
15
-
16
- module Google
17
- module Spanner
18
- module V1
19
- # = Transactions
20
- #
21
- # Each session can have at most one active transaction at a time. After the
22
- # active transaction is completed, the session can immediately be
23
- # re-used for the next transaction. It is not necessary to create a
24
- # new session for each transaction.
25
- #
26
- # = Transaction Modes
27
- #
28
- # Cloud Spanner supports three transaction modes:
29
- #
30
- # 1. Locking read-write. This type of transaction is the only way
31
- # to write data into Cloud Spanner. These transactions rely on
32
- # pessimistic locking and, if necessary, two-phase commit.
33
- # Locking read-write transactions may abort, requiring the
34
- # application to retry.
35
- #
36
- # 2. Snapshot read-only. This transaction type provides guaranteed
37
- # consistency across several reads, but does not allow
38
- # writes. Snapshot read-only transactions can be configured to
39
- # read at timestamps in the past. Snapshot read-only
40
- # transactions do not need to be committed.
41
- #
42
- # 3. Partitioned DML. This type of transaction is used to execute
43
- # a single Partitioned DML statement. Partitioned DML partitions
44
- # the key space and runs the DML statement over each partition
45
- # in parallel using separate, internal transactions that commit
46
- # independently. Partitioned DML transactions do not need to be
47
- # committed.
48
- #
49
- # For transactions that only read, snapshot read-only transactions
50
- # provide simpler semantics and are almost always faster. In
51
- # particular, read-only transactions do not take locks, so they do
52
- # not conflict with read-write transactions. As a consequence of not
53
- # taking locks, they also do not abort, so retry loops are not needed.
54
- #
55
- # Transactions may only read/write data in a single database. They
56
- # may, however, read/write data in different tables within that
57
- # database.
58
- #
59
- # == Locking Read-Write Transactions
60
- #
61
- # Locking transactions may be used to atomically read-modify-write
62
- # data anywhere in a database. This type of transaction is externally
63
- # consistent.
64
- #
65
- # Clients should attempt to minimize the amount of time a transaction
66
- # is active. Faster transactions commit with higher probability
67
- # and cause less contention. Cloud Spanner attempts to keep read locks
68
- # active as long as the transaction continues to do reads, and the
69
- # transaction has not been terminated by
70
- # {Google::Spanner::V1::Spanner::Commit Commit} or
71
- # {Google::Spanner::V1::Spanner::Rollback Rollback}. Long periods of
72
- # inactivity at the client may cause Cloud Spanner to release a
73
- # transaction's locks and abort it.
74
- #
75
- # Conceptually, a read-write transaction consists of zero or more
76
- # reads or SQL statements followed by
77
- # {Google::Spanner::V1::Spanner::Commit Commit}. At any time before
78
- # {Google::Spanner::V1::Spanner::Commit Commit}, the client can send a
79
- # {Google::Spanner::V1::Spanner::Rollback Rollback} request to abort the
80
- # transaction.
81
- #
82
- # === Semantics
83
- #
84
- # Cloud Spanner can commit the transaction if all read locks it acquired
85
- # are still valid at commit time, and it is able to acquire write
86
- # locks for all writes. Cloud Spanner can abort the transaction for any
87
- # reason. If a commit attempt returns `ABORTED`, Cloud Spanner guarantees
88
- # that the transaction has not modified any user data in Cloud Spanner.
89
- #
90
- # Unless the transaction commits, Cloud Spanner makes no guarantees about
91
- # how long the transaction's locks were held for. It is an error to
92
- # use Cloud Spanner locks for any sort of mutual exclusion other than
93
- # between Cloud Spanner transactions themselves.
94
- #
95
- # === Retrying Aborted Transactions
96
- #
97
- # When a transaction aborts, the application can choose to retry the
98
- # whole transaction again. To maximize the chances of successfully
99
- # committing the retry, the client should execute the retry in the
100
- # same session as the original attempt. The original session's lock
101
- # priority increases with each consecutive abort, meaning that each
102
- # attempt has a slightly better chance of success than the previous.
103
- #
104
- # Under some circumstances (e.g., many transactions attempting to
105
- # modify the same row(s)), a transaction can abort many times in a
106
- # short period before successfully committing. Thus, it is not a good
107
- # idea to cap the number of retries a transaction can attempt;
108
- # instead, it is better to limit the total amount of wall time spent
109
- # retrying.
110
- #
111
- # === Idle Transactions
112
- #
113
- # A transaction is considered idle if it has no outstanding reads or
114
- # SQL queries and has not started a read or SQL query within the last 10
115
- # seconds. Idle transactions can be aborted by Cloud Spanner so that they
116
- # don't hold on to locks indefinitely. In that case, the commit will
117
- # fail with error `ABORTED`.
118
- #
119
- # If this behavior is undesirable, periodically executing a simple
120
- # SQL query in the transaction (e.g., `SELECT 1`) prevents the
121
- # transaction from becoming idle.
122
- #
123
- # == Snapshot Read-Only Transactions
124
- #
125
- # Snapshot read-only transactions provides a simpler method than
126
- # locking read-write transactions for doing several consistent
127
- # reads. However, this type of transaction does not support writes.
128
- #
129
- # Snapshot transactions do not take locks. Instead, they work by
130
- # choosing a Cloud Spanner timestamp, then executing all reads at that
131
- # timestamp. Since they do not acquire locks, they do not block
132
- # concurrent read-write transactions.
133
- #
134
- # Unlike locking read-write transactions, snapshot read-only
135
- # transactions never abort. They can fail if the chosen read
136
- # timestamp is garbage collected; however, the default garbage
137
- # collection policy is generous enough that most applications do not
138
- # need to worry about this in practice.
139
- #
140
- # Snapshot read-only transactions do not need to call
141
- # {Google::Spanner::V1::Spanner::Commit Commit} or
142
- # {Google::Spanner::V1::Spanner::Rollback Rollback} (and in fact are not
143
- # permitted to do so).
144
- #
145
- # To execute a snapshot transaction, the client specifies a timestamp
146
- # bound, which tells Cloud Spanner how to choose a read timestamp.
147
- #
148
- # The types of timestamp bound are:
149
- #
150
- # * Strong (the default).
151
- # * Bounded staleness.
152
- # * Exact staleness.
153
- #
154
- # If the Cloud Spanner database to be read is geographically distributed,
155
- # stale read-only transactions can execute more quickly than strong
156
- # or read-write transaction, because they are able to execute far
157
- # from the leader replica.
158
- #
159
- # Each type of timestamp bound is discussed in detail below.
160
- #
161
- # === Strong
162
- #
163
- # Strong reads are guaranteed to see the effects of all transactions
164
- # that have committed before the start of the read. Furthermore, all
165
- # rows yielded by a single read are consistent with each other -- if
166
- # any part of the read observes a transaction, all parts of the read
167
- # see the transaction.
168
- #
169
- # Strong reads are not repeatable: two consecutive strong read-only
170
- # transactions might return inconsistent results if there are
171
- # concurrent writes. If consistency across reads is required, the
172
- # reads should be executed within a transaction or at an exact read
173
- # timestamp.
174
- #
175
- # See {Google::Spanner::V1::TransactionOptions::ReadOnly#strong TransactionOptions::ReadOnly#strong}.
176
- #
177
- # === Exact Staleness
178
- #
179
- # These timestamp bounds execute reads at a user-specified
180
- # timestamp. Reads at a timestamp are guaranteed to see a consistent
181
- # prefix of the global transaction history: they observe
182
- # modifications done by all transactions with a commit timestamp <=
183
- # the read timestamp, and observe none of the modifications done by
184
- # transactions with a larger commit timestamp. They will block until
185
- # all conflicting transactions that may be assigned commit timestamps
186
- # <= the read timestamp have finished.
187
- #
188
- # The timestamp can either be expressed as an absolute Cloud Spanner commit
189
- # timestamp or a staleness relative to the current time.
190
- #
191
- # These modes do not require a "negotiation phase" to pick a
192
- # timestamp. As a result, they execute slightly faster than the
193
- # equivalent boundedly stale concurrency modes. On the other hand,
194
- # boundedly stale reads usually return fresher results.
195
- #
196
- # See {Google::Spanner::V1::TransactionOptions::ReadOnly#read_timestamp TransactionOptions::ReadOnly#read_timestamp} and
197
- # {Google::Spanner::V1::TransactionOptions::ReadOnly#exact_staleness TransactionOptions::ReadOnly#exact_staleness}.
198
- #
199
- # === Bounded Staleness
200
- #
201
- # Bounded staleness modes allow Cloud Spanner to pick the read timestamp,
202
- # subject to a user-provided staleness bound. Cloud Spanner chooses the
203
- # newest timestamp within the staleness bound that allows execution
204
- # of the reads at the closest available replica without blocking.
205
- #
206
- # All rows yielded are consistent with each other -- if any part of
207
- # the read observes a transaction, all parts of the read see the
208
- # transaction. Boundedly stale reads are not repeatable: two stale
209
- # reads, even if they use the same staleness bound, can execute at
210
- # different timestamps and thus return inconsistent results.
211
- #
212
- # Boundedly stale reads execute in two phases: the first phase
213
- # negotiates a timestamp among all replicas needed to serve the
214
- # read. In the second phase, reads are executed at the negotiated
215
- # timestamp.
216
- #
217
- # As a result of the two phase execution, bounded staleness reads are
218
- # usually a little slower than comparable exact staleness
219
- # reads. However, they are typically able to return fresher
220
- # results, and are more likely to execute at the closest replica.
221
- #
222
- # Because the timestamp negotiation requires up-front knowledge of
223
- # which rows will be read, it can only be used with single-use
224
- # read-only transactions.
225
- #
226
- # See {Google::Spanner::V1::TransactionOptions::ReadOnly#max_staleness TransactionOptions::ReadOnly#max_staleness} and
227
- # {Google::Spanner::V1::TransactionOptions::ReadOnly#min_read_timestamp TransactionOptions::ReadOnly#min_read_timestamp}.
228
- #
229
- # === Old Read Timestamps and Garbage Collection
230
- #
231
- # Cloud Spanner continuously garbage collects deleted and overwritten data
232
- # in the background to reclaim storage space. This process is known
233
- # as "version GC". By default, version GC reclaims versions after they
234
- # are one hour old. Because of this, Cloud Spanner cannot perform reads
235
- # at read timestamps more than one hour in the past. This
236
- # restriction also applies to in-progress reads and/or SQL queries whose
237
- # timestamp become too old while executing. Reads and SQL queries with
238
- # too-old read timestamps fail with the error `FAILED_PRECONDITION`.
239
- #
240
- # == Partitioned DML Transactions
241
- #
242
- # Partitioned DML transactions are used to execute DML statements with a
243
- # different execution strategy that provides different, and often better,
244
- # scalability properties for large, table-wide operations than DML in a
245
- # ReadWrite transaction. Smaller scoped statements, such as an OLTP workload,
246
- # should prefer using ReadWrite transactions.
247
- #
248
- # Partitioned DML partitions the keyspace and runs the DML statement on each
249
- # partition in separate, internal transactions. These transactions commit
250
- # automatically when complete, and run independently from one another.
251
- #
252
- # To reduce lock contention, this execution strategy only acquires read locks
253
- # on rows that match the WHERE clause of the statement. Additionally, the
254
- # smaller per-partition transactions hold locks for less time.
255
- #
256
- # That said, Partitioned DML is not a drop-in replacement for standard DML used
257
- # in ReadWrite transactions.
258
- #
259
- # * The DML statement must be fully-partitionable. Specifically, the statement
260
- # must be expressible as the union of many statements which each access only
261
- # a single row of the table.
262
- #
263
- # * The statement is not applied atomically to all rows of the table. Rather,
264
- # the statement is applied atomically to partitions of the table, in
265
- # independent transactions. Secondary index rows are updated atomically
266
- # with the base table rows.
267
- #
268
- # * Partitioned DML does not guarantee exactly-once execution semantics
269
- # against a partition. The statement will be applied at least once to each
270
- # partition. It is strongly recommended that the DML statement should be
271
- # idempotent to avoid unexpected results. For instance, it is potentially
272
- # dangerous to run a statement such as
273
- # `UPDATE table SET column = column + 1` as it could be run multiple times
274
- # against some rows.
275
- #
276
- # * The partitions are committed automatically - there is no support for
277
- # Commit or Rollback. If the call returns an error, or if the client issuing
278
- # the ExecuteSql call dies, it is possible that some rows had the statement
279
- # executed on them successfully. It is also possible that statement was
280
- # never executed against other rows.
281
- #
282
- # * Partitioned DML transactions may only contain the execution of a single
283
- # DML statement via ExecuteSql or ExecuteStreamingSql.
284
- #
285
- # * If any error is encountered during the execution of the partitioned DML
286
- # operation (for instance, a UNIQUE INDEX violation, division by zero, or a
287
- # value that cannot be stored due to schema constraints), then the
288
- # operation is stopped at that point and an error is returned. It is
289
- # possible that at this point, some partitions have been committed (or even
290
- # committed multiple times), and other partitions have not been run at all.
291
- #
292
- # Given the above, Partitioned DML is good fit for large, database-wide,
293
- # operations that are idempotent, such as deleting old rows from a very large
294
- # table.
295
- # @!attribute [rw] read_write
296
- # @return [Google::Spanner::V1::TransactionOptions::ReadWrite]
297
- # Transaction may write.
298
- #
299
- # Authorization to begin a read-write transaction requires
300
- # `spanner.databases.beginOrRollbackReadWriteTransaction` permission
301
- # on the `session` resource.
302
- # @!attribute [rw] partitioned_dml
303
- # @return [Google::Spanner::V1::TransactionOptions::PartitionedDml]
304
- # Partitioned DML transaction.
305
- #
306
- # Authorization to begin a Partitioned DML transaction requires
307
- # `spanner.databases.beginPartitionedDmlTransaction` permission
308
- # on the `session` resource.
309
- # @!attribute [rw] read_only
310
- # @return [Google::Spanner::V1::TransactionOptions::ReadOnly]
311
- # Transaction will not write.
312
- #
313
- # Authorization to begin a read-only transaction requires
314
- # `spanner.databases.beginReadOnlyTransaction` permission
315
- # on the `session` resource.
316
- class TransactionOptions
317
- # Message type to initiate a read-write transaction. Currently this
318
- # transaction type has no options.
319
- class ReadWrite; end
320
-
321
- # Message type to initiate a Partitioned DML transaction.
322
- class PartitionedDml; end
323
-
324
- # Message type to initiate a read-only transaction.
325
- # @!attribute [rw] strong
326
- # @return [true, false]
327
- # Read at a timestamp where all previously committed transactions
328
- # are visible.
329
- # @!attribute [rw] min_read_timestamp
330
- # @return [Google::Protobuf::Timestamp]
331
- # Executes all reads at a timestamp >= `min_read_timestamp`.
332
- #
333
- # This is useful for requesting fresher data than some previous
334
- # read, or data that is fresh enough to observe the effects of some
335
- # previously committed transaction whose timestamp is known.
336
- #
337
- # Note that this option can only be used in single-use transactions.
338
- #
339
- # A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.
340
- # Example: `"2014-10-02T15:01:23.045123456Z"`.
341
- # @!attribute [rw] max_staleness
342
- # @return [Google::Protobuf::Duration]
343
- # Read data at a timestamp >= `NOW - max_staleness`
344
- # seconds. Guarantees that all writes that have committed more
345
- # than the specified number of seconds ago are visible. Because
346
- # Cloud Spanner chooses the exact timestamp, this mode works even if
347
- # the client's local clock is substantially skewed from Cloud Spanner
348
- # commit timestamps.
349
- #
350
- # Useful for reading the freshest data available at a nearby
351
- # replica, while bounding the possible staleness if the local
352
- # replica has fallen behind.
353
- #
354
- # Note that this option can only be used in single-use
355
- # transactions.
356
- # @!attribute [rw] read_timestamp
357
- # @return [Google::Protobuf::Timestamp]
358
- # Executes all reads at the given timestamp. Unlike other modes,
359
- # reads at a specific timestamp are repeatable; the same read at
360
- # the same timestamp always returns the same data. If the
361
- # timestamp is in the future, the read will block until the
362
- # specified timestamp, modulo the read's deadline.
363
- #
364
- # Useful for large scale consistent reads such as mapreduces, or
365
- # for coordinating many reads against a consistent snapshot of the
366
- # data.
367
- #
368
- # A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.
369
- # Example: `"2014-10-02T15:01:23.045123456Z"`.
370
- # @!attribute [rw] exact_staleness
371
- # @return [Google::Protobuf::Duration]
372
- # Executes all reads at a timestamp that is `exact_staleness`
373
- # old. The timestamp is chosen soon after the read is started.
374
- #
375
- # Guarantees that all writes that have committed more than the
376
- # specified number of seconds ago are visible. Because Cloud Spanner
377
- # chooses the exact timestamp, this mode works even if the client's
378
- # local clock is substantially skewed from Cloud Spanner commit
379
- # timestamps.
380
- #
381
- # Useful for reading at nearby replicas without the distributed
382
- # timestamp negotiation overhead of `max_staleness`.
383
- # @!attribute [rw] return_read_timestamp
384
- # @return [true, false]
385
- # If true, the Cloud Spanner-selected read timestamp is included in
386
- # the {Google::Spanner::V1::Transaction Transaction} message that describes the transaction.
387
- class ReadOnly; end
388
- end
389
-
390
- # A transaction.
391
- # @!attribute [rw] id
392
- # @return [String]
393
- # `id` may be used to identify the transaction in subsequent
394
- # {Google::Spanner::V1::Spanner::Read Read},
395
- # {Google::Spanner::V1::Spanner::ExecuteSql ExecuteSql},
396
- # {Google::Spanner::V1::Spanner::Commit Commit}, or
397
- # {Google::Spanner::V1::Spanner::Rollback Rollback} calls.
398
- #
399
- # Single-use read-only transactions do not have IDs, because
400
- # single-use transactions do not support multiple requests.
401
- # @!attribute [rw] read_timestamp
402
- # @return [Google::Protobuf::Timestamp]
403
- # For snapshot read-only transactions, the read timestamp chosen
404
- # for the transaction. Not returned by default: see
405
- # {Google::Spanner::V1::TransactionOptions::ReadOnly#return_read_timestamp TransactionOptions::ReadOnly#return_read_timestamp}.
406
- #
407
- # A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.
408
- # Example: `"2014-10-02T15:01:23.045123456Z"`.
409
- class Transaction; end
410
-
411
- # This message is used to select the transaction in which a
412
- # {Google::Spanner::V1::Spanner::Read Read} or
413
- # {Google::Spanner::V1::Spanner::ExecuteSql ExecuteSql} call runs.
414
- #
415
- # See {Google::Spanner::V1::TransactionOptions TransactionOptions} for more information about transactions.
416
- # @!attribute [rw] single_use
417
- # @return [Google::Spanner::V1::TransactionOptions]
418
- # Execute the read or SQL query in a temporary transaction.
419
- # This is the most efficient way to execute a transaction that
420
- # consists of a single SQL query.
421
- # @!attribute [rw] id
422
- # @return [String]
423
- # Execute the read or SQL query in a previously-started transaction.
424
- # @!attribute [rw] begin
425
- # @return [Google::Spanner::V1::TransactionOptions]
426
- # Begin a new transaction and execute this read or SQL query in
427
- # it. The transaction ID of the new transaction is returned in
428
- # {Google::Spanner::V1::ResultSetMetadata#transaction ResultSetMetadata#transaction}, which is a {Google::Spanner::V1::Transaction Transaction}.
429
- class TransactionSelector; end
430
- end
431
- end
432
- end
@@ -1,112 +0,0 @@
1
- # Copyright 2020 Google LLC
2
- #
3
- # Licensed under the Apache License, Version 2.0 (the "License");
4
- # you may not use this file except in compliance with the License.
5
- # You may obtain a copy of the License at
6
- #
7
- # https://www.apache.org/licenses/LICENSE-2.0
8
- #
9
- # Unless required by applicable law or agreed to in writing, software
10
- # distributed under the License is distributed on an "AS IS" BASIS,
11
- # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12
- # See the License for the specific language governing permissions and
13
- # limitations under the License.
14
-
15
-
16
- module Google
17
- module Spanner
18
- module V1
19
- # `Type` indicates the type of a Cloud Spanner value, as might be stored in a
20
- # table cell or returned from an SQL query.
21
- # @!attribute [rw] code
22
- # @return [Google::Spanner::V1::TypeCode]
23
- # Required. The {Google::Spanner::V1::TypeCode TypeCode} for this type.
24
- # @!attribute [rw] array_element_type
25
- # @return [Google::Spanner::V1::Type]
26
- # If {Google::Spanner::V1::Type#code code} == {Google::Spanner::V1::TypeCode::ARRAY ARRAY}, then `array_element_type`
27
- # is the type of the array elements.
28
- # @!attribute [rw] struct_type
29
- # @return [Google::Spanner::V1::StructType]
30
- # If {Google::Spanner::V1::Type#code code} == {Google::Spanner::V1::TypeCode::STRUCT STRUCT}, then `struct_type`
31
- # provides type information for the struct's fields.
32
- class Type; end
33
-
34
- # `StructType` defines the fields of a {Google::Spanner::V1::TypeCode::STRUCT STRUCT} type.
35
- # @!attribute [rw] fields
36
- # @return [Array<Google::Spanner::V1::StructType::Field>]
37
- # The list of fields that make up this struct. Order is
38
- # significant, because values of this struct type are represented as
39
- # lists, where the order of field values matches the order of
40
- # fields in the {Google::Spanner::V1::StructType StructType}. In turn, the order of fields
41
- # matches the order of columns in a read request, or the order of
42
- # fields in the `SELECT` clause of a query.
43
- class StructType
44
- # Message representing a single field of a struct.
45
- # @!attribute [rw] name
46
- # @return [String]
47
- # The name of the field. For reads, this is the column name. For
48
- # SQL queries, it is the column alias (e.g., `"Word"` in the
49
- # query `"SELECT 'hello' AS Word"`), or the column name (e.g.,
50
- # `"ColName"` in the query `"SELECT ColName FROM Table"`). Some
51
- # columns might have an empty name (e.g., !"SELECT
52
- # UPPER(ColName)"`). Note that a query result can contain
53
- # multiple fields with the same name.
54
- # @!attribute [rw] type
55
- # @return [Google::Spanner::V1::Type]
56
- # The type of the field.
57
- class Field; end
58
- end
59
-
60
- # `TypeCode` is used as part of {Google::Spanner::V1::Type Type} to
61
- # indicate the type of a Cloud Spanner value.
62
- #
63
- # Each legal value of a type can be encoded to or decoded from a JSON
64
- # value, using the encodings described below. All Cloud Spanner values can
65
- # be `null`, regardless of type; `null`s are always encoded as a JSON
66
- # `null`.
67
- module TypeCode
68
- # Not specified.
69
- TYPE_CODE_UNSPECIFIED = 0
70
-
71
- # Encoded as JSON `true` or `false`.
72
- BOOL = 1
73
-
74
- # Encoded as `string`, in decimal format.
75
- INT64 = 2
76
-
77
- # Encoded as `number`, or the strings `"NaN"`, `"Infinity"`, or
78
- # `"-Infinity"`.
79
- FLOAT64 = 3
80
-
81
- # Encoded as `string` in RFC 3339 timestamp format. The time zone
82
- # must be present, and must be `"Z"`.
83
- #
84
- # If the schema has the column option
85
- # `allow_commit_timestamp=true`, the placeholder string
86
- # `"spanner.commit_timestamp()"` can be used to instruct the system
87
- # to insert the commit timestamp associated with the transaction
88
- # commit.
89
- TIMESTAMP = 4
90
-
91
- # Encoded as `string` in RFC 3339 date format.
92
- DATE = 5
93
-
94
- # Encoded as `string`.
95
- STRING = 6
96
-
97
- # Encoded as a base64-encoded `string`, as described in RFC 4648,
98
- # section 4.
99
- BYTES = 7
100
-
101
- # Encoded as `list`, where the list elements are represented
102
- # according to
103
- # {Google::Spanner::V1::Type#array_element_type array_element_type}.
104
- ARRAY = 8
105
-
106
- # Encoded as `list`, where list element `i` is represented according
107
- # to [struct_type.fields[i]][google.spanner.v1.StructType.fields].
108
- STRUCT = 9
109
- end
110
- end
111
- end
112
- end