feat: add Session creator role

docs: clarify transaction semantics

PiperOrigin-RevId: 452634948

google/spanner/v1/commit_response.proto

@@ -1,4 +1,4 @@
-// Copyright 2021 Google LLC
+// Copyright 2022 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.

google/spanner/v1/keys.proto

@@ -1,4 +1,4 @@
-// Copyright 2021 Google LLC
+// Copyright 2022 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.

google/spanner/v1/mutation.proto

@@ -1,4 +1,4 @@
-// Copyright 2021 Google LLC
+// Copyright 2022 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.

google/spanner/v1/query_plan.proto

@@ -1,4 +1,4 @@
-// Copyright 2021 Google LLC
+// Copyright 2022 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.

google/spanner/v1/result_set.proto

@@ -1,4 +1,4 @@
-// Copyright 2021 Google LLC
+// Copyright 2022 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -17,7 +17,6 @@ syntax = "proto3";
 package google.spanner.v1;
 
 import "google/protobuf/struct.proto";
-import "google/spanner/v1/commit_response.proto";
 import "google/spanner/v1/query_plan.proto";
 import "google/spanner/v1/transaction.proto";
 import "google/spanner/v1/type.proto";

google/spanner/v1/spanner.proto

@@ -1,4 +1,4 @@
-// Copyright 2021 Google LLC
+// Copyright 2022 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -358,6 +358,9 @@ message Session {
   // Output only. The approximate timestamp when the session is last used. It is
   // typically earlier than the actual last use time.
   google.protobuf.Timestamp approximate_last_use_time = 4 [(google.api.field_behavior) = OUTPUT_ONLY];
+
+  // The database role which created this session.
+  string creator_role = 5;
 }
 
 // The request for [GetSession][google.spanner.v1.Spanner.GetSession].

google/spanner/v1/spanner.yaml

@@ -1,56 +1,59 @@
-# This service config is currently set for generating client libraries for the
-# non-admin API. Use the spanner_admin_*.yaml service configs to generate admin
-# client libraries.
-
 type: google.api.Service
 config_version: 3
 name: spanner.googleapis.com
 title: Cloud Spanner API
 
 apis:
-  - name: google.spanner.v1.Spanner
+- name: google.spanner.v1.Spanner
 
-authentication:
+documentation:
+  summary: |-
+    Cloud Spanner is a managed, mission-critical, globally consistent and
+    scalable relational database service.
+
+backend:
   rules:
-  - selector: google.spanner.v1.Spanner.*
-    oauth:
-      canonical_scopes: https://www.googleapis.com/auth/spanner.data,
-                        https://www.googleapis.com/auth/cloud-platform
+  - selector: 'google.longrunning.Operations.*'
+    deadline: 3600.0
+  - selector: 'google.spanner.v1.Spanner.*'
+    deadline: 3600.0
 
 http:
   rules:
-  - selector: google.longrunning.Operations.GetOperation
-    get: '/v1/{name=projects/*/instances/*/databases/*/operations/*}'
-    additional_bindings:
-    - get:  '/v1/{name=projects/*/instances/*/operations/*}'
-  - selector: google.longrunning.Operations.ListOperations
-    get: '/v1/{name=projects/*/instances/*/databases/*/operations}'
-    additional_bindings:
-    - get:  '/v1/{name=projects/*/instances/*/operations}'
   - selector: google.longrunning.Operations.CancelOperation
     post: '/v1/{name=projects/*/instances/*/databases/*/operations/*}:cancel'
     additional_bindings:
-    - post:  '/v1/{name=projects/*/instances/*/operations/*}:cancel'
+    - post: '/v1/{name=projects/*/instances/*/operations/*}:cancel'
+    - post: '/v1/{name=projects/*/instances/*/backups/*/operations/*}:cancel'
+    - post: '/v1/{name=projects/*/instanceConfigs/*/operations/*}:cancel'
   - selector: google.longrunning.Operations.DeleteOperation
     delete: '/v1/{name=projects/*/instances/*/databases/*/operations/*}'
     additional_bindings:
