feat(spanner): Add support for Cloud Spanner Default Backup Schedules

.gitignore

@@ -12,4 +12,3 @@ system-test/*key.json
 .DS_Store
 package-lock.json
 __pycache__
-.vscode

protos/google/spanner/admin/instance/v1/common.proto

@@ -16,6 +16,7 @@ syntax = "proto3";
 
 package google.spanner.admin.instance.v1;
 
+import "google/api/field_behavior.proto";
 import "google/protobuf/timestamp.proto";
 
 option csharp_namespace = "Google.Cloud.Spanner.Admin.Instance.V1";
@@ -54,3 +55,9 @@ enum FulfillmentPeriod {
   // to complete.
   FULFILLMENT_PERIOD_EXTENDED = 2;
 }
+
+// ReplicaSelection identifies replicas with common properties.
+message ReplicaSelection {
+  // Required. Name of the location of the replicas (e.g., "us-central1").
+  string location = 1 [(google.api.field_behavior) = REQUIRED];
+}

protos/google/spanner/admin/instance/v1/spanner_instance_admin.proto

@@ -803,6 +803,34 @@ message InstanceConfig {
   State state = 11 [(google.api.field_behavior) = OUTPUT_ONLY];
 }
 
+// ReplicaComputeCapacity describes the amount of server resources that are
+// allocated to each replica identified by the replica selection.
+message ReplicaComputeCapacity {
+  // Required. Identifies replicas by specified properties.
+  // All replicas in the selection have the same amount of compute capacity.
+  ReplicaSelection replica_selection = 1
+      [(google.api.field_behavior) = REQUIRED];
+
+  // Compute capacity allocated to each replica identified by the specified
+  // selection.
+  // The unit is selected based on the unit used to specify the instance size
+  // for non-autoscaling instances, or the unit used in autoscaling limit for
+  // autoscaling instances.
+  oneof compute_capacity {
+    // The number of nodes allocated to each replica.
+    //
+    // This may be zero in API responses for instances that are not yet in
+    // state `READY`.
+    int32 node_count = 2;
+
+    // The number of processing units allocated to each replica.
+    //
+    // This may be zero in API responses for instances that are not yet in
+    // state `READY`.
+    int32 processing_units = 3;
+  }
+}
+
 // Autoscaling configuration for an instance.
 message AutoscalingConfig {
   // The autoscaling limits for the instance. Users can define the minimum and
@@ -854,13 +882,56 @@ message AutoscalingConfig {
         [(google.api.field_behavior) = REQUIRED];
   }
 
+  // AsymmetricAutoscalingOption specifies the scaling of replicas identified by
+  // the given selection.
+  message AsymmetricAutoscalingOption {
+    // Overrides the top-level autoscaling configuration for the replicas
+    // identified by `replica_selection`. All fields in this message are
+    // optional. Any unspecified fields will use the corresponding values from
+    // the top-level autoscaling configuration.
+    message AutoscalingConfigOverrides {
+      // Optional. If specified, overrides the min/max limit in the top-level
+      // autoscaling configuration for the selected replicas.
+      AutoscalingLimits autoscaling_limits = 1
+          [(google.api.field_behavior) = OPTIONAL];
+
+      // Optional. If specified, overrides the autoscaling target
+      // high_priority_cpu_utilization_percent in the top-level autoscaling
+      // configuration for the selected replicas.
+      int32 autoscaling_target_high_priority_cpu_utilization_percent = 2
+          [(google.api.field_behavior) = OPTIONAL];
+    }
+
+    // Required. Selects the replicas to which this AsymmetricAutoscalingOption
+    // applies. Only read-only replicas are supported.
+    ReplicaSelection replica_selection = 1
+        [(google.api.field_behavior) = REQUIRED];
+
+    // Optional. Overrides applied to the top-level autoscaling configuration
+    // for the selected replicas.
+    AutoscalingConfigOverrides overrides = 2
+        [(google.api.field_behavior) = OPTIONAL];
+  }
+
   // Required. Autoscaling limits for an instance.
   AutoscalingLimits autoscaling_limits = 1
       [(google.api.field_behavior) = REQUIRED];
 
   // Required. The autoscaling targets for an instance.
   AutoscalingTargets autoscaling_targets = 2
       [(google.api.field_behavior) = REQUIRED];
+
+  // Optional. Optional asymmetric autoscaling options.
+  // Replicas matching the replica selection criteria will be autoscaled
+  // independently from other replicas. The autoscaler will scale the replicas
+  // based on the utilization of replicas identified by the replica selection.
+  // Replica selections should not overlap with each other.
+  //
+  // Other replicas (those do not match any replica selection) will be
+  // autoscaled together and will have the same compute capacity allocated to
+  // them.
+  repeated AsymmetricAutoscalingOption asymmetric_autoscaling_options = 3
+      [(google.api.field_behavior) = OPTIONAL];
 }
 
 // An isolated set of Cloud Spanner resources on which databases can be hosted.
@@ -901,6 +972,24 @@ message Instance {
     ENTERPRISE_PLUS = 3;
   }
 
+  // Indicates the default backup behavior for new databases within the
+  // instance.
+  enum DefaultBackupScheduleType {
+    // Not specified.
+    DEFAULT_BACKUP_SCHEDULE_TYPE_UNSPECIFIED = 0;
+
+    // No default backup schedule will be created automatically on creation of a
+    // database within the instance.
+    NONE = 1;
+
+    // A default backup schedule will be created automatically on creation of a
+    // database within the instance. The default backup schedule creates a full
+    // backup every 24 hours and retains the backup for a period of 7 days. Once
+    // created, the default backup schedule can be edited/deleted similar to any
+    // other backup schedule.
+    AUTOMATIC = 2;
+  }
+
   // Required. A unique identifier for the instance, which cannot be changed
   // after the instance is created. Values are of the form
   // `projects/<project>/instances/[a-z][-a-z0-9]*[a-z0-9]`. The final
@@ -922,34 +1011,56 @@ message Instance {
   // Must be unique per project and between 4 and 30 characters in length.
   string display_name = 3 [(google.api.field_behavior) = REQUIRED];
 
-  // The number of nodes allocated to this instance. At most one of either
-  // node_count or processing_units should be present in the message.
+  // The number of nodes allocated to this instance. At most, one of either
+  // `node_count` or `processing_units` should be present in the message.
   //
-  // Users can set the node_count field to specify the target number of nodes
+  // Users can set the `node_count` field to specify the target number of nodes
   // allocated to the instance.
   //
-  // This may be zero in API responses for instances that are not yet in state
-  // `READY`.
+  // If autoscaling is enabled, `node_count` is treated as an `OUTPUT_ONLY`
+  // field and reflects the current number of nodes allocated to the instance.
   //
-  // See [the
-  // documentation](https://cloud.google.com/spanner/docs/compute-capacity)
-  // for more information about nodes and processing units.
+  // This might be zero in API responses for instances that are not yet in the
+  // `READY` state.
+  //
+  // If the instance has varying node count across replicas (achieved by
+  // setting asymmetric_autoscaling_options in autoscaling config), the
+  // node_count here is the maximum node count across all replicas.
+  //
+  // For more information, see
+  // [Compute capacity, nodes, and processing
+  // units](https://cloud.google.com/spanner/docs/compute-capacity).
   int32 node_count = 5;
 
-  // The number of processing units allocated to this instance. At most one of
-  // processing_units or node_count should be present in the message.
+  // The number of processing units allocated to this instance. At most, one of
+  // either `processing_units` or `node_count` should be present in the message.
   //
-  // Users can set the processing_units field to specify the target number of
+  // Users can set the `processing_units` field to specify the target number of
   // processing units allocated to the instance.
   //
-  // This may be zero in API responses for instances that are not yet in state
-  // `READY`.
+  // If autoscaling is enabled, `processing_units` is treated as an
+  // `OUTPUT_ONLY` field and reflects the current number of processing units
+  // allocated to the instance.
   //
-  // See [the
-  // documentation](https://cloud.google.com/spanner/docs/compute-capacity)
-  // for more information about nodes and processing units.
+  // This might be zero in API responses for instances that are not yet in the
+  // `READY` state.
+  //
+  // If the instance has varying processing units per replica
+  // (achieved by setting asymmetric_autoscaling_options in autoscaling config),
+  // the processing_units here is the maximum processing units across all
+  // replicas.
+  //
+  // For more information, see
+  // [Compute capacity, nodes and processing
+  // units](https://cloud.google.com/spanner/docs/compute-capacity).
   int32 processing_units = 9;
 
+  // Output only. Lists the compute capacity per ReplicaSelection. A replica
+  // selection identifies a set of replicas with common properties. Replicas
+  // identified by a ReplicaSelection are scaled with the same compute capacity.
+  repeated ReplicaComputeCapacity replica_compute_capacity = 19
+      [(google.api.field_behavior) = OUTPUT_ONLY];
+
   // Optional. The autoscaling configuration. Autoscaling is enabled if this
   // field is set. When autoscaling is enabled, node_count and processing_units
   // are treated as OUTPUT_ONLY fields and reflect the current compute capacity
@@ -1000,6 +1111,18 @@ message Instance {
 
   // Optional. The `Edition` of the current instance.
   Edition edition = 20 [(google.api.field_behavior) = OPTIONAL];
+
+  // Optional. Controls the default backup behavior for new databases within the
+  // instance.
+  //
+  // Note that `AUTOMATIC` is not permitted for free instances, as backups and
+  // backup schedules are not allowed for free instances.
+  //
+  // In the `GetInstance` or `ListInstances` response, if the value of
+  // default_backup_schedule_type is unset or NONE, no default backup
+  // schedule will be created for new databases within the instance.
+  DefaultBackupScheduleType default_backup_schedule_type = 23
+      [(google.api.field_behavior) = OPTIONAL];
 }
 
 // The request for

protos/google/spanner/v1/commit_response.proto

@@ -17,6 +17,7 @@ syntax = "proto3";
 package google.spanner.v1;
 
 import "google/protobuf/timestamp.proto";
+import "google/spanner/v1/transaction.proto";
 
 option csharp_namespace = "Google.Cloud.Spanner.V1";
 option go_package = "cloud.google.com/go/spanner/apiv1/spannerpb;spannerpb";
@@ -47,4 +48,12 @@ message CommitResponse {
   // For more information, see
   // [CommitRequest.return_commit_stats][google.spanner.v1.CommitRequest.return_commit_stats].
   CommitStats commit_stats = 2;
+
+  // Clients should examine and retry the commit if any of the following
+  // reasons are populated.
+  oneof MultiplexedSessionRetry {
+    // If specified, transaction has not committed yet.
+    // Clients must retry the commit with the new precommit token.
+    MultiplexedSessionPrecommitToken precommit_token = 4;
+  }
 }

protos/google/spanner/v1/result_set.proto

@@ -16,6 +16,7 @@ syntax = "proto3";
 
 package google.spanner.v1;
 
+import "google/api/field_behavior.proto";
 import "google/protobuf/struct.proto";
 import "google/spanner/v1/query_plan.proto";
 import "google/spanner/v1/transaction.proto";
@@ -53,6 +54,16 @@ message ResultSet {
   // Other fields may or may not be populated, based on the
   // [ExecuteSqlRequest.query_mode][google.spanner.v1.ExecuteSqlRequest.query_mode].
   ResultSetStats stats = 3;
+
+  // Optional. A precommit token will be included if the read-write transaction
+  // is on a multiplexed session.
+  // The precommit token with the highest sequence number from this transaction
+  // attempt should be passed to the
+  // [Commit][google.spanner.v1.Spanner.Commit] request for this transaction.
+  // This feature is not yet supported and will result in an UNIMPLEMENTED
+  // error.
+  MultiplexedSessionPrecommitToken precommit_token = 5
+      [(google.api.field_behavior) = OPTIONAL];
 }
 
 // Partial results from a streaming read or SQL query. Streaming reads and
@@ -157,6 +168,16 @@ message PartialResultSet {
   // This field will also be present in the last response for DML
   // statements.
   ResultSetStats stats = 5;
+
+  // Optional. A precommit token will be included if the read-write transaction
+  // is on a multiplexed session.
+  // The precommit token with the highest sequence number from this transaction
+  // attempt should be passed to the
+  // [Commit][google.spanner.v1.Spanner.Commit] request for this transaction.
+  // This feature is not yet supported and will result in an UNIMPLEMENTED
+  // error.
+  MultiplexedSessionPrecommitToken precommit_token = 8
+      [(google.api.field_behavior) = OPTIONAL];
 }
 
 // Metadata about a [ResultSet][google.spanner.v1.ResultSet] or [PartialResultSet][google.spanner.v1.PartialResultSet].

protos/google/spanner/v1/spanner.proto

@@ -628,9 +628,19 @@ message ExecuteSqlRequest {
     // execution statistics information.
     PLAN = 1;
 
-    // This mode returns both the query plan and the execution statistics along
-    // with the results.
+    // This mode returns the query plan, overall execution statistics,
+    // operator level execution statistics along with the results. This has a
+    // performance overhead compared to the other modes. It is not recommended
+    // to use this mode for production traffic.
     PROFILE = 2;
+
+    // This mode returns the overall (but not operator-level) execution
+    // statistics along with the results.
+    WITH_STATS = 3;
+
+    // This mode returns the query plan, overall (but not operator-level)
+    // execution statistics along with the results.
+    WITH_PLAN_AND_STATS = 4;
   }
 
   // Query optimizer configuration.
@@ -899,6 +909,16 @@ message ExecuteBatchDmlResponse {
   // If all DML statements are executed successfully, the status is `OK`.
   // Otherwise, the error status of the first failed statement.
   google.rpc.Status status = 2;
+
+  // Optional. A precommit token will be included if the read-write transaction
+  // is on a multiplexed session.
+  // The precommit token with the highest sequence number from this transaction
+  // attempt should be passed to the
+  // [Commit][google.spanner.v1.Spanner.Commit] request for this transaction.
+  // This feature is not yet supported and will result in an UNIMPLEMENTED
+  // error.
+  MultiplexedSessionPrecommitToken precommit_token = 3
+      [(google.api.field_behavior) = OPTIONAL];
 }
 
 // Options for a PartitionQueryRequest and
@@ -1215,6 +1235,14 @@ message BeginTransactionRequest {
   // transaction, set it on the reads and writes that are part of this
   // transaction instead.
   RequestOptions request_options = 3;
+
+  // Optional. Required for read-write transactions on a multiplexed session
+  // that commit mutations but do not perform any reads or queries. Clients
+  // should randomly select one of the mutations from the mutation set and send
+  // it as a part of this request.
+  // This feature is not yet supported and will result in an UNIMPLEMENTED
+  // error.
+  Mutation mutation_key = 4 [(google.api.field_behavior) = OPTIONAL];
 }
 
 // The request for [Commit][google.spanner.v1.Spanner.Commit].
@@ -1262,6 +1290,15 @@ message CommitRequest {
 
   // Common options for this request.
   RequestOptions request_options = 6;
+
+  // Optional. If the read-write transaction was executed on a multiplexed
+  // session, the precommit token with the highest sequence number received in
+  // this transaction attempt, should be included here. Failing to do so will
+  // result in a FailedPrecondition error.
+  // This feature is not yet supported and will result in an UNIMPLEMENTED
+  // error.
+  MultiplexedSessionPrecommitToken precommit_token = 9
+      [(google.api.field_behavior) = OPTIONAL];
 }
 
 // The request for [Rollback][google.spanner.v1.Spanner.Rollback].