Merge branch 'main' into multiplexed-session-support-read-only

Author: alkatrivedi

protos/google/spanner/admin/database/v1/backup.proto

@@ -207,6 +207,13 @@ message Backup {
   // retained by the backup system.
   google.protobuf.Timestamp oldest_version_time = 18
       [(google.api.field_behavior) = OUTPUT_ONLY];
+
+  // Output only. The instance partition(s) storing the backup.
+  //
+  // This is the same as the list of the instance partition(s) that the database
+  // had footprint in at the backup's `version_time`.
+  repeated BackupInstancePartition instance_partitions = 19
+      [(google.api.field_behavior) = OUTPUT_ONLY];
 }
 
 // The request for
@@ -755,3 +762,12 @@ message FullBackupSpec {}
 // successive incremental backups. The first backup created for an
 // incremental backup chain is always a full backup.
 message IncrementalBackupSpec {}
+
+// Instance partition information for the backup.
+message BackupInstancePartition {
+  // A unique identifier for the instance partition. Values are of the form
+  // `projects/<project>/instances/<instance>/instancePartitions/<instance_partition_id>`
+  string instance_partition = 1 [(google.api.resource_reference) = {
+    type: "spanner.googleapis.com/InstancePartition"
+  }];
+}

protos/google/spanner/admin/database/v1/spanner_database_admin.proto

@@ -25,6 +25,7 @@ import "google/iam/v1/policy.proto";
 import "google/longrunning/operations.proto";
 import "google/protobuf/empty.proto";
 import "google/protobuf/field_mask.proto";
+import "google/protobuf/struct.proto";
 import "google/protobuf/timestamp.proto";
 import "google/spanner/admin/database/v1/backup.proto";
 import "google/spanner/admin/database/v1/backup_schedule.proto";
@@ -41,6 +42,10 @@ option (google.api.resource_definition) = {
   type: "spanner.googleapis.com/Instance"
   pattern: "projects/{project}/instances/{instance}"
 };
+option (google.api.resource_definition) = {
+  type: "spanner.googleapis.com/InstancePartition"
+  pattern: "projects/{project}/instances/{instance}/instancePartitions/{instance_partition}"
+};
 
 // Cloud Spanner Database Admin API
 //
@@ -425,6 +430,15 @@ service DatabaseAdmin {
     option (google.api.method_signature) = "parent";
   }
 