-    - delete:  '/v1/{name=projects/*/instances/*/operations/*}'
-
-documentation:
-  summary:
-    Cloud Spanner is a managed, mission-critical, globally consistent and scalable relational database service.
+    - delete: '/v1/{name=projects/*/instances/*/operations/*}'
+    - delete: '/v1/{name=projects/*/instances/*/backups/*/operations/*}'
+    - delete: '/v1/{name=projects/*/instanceConfigs/*/operations/*}'
+  - selector: google.longrunning.Operations.GetOperation
+    get: '/v1/{name=projects/*/instances/*/databases/*/operations/*}'
+    additional_bindings:
+    - get: '/v1/{name=projects/*/instances/*/operations/*}'
+    - get: '/v1/{name=projects/*/instances/*/backups/*/operations/*}'
+    - get: '/v1/{name=projects/*/instanceConfigs/*/operations/*}'
+  - selector: google.longrunning.Operations.ListOperations
+    get: '/v1/{name=projects/*/instances/*/databases/*/operations}'
+    additional_bindings:
+    - get: '/v1/{name=projects/*/instances/*/operations}'
+    - get: '/v1/{name=projects/*/instances/*/backups/*/operations}'
+    - get: '/v1/{name=projects/*/instanceConfigs/*/operations}'
 
+authentication:
   rules:
-    - selector: google.iam.v1.SetIamPolicyRequest.resource
-      description: |
-        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.
-    - selector: google.iam.v1.GetIamPolicyRequest.resource
-      description: |
-        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.
-    - selector: google.iam.v1.TestIamPermissionsRequest.resource
-      description: |
-        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.
-    - selector: google.iam.v1.TestIamPermissionsRequest.permissions
-      description: |
-        REQUIRED: The set of permissions to check for 'resource'.
-        Permissions with wildcards (such as '*', 'spanner.*', 'spanner.instances.*') are not allowed.
+  - selector: 'google.longrunning.Operations.*'
+    oauth:
+      canonical_scopes: |-
+        https://www.googleapis.com/auth/cloud-platform,
+        https://www.googleapis.com/auth/spanner.admin
+  - selector: 'google.spanner.v1.Spanner.*'
+    oauth:
+      canonical_scopes: |-
+        https://www.googleapis.com/auth/cloud-platform,
+        https://www.googleapis.com/auth/spanner.data

google/spanner/v1/transaction.proto

@@ -1,4 +1,4 @@
-// Copyright 2021 Google LLC
+// Copyright 2022 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -35,7 +35,8 @@ option ruby_package = "Google::Cloud::Spanner::V1";
 // completed, the session can immediately be re-used for the next transaction.
 // It is not necessary to create a new session for each transaction.
 //
-// Transaction Modes:
+// Transaction modes:
+//
 // Cloud Spanner supports three transaction modes:
 //
 //   1. Locking read-write. This type of transaction is the only way
@@ -44,11 +45,18 @@ option ruby_package = "Google::Cloud::Spanner::V1";
 //      Locking read-write transactions may abort, requiring the
 //      application to retry.
 //
-//   2. Snapshot read-only. This transaction type provides guaranteed
-//      consistency across several reads, but does not allow
-//      writes. Snapshot read-only transactions can be configured to
-//      read at timestamps in the past. Snapshot read-only
-//      transactions do not need to be committed.
+//   2. Snapshot read-only. Snapshot read-only transactions provide guaranteed
+//      consistency across several reads, but do not allow
+//      writes. Snapshot read-only transactions can be configured to read at
+//      timestamps in the past, or configured to perform a strong read
+//      (where Spanner will select a timestamp such that the read is
+//      guaranteed to see the effects of all transactions that have committed
+//      before the start of the read). Snapshot read-only transactions do not
+//      need to be committed.
+//
+//      Queries on change streams must be performed with the snapshot read-only
+//      transaction mode, specifying a strong read. Please see
+//      [TransactionOptions.ReadOnly.strong][google.spanner.v1.TransactionOptions.ReadOnly.strong] for more details.
 //
 //   3. Partitioned DML. This type of transaction is used to execute
 //      a single Partitioned DML statement. Partitioned DML partitions
