Skip to content

Commit df51ec8

Browse files
Google APIscopybara-github
Google APIs
authored and
copybara-github
committed
feat: add Session creator role
docs: clarify transaction semantics PiperOrigin-RevId: 452634948
1 parent 13f9b89 commit df51ec8

9 files changed

Lines changed: 123 additions & 66 deletions

File tree

‎google/spanner/v1/commit_response.proto‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
// Copyright 2021 Google LLC
1+
// Copyright 2022 Google LLC
22
//
33
// Licensed under the Apache License, Version 2.0 (the "License");
44
// you may not use this file except in compliance with the License.

‎google/spanner/v1/keys.proto‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
// Copyright 2021 Google LLC
1+
// Copyright 2022 Google LLC
22
//
33
// Licensed under the Apache License, Version 2.0 (the "License");
44
// you may not use this file except in compliance with the License.

‎google/spanner/v1/mutation.proto‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
// Copyright 2021 Google LLC
1+
// Copyright 2022 Google LLC
22
//
33
// Licensed under the Apache License, Version 2.0 (the "License");
44
// you may not use this file except in compliance with the License.

‎google/spanner/v1/query_plan.proto‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
// Copyright 2021 Google LLC
1+
// Copyright 2022 Google LLC
22
//
33
// Licensed under the Apache License, Version 2.0 (the "License");
44
// you may not use this file except in compliance with the License.

‎google/spanner/v1/result_set.proto‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
// Copyright 2021 Google LLC
1+
// Copyright 2022 Google LLC
22
//
33
// Licensed under the Apache License, Version 2.0 (the "License");
44
// you may not use this file except in compliance with the License.
@@ -17,7 +17,6 @@ syntax = "proto3";
1717
package google.spanner.v1;
1818

1919
import "google/protobuf/struct.proto";
20-
import "google/spanner/v1/commit_response.proto";
2120
import "google/spanner/v1/query_plan.proto";
2221
import "google/spanner/v1/transaction.proto";
2322
import "google/spanner/v1/type.proto";

‎google/spanner/v1/spanner.proto‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
// Copyright 2021 Google LLC
1+
// Copyright 2022 Google LLC
22
//
33
// Licensed under the Apache License, Version 2.0 (the "License");
44
// you may not use this file except in compliance with the License.
@@ -358,6 +358,9 @@ message Session {
358358
// Output only. The approximate timestamp when the session is last used. It is
359359
// typically earlier than the actual last use time.
360360
google.protobuf.Timestamp approximate_last_use_time = 4 [(google.api.field_behavior) = OUTPUT_ONLY];
361+
362+
// The database role which created this session.
363+
string creator_role = 5;
361364
}
362365

363366
// The request for [GetSession][google.spanner.v1.Spanner.GetSession].

‎google/spanner/v1/spanner.yaml‎

Lines changed: 40 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -1,56 +1,59 @@
1-
# This service config is currently set for generating client libraries for the
2-
# non-admin API. Use the spanner_admin_*.yaml service configs to generate admin
3-
# client libraries.
4-
51
type: google.api.Service
62
config_version: 3
73
name: spanner.googleapis.com
84
title: Cloud Spanner API
95

106
apis:
11-
- name: google.spanner.v1.Spanner
7+
- name: google.spanner.v1.Spanner
128

13-
authentication:
9+
documentation:
10+
summary: |-
11+
Cloud Spanner is a managed, mission-critical, globally consistent and
12+
scalable relational database service.
13+
14+
backend:
1415
rules:
15-
- selector: google.spanner.v1.Spanner.*
16-
oauth:
17-
canonical_scopes: https://www.googleapis.com/auth/spanner.data,
18-
https://www.googleapis.com/auth/cloud-platform
16+
- selector: 'google.longrunning.Operations.*'
17+
deadline: 3600.0
18+
- selector: 'google.spanner.v1.Spanner.*'
19+
deadline: 3600.0
1920