+  // Adds split points to specified tables, indexes of a database.
+  rpc AddSplitPoints(AddSplitPointsRequest) returns (AddSplitPointsResponse) {
+    option (google.api.http) = {
+      post: "/v1/{database=projects/*/instances/*/databases/*}:addSplitPoints"
+      body: "*"
+    };
+    option (google.api.method_signature) = "database,split_points";
+  }
+
   // Creates a new backup schedule.
   rpc CreateBackupSchedule(CreateBackupScheduleRequest)
       returns (BackupSchedule) {
@@ -1207,3 +1221,59 @@ message ListDatabaseRolesResponse {
   // call to fetch more of the matching roles.
   string next_page_token = 2;
 }
+
+// The request for
+// [AddSplitPoints][google.spanner.admin.database.v1.DatabaseAdmin.AddSplitPoints].
+message AddSplitPointsRequest {
+  // Required. The database on whose tables/indexes split points are to be
+  // added. Values are of the form
+  // `projects/<project>/instances/<instance>/databases/<database>`.
+  string database = 1 [
+    (google.api.field_behavior) = REQUIRED,
+    (google.api.resource_reference) = {
+      type: "spanner.googleapis.com/Database"
+    }
+  ];
+
+  // Required. The split points to add.
+  repeated SplitPoints split_points = 2
+      [(google.api.field_behavior) = REQUIRED];
+
+  // Optional. A user-supplied tag associated with the split points.
+  // For example, "intital_data_load", "special_event_1".
+  // Defaults to "CloudAddSplitPointsAPI" if not specified.
+  // The length of the tag must not exceed 50 characters,else will be trimmed.
+  // Only valid UTF8 characters are allowed.
+  string initiator = 3 [(google.api.field_behavior) = OPTIONAL];
+}
+
+// The response for
+// [AddSplitPoints][google.spanner.admin.database.v1.DatabaseAdmin.AddSplitPoints].
+message AddSplitPointsResponse {}
+
+// The split points of a table/index.
+message SplitPoints {
+  // A split key.
+  message Key {
+    // Required. The column values making up the split key.
+    google.protobuf.ListValue key_parts = 1
+        [(google.api.field_behavior) = REQUIRED];
+  }
+
+  // The table to split.
+  string table = 1;
+
+  // The index to split.
+  // If specified, the `table` field must refer to the index's base table.
+  string index = 2;
+
+  // Required. The list of split keys, i.e., the split boundaries.
+  repeated Key keys = 3 [(google.api.field_behavior) = REQUIRED];
+
+  // Optional. The expiration timestamp of the split points.
+  // A timestamp in the past means immediate expiration.
+  // The maximum value can be 30 days in the future.
+  // Defaults to 10 days in the future if not specified.
+  google.protobuf.Timestamp expire_time = 5
+      [(google.api.field_behavior) = OPTIONAL];
+}

protos/google/spanner/v1/transaction.proto

@@ -361,19 +361,31 @@ message TransactionOptions {
     enum ReadLockMode {
       // Default value.
       //
-      // If the value is not specified, the pessimistic read lock is used.
+      // * If isolation level is `REPEATABLE_READ`, then it is an error to
+      //   specify `read_lock_mode`. Locking semantics default to `OPTIMISTIC`.
+      //   No validation checks are done for reads, except for:
+      //     1. reads done as part of queries that use `SELECT FOR UPDATE`
+      //     2. reads done as part of statements with a `LOCK_SCANNED_RANGES`
+      //        hint
+      //     3. reads done as part of DML statements
+      //   to validate that the data that was served at the snapshot time is
+      //   unchanged at commit time.
+      // * At all other isolation levels, if `read_lock_mode` is the default
+      //   value, then pessimistic read lock is used.
       READ_LOCK_MODE_UNSPECIFIED = 0;
 
       // Pessimistic lock mode.
       //
       // Read locks are acquired immediately on read.
+      // Semantics described only applies to `SERIALIZABLE` isolation.
       PESSIMISTIC = 1;
 
       // Optimistic lock mode.
       //
       // Locks for reads within the transaction are not acquired on read.
       // Instead the locks are acquired on a commit to validate that
       // read/queried data has not changed since the transaction started.
+      // Semantics described only applies to `SERIALIZABLE` isolation.
       OPTIMISTIC = 2;
     }
 
@@ -461,6 +473,38 @@ message TransactionOptions {
     bool return_read_timestamp = 6;
   }
 
+  // `IsolationLevel` is used when setting `isolation_level` for a transaction.
+  enum IsolationLevel {
+    // Default value.
+    //
+    // If the value is not specified, the `SERIALIZABLE` isolation level is
+    // used.
+    ISOLATION_LEVEL_UNSPECIFIED = 0;
+
+    // All transactions appear as if they executed in a serial order, even if
+    // some of the reads, writes, and other operations of distinct transactions
+    // actually occurred in parallel. Spanner assigns commit timestamps that
+    // reflect the order of committed transactions to implement this property.
+    // Spanner offers a stronger guarantee than serializability called external
+    // consistency. For further details, please refer to
+    // https://cloud.google.com/spanner/docs/true-time-external-consistency#serializability.
+    SERIALIZABLE = 1;
+
+    // All reads performed during the transaction observe a consistent snapshot
+    // of the database, and the transaction will only successfully commit in the
+    // absence of conflicts between its updates and any concurrent updates that
+    // have occurred since that snapshot. Consequently, in contrast to
+    // `SERIALIZABLE` transactions, only write-write conflicts are detected in
+    // snapshot transactions.
+    //
+    // This isolation level does not support Read-only and Partitioned DML
+    // transactions.
+    //
+    // When `REPEATABLE_READ` is specified on a read-write transaction, the
+    // locking semantics default to `OPTIMISTIC`.
+    REPEATABLE_READ = 2;
+  }
+
   // Required. The type of transaction.
   oneof mode {
     // Transaction may write.
@@ -500,6 +544,9 @@ message TransactionOptions {
   // partitioned-dml transactions, otherwise the API will return an
   // `INVALID_ARGUMENT` error.
   bool exclude_txn_from_change_streams = 5;
+
+  // Isolation level for the transaction.
+  IsolationLevel isolation_level = 6;
 }
 
 // A transaction.