@@ -63,11 +71,12 @@ option ruby_package = "Google::Cloud::Spanner::V1";
 // not conflict with read-write transactions. As a consequence of not
 // taking locks, they also do not abort, so retry loops are not needed.
 //
-// Transactions may only read/write data in a single database. They
-// may, however, read/write data in different tables within that
+// Transactions may only read-write data in a single database. They
+// may, however, read-write data in different tables within that
 // database.
 //
-// Locking Read-Write Transactions:
+// Locking read-write transactions:
+//
 // Locking transactions may be used to atomically read-modify-write
 // data anywhere in a database. This type of transaction is externally
 // consistent.
@@ -78,7 +87,7 @@ option ruby_package = "Google::Cloud::Spanner::V1";
 // active as long as the transaction continues to do reads, and the
 // transaction has not been terminated by
 // [Commit][google.spanner.v1.Spanner.Commit] or
-// [Rollback][google.spanner.v1.Spanner.Rollback].  Long periods of
+// [Rollback][google.spanner.v1.Spanner.Rollback]. Long periods of
 // inactivity at the client may cause Cloud Spanner to release a
 // transaction's locks and abort it.
 //
@@ -90,6 +99,7 @@ option ruby_package = "Google::Cloud::Spanner::V1";
 // transaction.
 //
 // Semantics:
+//
 // Cloud Spanner can commit the transaction if all read locks it acquired
 // are still valid at commit time, and it is able to acquire write
 // locks for all writes. Cloud Spanner can abort the transaction for any
@@ -101,7 +111,8 @@ option ruby_package = "Google::Cloud::Spanner::V1";
 // use Cloud Spanner locks for any sort of mutual exclusion other than
 // between Cloud Spanner transactions themselves.
 //
-// Retrying Aborted Transactions:
+// Retrying aborted transactions:
+//
 // When a transaction aborts, the application can choose to retry the
 // whole transaction again. To maximize the chances of successfully
 // committing the retry, the client should execute the retry in the
@@ -116,7 +127,8 @@ option ruby_package = "Google::Cloud::Spanner::V1";
 // instead, it is better to limit the total amount of time spent
 // retrying.
 //
-// Idle Transactions:
+// Idle transactions:
+//
 // A transaction is considered idle if it has no outstanding reads or
 // SQL queries and has not started a read or SQL query within the last 10
 // seconds. Idle transactions can be aborted by Cloud Spanner so that they
@@ -127,7 +139,8 @@ option ruby_package = "Google::Cloud::Spanner::V1";
 // SQL query in the transaction (for example, `SELECT 1`) prevents the
 // transaction from becoming idle.
 //
-// Snapshot Read-Only Transactions:
+// Snapshot read-only transactions:
+//
 // Snapshot read-only transactions provides a simpler method than
 // locking read-write transactions for doing several consistent
 // reads. However, this type of transaction does not support writes.
@@ -159,13 +172,12 @@ option ruby_package = "Google::Cloud::Spanner::V1";
 //
 // If the Cloud Spanner database to be read is geographically distributed,
 // stale read-only transactions can execute more quickly than strong
-// or read-write transaction, because they are able to execute far
+// or read-write transactions, because they are able to execute far
 // from the leader replica.
 //
 // Each type of timestamp bound is discussed in detail below.
 //
-// Strong:
-// Strong reads are guaranteed to see the effects of all transactions
+// Strong: Strong reads are guaranteed to see the effects of all transactions
 // that have committed before the start of the read. Furthermore, all
 // rows yielded by a single read are consistent with each other -- if
 // any part of the read observes a transaction, all parts of the read
@@ -177,9 +189,13 @@ option ruby_package = "Google::Cloud::Spanner::V1";
 // reads should be executed within a transaction or at an exact read
 // timestamp.
 //