2021
http:
2122
rules:
22-
- selector: google.longrunning.Operations.GetOperation
23-
get: '/v1/{name=projects/*/instances/*/databases/*/operations/*}'
24-
additional_bindings:
25-
- get: '/v1/{name=projects/*/instances/*/operations/*}'
26-
- selector: google.longrunning.Operations.ListOperations
27-
get: '/v1/{name=projects/*/instances/*/databases/*/operations}'
28-
additional_bindings:
29-
- get: '/v1/{name=projects/*/instances/*/operations}'
3023
- selector: google.longrunning.Operations.CancelOperation
3124
post: '/v1/{name=projects/*/instances/*/databases/*/operations/*}:cancel'
3225
additional_bindings:
33-
- post: '/v1/{name=projects/*/instances/*/operations/*}:cancel'
26+
- post: '/v1/{name=projects/*/instances/*/operations/*}:cancel'
27+
- post: '/v1/{name=projects/*/instances/*/backups/*/operations/*}:cancel'
28+
- post: '/v1/{name=projects/*/instanceConfigs/*/operations/*}:cancel'
3429
- selector: google.longrunning.Operations.DeleteOperation
3530
delete: '/v1/{name=projects/*/instances/*/databases/*/operations/*}'
3631
additional_bindings:
37-
- delete: '/v1/{name=projects/*/instances/*/operations/*}'
38-
39-
documentation:
40-
summary:
41-
Cloud Spanner is a managed, mission-critical, globally consistent and scalable relational database service.
32+
- delete: '/v1/{name=projects/*/instances/*/operations/*}'
33+
- delete: '/v1/{name=projects/*/instances/*/backups/*/operations/*}'
34+
- delete: '/v1/{name=projects/*/instanceConfigs/*/operations/*}'
35+
- selector: google.longrunning.Operations.GetOperation
36+
get: '/v1/{name=projects/*/instances/*/databases/*/operations/*}'
37+
additional_bindings:
38+
- get: '/v1/{name=projects/*/instances/*/operations/*}'
39+
- get: '/v1/{name=projects/*/instances/*/backups/*/operations/*}'
40+
- get: '/v1/{name=projects/*/instanceConfigs/*/operations/*}'
41+
- selector: google.longrunning.Operations.ListOperations
42+
get: '/v1/{name=projects/*/instances/*/databases/*/operations}'
43+
additional_bindings:
44+
- get: '/v1/{name=projects/*/instances/*/operations}'
45+
- get: '/v1/{name=projects/*/instances/*/backups/*/operations}'
46+
- get: '/v1/{name=projects/*/instanceConfigs/*/operations}'
4247

48+
authentication:
4349
rules:
44-
- selector: google.iam.v1.SetIamPolicyRequest.resource
45-
description: |
46-
REQUIRED: The Cloud Spanner resource for which the policy is being set. The format is `projects/<project ID>/instances/<instance ID>` for instance resources and `projects/<project ID>/instances/<instance ID>/databases/<database ID>` for databases resources.
47-
- selector: google.iam.v1.GetIamPolicyRequest.resource
48-
description: |
49-
REQUIRED: The Cloud Spanner resource for which the policy is being retrieved. The format is `projects/<project ID>/instances/<instance ID>` for instance resources and `projects/<project ID>/instances/<instance ID>/databases/<database ID>` for database resources.
50-
- selector: google.iam.v1.TestIamPermissionsRequest.resource
51-
description: |
52-
REQUIRED: The Cloud Spanner resource for which permissions are being tested. The format is `projects/<project ID>/instances/<instance ID>` for instance resources and `projects/<project ID>/instances/<instance ID>/databases/<database ID>` for database resources.
53-
- selector: google.iam.v1.TestIamPermissionsRequest.permissions
54-
description: |
55-
REQUIRED: The set of permissions to check for 'resource'.
56-
Permissions with wildcards (such as '*', 'spanner.*', 'spanner.instances.*') are not allowed.
50+
- selector: 'google.longrunning.Operations.*'
51+
oauth:
52+
canonical_scopes: |-
53+
https://www.googleapis.com/auth/cloud-platform,
54+
https://www.googleapis.com/auth/spanner.admin
55+
- selector: 'google.spanner.v1.Spanner.*'
56+
oauth:
57+
canonical_scopes: |-
58+
https://www.googleapis.com/auth/cloud-platform,
59+
https://www.googleapis.com/auth/spanner.data

‎google/spanner/v1/transaction.proto‎

