google-cloud-spanner 1.6.3 → 1.6.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/CHANGELOG.md +8 -0
- data/LOGGING.md +1 -1
- data/OVERVIEW.md +1 -1
- data/lib/google/cloud/spanner/admin/database/v1/database_admin_client.rb +29 -29
- data/lib/google/cloud/spanner/admin/database/v1/doc/google/iam/v1/iam_policy.rb +13 -13
- data/lib/google/cloud/spanner/admin/database/v1/doc/google/iam/v1/policy.rb +28 -28
- data/lib/google/cloud/spanner/admin/database/v1/doc/google/longrunning/operations.rb +9 -9
- data/lib/google/cloud/spanner/admin/database/v1/doc/google/protobuf/any.rb +8 -8
- data/lib/google/cloud/spanner/admin/database/v1/doc/google/protobuf/empty.rb +1 -1
- data/lib/google/cloud/spanner/admin/database/v1/doc/google/rpc/status.rb +11 -11
- data/lib/google/cloud/spanner/admin/database/v1/doc/google/spanner/admin/database/v1/spanner_database_admin.rb +21 -21
- data/lib/google/cloud/spanner/admin/database/v1.rb +4 -4
- data/lib/google/cloud/spanner/admin/database.rb +4 -4
- data/lib/google/cloud/spanner/admin/instance/v1/doc/google/iam/v1/iam_policy.rb +13 -13
- data/lib/google/cloud/spanner/admin/instance/v1/doc/google/iam/v1/policy.rb +28 -28
- data/lib/google/cloud/spanner/admin/instance/v1/doc/google/longrunning/operations.rb +9 -9
- data/lib/google/cloud/spanner/admin/instance/v1/doc/google/protobuf/any.rb +8 -8
- data/lib/google/cloud/spanner/admin/instance/v1/doc/google/protobuf/empty.rb +1 -1
- data/lib/google/cloud/spanner/admin/instance/v1/doc/google/protobuf/field_mask.rb +7 -7
- data/lib/google/cloud/spanner/admin/instance/v1/doc/google/rpc/status.rb +11 -11
- data/lib/google/cloud/spanner/admin/instance/v1/doc/google/spanner/admin/instance/v1/spanner_instance_admin.rb +30 -30
- data/lib/google/cloud/spanner/admin/instance/v1/instance_admin_client.rb +44 -44
- data/lib/google/cloud/spanner/admin/instance/v1.rb +4 -4
- data/lib/google/cloud/spanner/admin/instance.rb +4 -4
- data/lib/google/cloud/spanner/v1/doc/google/protobuf/duration.rb +3 -3
- data/lib/google/cloud/spanner/v1/doc/google/protobuf/empty.rb +1 -1
- data/lib/google/cloud/spanner/v1/doc/google/protobuf/struct.rb +11 -11
- data/lib/google/cloud/spanner/v1/doc/google/protobuf/timestamp.rb +7 -7
- data/lib/google/cloud/spanner/v1/doc/google/spanner/v1/keys.rb +19 -19
- data/lib/google/cloud/spanner/v1/doc/google/spanner/v1/mutation.rb +6 -6
- data/lib/google/cloud/spanner/v1/doc/google/spanner/v1/query_plan.rb +11 -11
- data/lib/google/cloud/spanner/v1/doc/google/spanner/v1/result_set.rb +33 -19
- data/lib/google/cloud/spanner/v1/doc/google/spanner/v1/spanner.rb +65 -39
- data/lib/google/cloud/spanner/v1/doc/google/spanner/v1/transaction.rb +91 -21
- data/lib/google/cloud/spanner/v1/doc/google/spanner/v1/type.rb +25 -25
- data/lib/google/cloud/spanner/v1/spanner_client.rb +139 -79
- data/lib/google/cloud/spanner/version.rb +1 -1
- data/lib/google/spanner/admin/database/v1/spanner_database_admin_services_pb.rb +1 -1
- data/lib/google/spanner/admin/instance/v1/spanner_instance_admin_services_pb.rb +1 -1
- data/lib/google/spanner/v1/result_set_pb.rb +4 -0
- data/lib/google/spanner/v1/spanner_pb.rb +1 -0
- data/lib/google/spanner/v1/spanner_services_pb.rb +14 -6
- data/lib/google/spanner/v1/transaction_pb.rb +4 -0
- data/lib/google-cloud-spanner.rb +1 -1
- metadata +3 -3
@@ -25,7 +25,7 @@ module Google
|
|
25
25
|
#
|
26
26
|
# = Transaction Modes
|
27
27
|
#
|
28
|
-
# Cloud Spanner supports
|
28
|
+
# Cloud Spanner supports three transaction modes:
|
29
29
|
#
|
30
30
|
# 1. Locking read-write. This type of transaction is the only way
|
31
31
|
# to write data into Cloud Spanner. These transactions rely on
|
@@ -39,6 +39,13 @@ module Google
|
|
39
39
|
# read at timestamps in the past. Snapshot read-only
|
40
40
|
# transactions do not need to be committed.
|
41
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
|
+
#
|
42
49
|
# For transactions that only read, snapshot read-only transactions
|
43
50
|
# provide simpler semantics and are almost always faster. In
|
44
51
|
# particular, read-only transactions do not take locks, so they do
|
@@ -65,11 +72,8 @@ module Google
|
|
65
72
|
# inactivity at the client may cause Cloud Spanner to release a
|
66
73
|
# transaction's locks and abort it.
|
67
74
|
#
|
68
|
-
# Reads performed within a transaction acquire locks on the data
|
69
|
-
# being read. Writes can only be done at commit time, after all reads
|
70
|
-
# have been completed.
|
71
75
|
# Conceptually, a read-write transaction consists of zero or more
|
72
|
-
# reads or SQL
|
76
|
+
# reads or SQL statements followed by
|
73
77
|
# {Google::Spanner::V1::Spanner::Commit Commit}. At any time before
|
74
78
|
# {Google::Spanner::V1::Spanner::Commit Commit}, the client can send a
|
75
79
|
# {Google::Spanner::V1::Spanner::Rollback Rollback} request to abort the
|
@@ -80,7 +84,7 @@ module Google
|
|
80
84
|
# Cloud Spanner can commit the transaction if all read locks it acquired
|
81
85
|
# are still valid at commit time, and it is able to acquire write
|
82
86
|
# locks for all writes. Cloud Spanner can abort the transaction for any
|
83
|
-
# reason. If a commit attempt returns
|
87
|
+
# reason. If a commit attempt returns `ABORTED`, Cloud Spanner guarantees
|
84
88
|
# that the transaction has not modified any user data in Cloud Spanner.
|
85
89
|
#
|
86
90
|
# Unless the transaction commits, Cloud Spanner makes no guarantees about
|
@@ -110,10 +114,10 @@ module Google
|
|
110
114
|
# SQL queries and has not started a read or SQL query within the last 10
|
111
115
|
# seconds. Idle transactions can be aborted by Cloud Spanner so that they
|
112
116
|
# don't hold on to locks indefinitely. In that case, the commit will
|
113
|
-
# fail with error
|
117
|
+
# fail with error `ABORTED`.
|
114
118
|
#
|
115
119
|
# If this behavior is undesirable, periodically executing a simple
|
116
|
-
# SQL query in the transaction (e.g.,
|
120
|
+
# SQL query in the transaction (e.g., `SELECT 1`) prevents the
|
117
121
|
# transaction from becoming idle.
|
118
122
|
#
|
119
123
|
# == Snapshot Read-Only Transactions
|
@@ -231,26 +235,92 @@ module Google
|
|
231
235
|
# at read timestamps more than one hour in the past. This
|
232
236
|
# restriction also applies to in-progress reads and/or SQL queries whose
|
233
237
|
# timestamp become too old while executing. Reads and SQL queries with
|
234
|
-
# too-old read timestamps fail with the error
|
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.
|
235
295
|
# @!attribute [rw] read_write
|
236
296
|
# @return [Google::Spanner::V1::TransactionOptions::ReadWrite]
|
237
297
|
# Transaction may write.
|
238
298
|
#
|
239
299
|
# Authorization to begin a read-write transaction requires
|
240
|
-
#
|
241
|
-
# on the
|
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.
|
242
309
|
# @!attribute [rw] read_only
|
243
310
|
# @return [Google::Spanner::V1::TransactionOptions::ReadOnly]
|
244
311
|
# Transaction will not write.
|
245
312
|
#
|
246
313
|
# Authorization to begin a read-only transaction requires
|
247
|
-
#
|
248
|
-
# on the
|
314
|
+
# `spanner.databases.beginReadOnlyTransaction` permission
|
315
|
+
# on the `session` resource.
|
249
316
|
class TransactionOptions
|
250
317
|
# Message type to initiate a read-write transaction. Currently this
|
251
318
|
# transaction type has no options.
|
252
319
|
class ReadWrite; end
|
253
320
|
|
321
|
+
# Message type to initiate a Partitioned DML transaction.
|
322
|
+
class PartitionedDml; end
|
323
|
+
|
254
324
|
# Message type to initiate a read-only transaction.
|
255
325
|
# @!attribute [rw] strong
|
256
326
|
# @return [true, false]
|
@@ -258,7 +328,7 @@ module Google
|
|
258
328
|
# are visible.
|
259
329
|
# @!attribute [rw] min_read_timestamp
|
260
330
|
# @return [Google::Protobuf::Timestamp]
|
261
|
-
# Executes all reads at a timestamp >=
|
331
|
+
# Executes all reads at a timestamp >= `min_read_timestamp`.
|
262
332
|
#
|
263
333
|
# This is useful for requesting fresher data than some previous
|
264
334
|
# read, or data that is fresh enough to observe the effects of some
|
@@ -267,10 +337,10 @@ module Google
|
|
267
337
|
# Note that this option can only be used in single-use transactions.
|
268
338
|
#
|
269
339
|
# A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.
|
270
|
-
# Example:
|
340
|
+
# Example: `"2014-10-02T15:01:23.045123456Z"`.
|
271
341
|
# @!attribute [rw] max_staleness
|
272
342
|
# @return [Google::Protobuf::Duration]
|
273
|
-
# Read data at a timestamp >=
|
343
|
+
# Read data at a timestamp >= `NOW - max_staleness`
|
274
344
|
# seconds. Guarantees that all writes that have committed more
|
275
345
|
# than the specified number of seconds ago are visible. Because
|
276
346
|
# Cloud Spanner chooses the exact timestamp, this mode works even if
|
@@ -296,10 +366,10 @@ module Google
|
|
296
366
|
# data.
|
297
367
|
#
|
298
368
|
# A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.
|
299
|
-
# Example:
|
369
|
+
# Example: `"2014-10-02T15:01:23.045123456Z"`.
|
300
370
|
# @!attribute [rw] exact_staleness
|
301
371
|
# @return [Google::Protobuf::Duration]
|
302
|
-
# Executes all reads at a timestamp that is
|
372
|
+
# Executes all reads at a timestamp that is `exact_staleness`
|
303
373
|
# old. The timestamp is chosen soon after the read is started.
|
304
374
|
#
|
305
375
|
# Guarantees that all writes that have committed more than the
|
@@ -309,7 +379,7 @@ module Google
|
|
309
379
|
# timestamps.
|
310
380
|
#
|
311
381
|
# Useful for reading at nearby replicas without the distributed
|
312
|
-
# timestamp negotiation overhead of
|
382
|
+
# timestamp negotiation overhead of `max_staleness`.
|
313
383
|
# @!attribute [rw] return_read_timestamp
|
314
384
|
# @return [true, false]
|
315
385
|
# If true, the Cloud Spanner-selected read timestamp is included in
|
@@ -320,7 +390,7 @@ module Google
|
|
320
390
|
# A transaction.
|
321
391
|
# @!attribute [rw] id
|
322
392
|
# @return [String]
|
323
|
-
#
|
393
|
+
# `id` may be used to identify the transaction in subsequent
|
324
394
|
# {Google::Spanner::V1::Spanner::Read Read},
|
325
395
|
# {Google::Spanner::V1::Spanner::ExecuteSql ExecuteSql},
|
326
396
|
# {Google::Spanner::V1::Spanner::Commit Commit}, or
|
@@ -335,7 +405,7 @@ module Google
|
|
335
405
|
# {Google::Spanner::V1::TransactionOptions::ReadOnly#return_read_timestamp TransactionOptions::ReadOnly#return_read_timestamp}.
|
336
406
|
#
|
337
407
|
# A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.
|
338
|
-
# Example:
|
408
|
+
# Example: `"2014-10-02T15:01:23.045123456Z"`.
|
339
409
|
class Transaction; end
|
340
410
|
|
341
411
|
# This message is used to select the transaction in which a
|
@@ -16,22 +16,22 @@
|
|
16
16
|
module Google
|
17
17
|
module Spanner
|
18
18
|
module V1
|
19
|
-
#
|
19
|
+
# `Type` indicates the type of a Cloud Spanner value, as might be stored in a
|
20
20
|
# table cell or returned from an SQL query.
|
21
21
|
# @!attribute [rw] code
|
22
22
|
# @return [Google::Spanner::V1::TypeCode]
|
23
23
|
# Required. The {Google::Spanner::V1::TypeCode TypeCode} for this type.
|
24
24
|
# @!attribute [rw] array_element_type
|
25
25
|
# @return [Google::Spanner::V1::Type]
|
26
|
-
# If {Google::Spanner::V1::Type#code code} == {Google::Spanner::V1::TypeCode::ARRAY ARRAY}, then
|
26
|
+
# If {Google::Spanner::V1::Type#code code} == {Google::Spanner::V1::TypeCode::ARRAY ARRAY}, then `array_element_type`
|
27
27
|
# is the type of the array elements.
|
28
28
|
# @!attribute [rw] struct_type
|
29
29
|
# @return [Google::Spanner::V1::StructType]
|
30
|
-
# If {Google::Spanner::V1::Type#code code} == {Google::Spanner::V1::TypeCode::STRUCT STRUCT}, then
|
30
|
+
# If {Google::Spanner::V1::Type#code code} == {Google::Spanner::V1::TypeCode::STRUCT STRUCT}, then `struct_type`
|
31
31
|
# provides type information for the struct's fields.
|
32
32
|
class Type; end
|
33
33
|
|
34
|
-
#
|
34
|
+
# `StructType` defines the fields of a {Google::Spanner::V1::TypeCode::STRUCT STRUCT} type.
|
35
35
|
# @!attribute [rw] fields
|
36
36
|
# @return [Array<Google::Spanner::V1::StructType::Field>]
|
37
37
|
# The list of fields that make up this struct. Order is
|
@@ -39,17 +39,17 @@ module Google
|
|
39
39
|
# lists, where the order of field values matches the order of
|
40
40
|
# fields in the {Google::Spanner::V1::StructType StructType}. In turn, the order of fields
|
41
41
|
# matches the order of columns in a read request, or the order of
|
42
|
-
# fields in the
|
42
|
+
# fields in the `SELECT` clause of a query.
|
43
43
|
class StructType
|
44
44
|
# Message representing a single field of a struct.
|
45
45
|
# @!attribute [rw] name
|
46
46
|
# @return [String]
|
47
47
|
# The name of the field. For reads, this is the column name. For
|
48
|
-
# SQL queries, it is the column alias (e.g.,
|
49
|
-
# query
|
50
|
-
#
|
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
51
|
# columns might have an empty name (e.g., !"SELECT
|
52
|
-
# UPPER(ColName)"
|
52
|
+
# UPPER(ColName)"`). Note that a query result can contain
|
53
53
|
# multiple fields with the same name.
|
54
54
|
# @!attribute [rw] type
|
55
55
|
# @return [Google::Spanner::V1::Type]
|
@@ -57,52 +57,52 @@ module Google
|
|
57
57
|
class Field; end
|
58
58
|
end
|
59
59
|
|
60
|
-
#
|
60
|
+
# `TypeCode` is used as part of {Google::Spanner::V1::Type Type} to
|
61
61
|
# indicate the type of a Cloud Spanner value.
|
62
62
|
#
|
63
63
|
# Each legal value of a type can be encoded to or decoded from a JSON
|
64
64
|
# value, using the encodings described below. All Cloud Spanner values can
|
65
|
-
# be
|
66
|
-
#
|
65
|
+
# be `null`, regardless of type; `null`s are always encoded as a JSON
|
66
|
+
# `null`.
|
67
67
|
module TypeCode
|
68
68
|
# Not specified.
|
69
69
|
TYPE_CODE_UNSPECIFIED = 0
|
70
70
|
|
71
|
-
# Encoded as JSON
|
71
|
+
# Encoded as JSON `true` or `false`.
|
72
72
|
BOOL = 1
|
73
73
|
|
74
|
-
# Encoded as
|
74
|
+
# Encoded as `string`, in decimal format.
|
75
75
|
INT64 = 2
|
76
76
|
|
77
|
-
# Encoded as
|
78
|
-
#
|
77
|
+
# Encoded as `number`, or the strings `"NaN"`, `"Infinity"`, or
|
78
|
+
# `"-Infinity"`.
|
79
79
|
FLOAT64 = 3
|
80
80
|
|
81
|
-
# Encoded as
|
82
|
-
# must be present, and must be
|
81
|
+
# Encoded as `string` in RFC 3339 timestamp format. The time zone
|
82
|
+
# must be present, and must be `"Z"`.
|
83
83
|
#
|
84
84
|
# If the schema has the column option
|
85
|
-
#
|
86
|
-
#
|
85
|
+
# `allow_commit_timestamp=true`, the placeholder string
|
86
|
+
# `"spanner.commit_timestamp()"` can be used to instruct the system
|
87
87
|
# to insert the commit timestamp associated with the transaction
|
88
88
|
# commit.
|
89
89
|
TIMESTAMP = 4
|
90
90
|
|
91
|
-
# Encoded as
|
91
|
+
# Encoded as `string` in RFC 3339 date format.
|
92
92
|
DATE = 5
|
93
93
|
|
94
|
-
# Encoded as
|
94
|
+
# Encoded as `string`.
|
95
95
|
STRING = 6
|
96
96
|
|
97
|
-
# Encoded as a base64-encoded
|
97
|
+
# Encoded as a base64-encoded `string`, as described in RFC 4648,
|
98
98
|
# section 4.
|
99
99
|
BYTES = 7
|
100
100
|
|
101
|
-
# Encoded as
|
101
|
+
# Encoded as `list`, where the list elements are represented
|
102
102
|
# according to {Google::Spanner::V1::Type#array_element_type array_element_type}.
|
103
103
|
ARRAY = 8
|
104
104
|
|
105
|
-
# Encoded as
|
105
|
+
# Encoded as `list`, where list element `i` is represented according
|
106
106
|
# to [struct_type.fields[i]][google.spanner.v1.StructType.fields].
|
107
107
|
STRUCT = 9
|
108
108
|
end
|