+// Queries on change streams (see below for more details) must also specify
+// the strong read timestamp bound.
+//
 // See [TransactionOptions.ReadOnly.strong][google.spanner.v1.TransactionOptions.ReadOnly.strong].
 //
-// Exact Staleness:
+// Exact staleness:
+//
 // These timestamp bounds execute reads at a user-specified
 // timestamp. Reads at a timestamp are guaranteed to see a consistent
 // prefix of the global transaction history: they observe
@@ -200,7 +216,8 @@ option ruby_package = "Google::Cloud::Spanner::V1";
 // See [TransactionOptions.ReadOnly.read_timestamp][google.spanner.v1.TransactionOptions.ReadOnly.read_timestamp] and
 // [TransactionOptions.ReadOnly.exact_staleness][google.spanner.v1.TransactionOptions.ReadOnly.exact_staleness].
 //
-// Bounded Staleness:
+// Bounded staleness:
+//
 // Bounded staleness modes allow Cloud Spanner to pick the read timestamp,
 // subject to a user-provided staleness bound. Cloud Spanner chooses the
 // newest timestamp within the staleness bound that allows execution
@@ -229,7 +246,8 @@ option ruby_package = "Google::Cloud::Spanner::V1";
 // See [TransactionOptions.ReadOnly.max_staleness][google.spanner.v1.TransactionOptions.ReadOnly.max_staleness] and
 // [TransactionOptions.ReadOnly.min_read_timestamp][google.spanner.v1.TransactionOptions.ReadOnly.min_read_timestamp].
 //
-// Old Read Timestamps and Garbage Collection:
+// Old read timestamps and garbage collection:
+//
 // Cloud Spanner continuously garbage collects deleted and overwritten data
 // in the background to reclaim storage space. This process is known
 // as "version GC". By default, version GC reclaims versions after they
@@ -239,7 +257,41 @@ option ruby_package = "Google::Cloud::Spanner::V1";
 // timestamp become too old while executing. Reads and SQL queries with
 // too-old read timestamps fail with the error `FAILED_PRECONDITION`.
 //
-// Partitioned DML Transactions:
+// You can configure and extend the `VERSION_RETENTION_PERIOD` of a
+// database up to a period as long as one week, which allows Cloud Spanner
+// to perform reads up to one week in the past.
+//
+// Querying change Streams:
+//
+// A Change Stream is a schema object that can be configured to watch data
+// changes on the entire database, a set of tables, or a set of columns
+// in a database.
+//
+// When a change stream is created, Spanner automatically defines a
+// corresponding SQL Table-Valued Function (TVF) that can be used to query
+// the change records in the associated change stream using the
+// ExecuteStreamingSql API. The name of the TVF for a change stream is
+// generated from the name of the change stream: READ_<change_stream_name>.
+//
+// All queries on change stream TVFs must be executed using the
+// ExecuteStreamingSql API with a single-use read-only transaction with a
+// strong read-only timestamp_bound. The change stream TVF allows users to
+// specify the start_timestamp and end_timestamp for the time range of
+// interest. All change records within the retention period is accessible
+// using the strong read-only timestamp_bound. All other TransactionOptions
+// are invalid for change stream queries.
+//
+// In addition, if TransactionOptions.read_only.return_read_timestamp is set
+// to true, a special value of 2^63 - 2 will be returned in the
+// [Transaction][google.spanner.v1.Transaction] message that describes the
+// transaction, instead of a valid read timestamp. This special value should be
+// discarded and not used for any subsequent queries.
+//
+// Please see https://cloud.google.com/spanner/docs/change-streams
+// for more details on how to query the change stream TVFs.
+//
+// Partitioned DML transactions:
+//
 // Partitioned DML transactions are used to execute DML statements with a
 // different execution strategy that provides different, and often better,
 // scalability properties for large, table-wide operations than DML in a

google/spanner/v1/type.proto

@@ -1,4 +1,4 @@
-// Copyright 2021 Google LLC
+// Copyright 2022 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.