Lines changed: 73 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
// Copyright 2021 Google LLC
1+
// Copyright 2022 Google LLC
22
//
33
// Licensed under the Apache License, Version 2.0 (the "License");
44
// you may not use this file except in compliance with the License.
@@ -35,7 +35,8 @@ option ruby_package = "Google::Cloud::Spanner::V1";
3535
// completed, the session can immediately be re-used for the next transaction.
3636
// It is not necessary to create a new session for each transaction.
3737
//
38-
// Transaction Modes:
38+
// Transaction modes:
39+
//
3940
// Cloud Spanner supports three transaction modes:
4041
//
4142
// 1. Locking read-write. This type of transaction is the only way
@@ -44,11 +45,18 @@ option ruby_package = "Google::Cloud::Spanner::V1";
4445
// Locking read-write transactions may abort, requiring the
4546
// application to retry.
4647
//
47-
// 2. Snapshot read-only. This transaction type provides guaranteed
48-
// consistency across several reads, but does not allow
49-
// writes. Snapshot read-only transactions can be configured to
50-
// read at timestamps in the past. Snapshot read-only
51-
// transactions do not need to be committed.
48+
// 2. Snapshot read-only. Snapshot read-only transactions provide guaranteed
49+
// consistency across several reads, but do not allow
50+
// writes. Snapshot read-only transactions can be configured to read at
51+
// timestamps in the past, or configured to perform a strong read
52+
// (where Spanner will select a timestamp such that the read is
53+
// guaranteed to see the effects of all transactions that have committed
54+
// before the start of the read). Snapshot read-only transactions do not
55+
// need to be committed.
56+
//
57+
// Queries on change streams must be performed with the snapshot read-only
58+
// transaction mode, specifying a strong read. Please see
59+
// [TransactionOptions.ReadOnly.strong][google.spanner.v1.TransactionOptions.ReadOnly.strong] for more details.
5260
//
5361
// 3. Partitioned DML. This type of transaction is used to execute
5462
// a single Partitioned DML statement. Partitioned DML partitions
@@ -63,11 +71,12 @@ option ruby_package = "Google::Cloud::Spanner::V1";
6371
// not conflict with read-write transactions. As a consequence of not
6472
// taking locks, they also do not abort, so retry loops are not needed.
6573
//
66-
// Transactions may only read/write data in a single database. They
67-
// may, however, read/write data in different tables within that
74+
// Transactions may only read-write data in a single database. They
75+
// may, however, read-write data in different tables within that
6876
// database.
6977
//
70-
// Locking Read-Write Transactions:
78+
// Locking read-write transactions:
79+
//
7180
// Locking transactions may be used to atomically read-modify-write
7281
// data anywhere in a database. This type of transaction is externally
7382
// consistent.
@@ -78,7 +87,7 @@ option ruby_package = "Google::Cloud::Spanner::V1";
7887
// active as long as the transaction continues to do reads, and the
7988
// transaction has not been terminated by
8089
// [Commit][google.spanner.v1.Spanner.Commit] or
81-
// [Rollback][google.spanner.v1.Spanner.Rollback]. Long periods of
90+
// [Rollback][google.spanner.v1.Spanner.Rollback]. Long periods of
8291
// inactivity at the client may cause Cloud Spanner to release a
8392
// transaction's locks and abort it.
8493
//
@@ -90,6 +99,7 @@ option ruby_package = "Google::Cloud::Spanner::V1";
9099
// transaction.
91100
//
92101
// Semantics:
102+
//
93103
// Cloud Spanner can commit the transaction if all read locks it acquired
94104
// are still valid at commit time, and it is able to acquire write
95105
// locks for all writes. Cloud Spanner can abort the transaction for any
@@ -101,7 +111,8 @@ option ruby_package = "Google::Cloud::Spanner::V1";
101111
// use Cloud Spanner locks for any sort of mutual exclusion other than
102112
// between Cloud Spanner transactions themselves.
103113
//
104-
// Retrying Aborted Transactions:
114+
// Retrying aborted transactions:
115+
//
105116
// When a transaction aborts, the application can choose to retry the
106117
// whole transaction again. To maximize the chances of successfully
107118
// committing the retry, the client should execute the retry in the
@@ -116,7 +127,8 @@ option ruby_package = "Google::Cloud::Spanner::V1";
116127
// instead, it is better to limit the total amount of time spent
117128
// retrying.
118129
//
119-
// Idle Transactions:
130+
// Idle transactions:
131+
//
120132
// A transaction is considered idle if it has no outstanding reads or
121133
// SQL queries and has not started a read or SQL query within the last 10
122134
// seconds. Idle transactions can be aborted by Cloud Spanner so that they
@@ -127,7 +139,8 @@ option ruby_package = "Google::Cloud::Spanner::V1";
127139
// SQL query in the transaction (for example, `SELECT 1`) prevents the
128140
// transaction from becoming idle.
129141
//
130-
// Snapshot Read-Only Transactions:
142+
// Snapshot read-only transactions:
143+
//
131144
// Snapshot read-only transactions provides a simpler method than
132145
// locking read-write transactions for doing several consistent
133146
// reads. However, this type of transaction does not support writes.
@@ -159,13 +172,12 @@ option ruby_package = "Google::Cloud::Spanner::V1";
159172
//
160173
// If the Cloud Spanner database to be read is geographically distributed,
161174
// stale read-only transactions can execute more quickly than strong
162-
// or read-write transaction, because they are able to execute far
175+
// or read-write transactions, because they are able to execute far
163176
// from the leader replica.
164177
//
165178
// Each type of timestamp bound is discussed in detail below.
166179
//
167-
// Strong:
168-
// Strong reads are guaranteed to see the effects of all transactions
180+
// Strong: Strong reads are guaranteed to see the effects of all transactions
169181
// that have committed before the start of the read. Furthermore, all
170182
// rows yielded by a single read are consistent with each other -- if
171183
// any part of the read observes a transaction, all parts of the read
@@ -177,9 +189,13 @@ option ruby_package = "Google::Cloud::Spanner::V1";
177189
// reads should be executed within a transaction or at an exact read
178190
// timestamp.
179191
//
192+
// Queries on change streams (see below for more details) must also specify
193+
// the strong read timestamp bound.
194+
//
180195
// See [TransactionOptions.ReadOnly.strong][google.spanner.v1.TransactionOptions.ReadOnly.strong].
181196
//
182-
// Exact Staleness:
197+
// Exact staleness:
198+
//
183199
// These timestamp bounds execute reads at a user-specified
184200
// timestamp. Reads at a timestamp are guaranteed to see a consistent
185201
// prefix of the global transaction history: they observe
@@ -200,7 +216,8 @@ option ruby_package = "Google::Cloud::Spanner::V1";
200216
// See [TransactionOptions.ReadOnly.read_timestamp][google.spanner.v1.TransactionOptions.ReadOnly.read_timestamp] and
201217
// [TransactionOptions.ReadOnly.exact_staleness][google.spanner.v1.TransactionOptions.ReadOnly.exact_staleness].
202218
//
203-
// Bounded Staleness:
219+
// Bounded staleness:
220+
//
204221
// Bounded staleness modes allow Cloud Spanner to pick the read timestamp,
205222
// subject to a user-provided staleness bound. Cloud Spanner chooses the
206223
// newest timestamp within the staleness bound that allows execution
@@ -229,7 +246,8 @@ option ruby_package = "Google::Cloud::Spanner::V1";
229246
// See [TransactionOptions.ReadOnly.max_staleness][google.spanner.v1.TransactionOptions.ReadOnly.max_staleness] and
230247
// [TransactionOptions.ReadOnly.min_read_timestamp][google.spanner.v1.TransactionOptions.ReadOnly.min_read_timestamp].
231248
//
232-
// Old Read Timestamps and Garbage Collection:
249+
// Old read timestamps and garbage collection:
250+
//
233251
// Cloud Spanner continuously garbage collects deleted and overwritten data
234252
// in the background to reclaim storage space. This process is known
235253
// as "version GC". By default, version GC reclaims versions after they
@@ -239,7 +257,41 @@ option ruby_package = "Google::Cloud::Spanner::V1";
239257
// timestamp become too old while executing. Reads and SQL queries with
240258
// too-old read timestamps fail with the error `FAILED_PRECONDITION`.
241259
//
242-
// Partitioned DML Transactions:
260+
// You can configure and extend the `VERSION_RETENTION_PERIOD` of a
261+
// database up to a period as long as one week, which allows Cloud Spanner
262+
// to perform reads up to one week in the past.
263+
//
264+
// Querying change Streams:
265+
//
266+
// A Change Stream is a schema object that can be configured to watch data
267+
// changes on the entire database, a set of tables, or a set of columns
268+
// in a database.
269+
//
270+
// When a change stream is created, Spanner automatically defines a
271+
// corresponding SQL Table-Valued Function (TVF) that can be used to query
272+
// the change records in the associated change stream using the
273+
// ExecuteStreamingSql API. The name of the TVF for a change stream is
274+
// generated from the name of the change stream: READ_<change_stream_name>.
275+
//
276+
// All queries on change stream TVFs must be executed using the
277+
// ExecuteStreamingSql API with a single-use read-only transaction with a
278+
// strong read-only timestamp_bound. The change stream TVF allows users to
279+
// specify the start_timestamp and end_timestamp for the time range of
280+
// interest. All change records within the retention period is accessible
281+
// using the strong read-only timestamp_bound. All other TransactionOptions
282+
// are invalid for change stream queries.
283+
//
284+
// In addition, if TransactionOptions.read_only.return_read_timestamp is set
285+
// to true, a special value of 2^63 - 2 will be returned in the
286+
// [Transaction][google.spanner.v1.Transaction] message that describes the
287+
// transaction, instead of a valid read timestamp. This special value should be
288+
// discarded and not used for any subsequent queries.
289+
//
290+
// Please see https://cloud.google.com/spanner/docs/change-streams
291+
// for more details on how to query the change stream TVFs.
292+
//
293+
// Partitioned DML transactions:
294+
//
243295
// Partitioned DML transactions are used to execute DML statements with a
244296
// different execution strategy that provides different, and often better,
245297
// scalability properties for large, table-wide operations than DML in a

‎google/spanner/v1/type.proto‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
// Copyright 2021 Google LLC
1+
// Copyright 2022 Google LLC
22
//
33
// Licensed under the Apache License, Version 2.0 (the "License");
44
// you may not use this file except in compliance with the License.

0 commit comments

Comments
 (0)