feat: add Cluster maintenance and Self-service maintenance to SqlOperationType

Google APIs · copybara-github · commit ac90fa9958bd · 2024-06-10T14:50:14.000-07:00
feat: add MySQL 8.4 to SqlDatabaseVersion
docs: update a variety of documentation

PiperOrigin-RevId: 642030046
diff --git a/google/cloud/sql/v1beta4/cloud_sql.proto b/google/cloud/sql/v1beta4/cloud_sql.proto
@@ -274,15 +274,17 @@ service SqlInstancesService {
     };
   }
 
-  // Promotes the read replica instance to be a stand-alone Cloud SQL instance.
+  // Promotes the read replica instance to be an independent Cloud SQL
+  // primary instance.
   // Using this operation might cause your instance to restart.
   rpc PromoteReplica(SqlInstancesPromoteReplicaRequest) returns (Operation) {
     option (google.api.http) = {
       post: "/sql/v1beta4/projects/{project}/instances/{instance}/promoteReplica"
     };
   }
 
-  // Switches over from the primary instance to a replica instance.
+  // Switches over from the primary instance to the designated DR replica
+  // instance.
   rpc Switchover(SqlInstancesSwitchoverRequest) returns (Operation) {
     option (google.api.http) = {
       post: "/sql/v1beta4/projects/{project}/instances/{instance}/switchover"
@@ -770,9 +772,13 @@ message SqlInstancesPromoteReplicaRequest {
   // ID of the project that contains the read replica.
   string project = 2;
 
-  // Set to true if the promote operation should attempt to re-add the original
-  // primary as a replica when it comes back online. Otherwise, if this value is
-  // false or not set, the original primary will be a standalone instance.
+  // Set to true to invoke a replica failover to the designated DR replica.
+  // As part of replica failover, the promote operation attempts
+  // to add the original primary instance as a replica of the promoted
+  // DR replica when the original primary instance comes back online.
+  // If set to false or not specified, then the original primary
+  // instance becomes an independent Cloud SQL primary instance.
+  // Only applicable to MySQL.
   bool failover = 3;
 }
 
@@ -953,16 +959,16 @@ message SqlInstancesVerifyExternalSyncSettingsRequest {
     OFFLINE = 2;
   }
 
-  // MigrationType enum decides if the migration is a physical file based
-  // migration or logical migration
+  // MigrationType determines whether the migration is a physical file-based
+  // migration or a logical dump file-based migration.
   enum MigrationType {
-    // If no migration type is specified it will be defaulted to LOGICAL.
+    // Default value is a logical dump file-based migration
     MIGRATION_TYPE_UNSPECIFIED = 0;
 
-    // Logical Migrations
+    // Logical dump file-based migration
     LOGICAL = 1;
 
-    // Physical file based Migrations
+    // Physical file-based migration
     PHYSICAL = 2;
   }
 
@@ -987,12 +993,13 @@ message SqlInstancesVerifyExternalSyncSettingsRequest {
         [(google.api.field_behavior) = OPTIONAL];
   }
 
-  // Optional. MigrationType field decides if the migration is a physical file
-  // based migration or logical migration
+  // Optional. MigrationType configures the migration to use physical files or
+  // logical dump files. If not set, then the logical dump file configuration is
+  // used. Valid values are `LOGICAL` or `PHYSICAL`. Only applicable to MySQL.
   MigrationType migration_type = 7 [(google.api.field_behavior) = OPTIONAL];
 
-  // Optional. Parallel level for initial data sync. Currently only applicable
-  // for PostgreSQL.
+  // Optional. Parallel level for initial data sync. Only applicable for
+  // PostgreSQL.
   ExternalSyncParallelLevel sync_parallel_level = 8
       [(google.api.field_behavior) = OPTIONAL];
 }
@@ -1020,8 +1027,9 @@ message SqlInstancesStartExternalSyncRequest {
   ExternalSyncParallelLevel sync_parallel_level = 7
       [(google.api.field_behavior) = OPTIONAL];
 
-  // Optional. MigrationType decides if the migration is a physical file based
-  // migration or logical migration.
+  // Optional. MigrationType configures the migration to use physical files or
+  // logical dump files. If not set, then the logical dump file configuration is
+  // used. Valid values are `LOGICAL` or `PHYSICAL`. Only applicable to MySQL.
   SqlInstancesVerifyExternalSyncSettingsRequest.MigrationType migration_type = 8
       [(google.api.field_behavior) = OPTIONAL];
 }
diff --git a/google/cloud/sql/v1beta4/cloud_sql_resources.proto b/google/cloud/sql/v1beta4/cloud_sql_resources.proto
@@ -99,24 +99,28 @@ message BackupRetentionSettings {
 
 // Database instance backup configuration.
 message BackupConfiguration {
-  // This value contains the storage location of transactional logs for the
-  // database for point-in-time recovery.
+  // This value contains the storage location of the transactional logs
+  // used to perform point-in-time recovery (PITR) for the database.
   enum TransactionalLogStorageState {
     // Unspecified.
     TRANSACTIONAL_LOG_STORAGE_STATE_UNSPECIFIED = 0;
 
-    // The transaction logs for the instance are stored on a data disk.
+    // The transaction logs used for PITR for the instance are stored
+    // on a data disk.
     DISK = 1;
 
-    // The transaction logs for the instance are switching from being stored on
-    // a data disk to being stored in Cloud Storage.
+    // The transaction logs used for PITR for the instance are switching from
+    // being stored on a data disk to being stored in Cloud Storage.
+    // Only applicable to MySQL.
     SWITCHING_TO_CLOUD_STORAGE = 2;
 
-    // The transaction logs for the instance are now stored in Cloud Storage.
-    // Previously, they were stored on a data disk.
+    // The transaction logs used for PITR for the instance are now stored
+    // in Cloud Storage. Previously, they were stored on a data disk.
+    // Only applicable to MySQL.
     SWITCHED_TO_CLOUD_STORAGE = 3;
 
-    // The transaction logs for the instance are stored in Cloud Storage.
+    // The transaction logs used for PITR for the instance are stored in
+    // Cloud Storage. Only applicable to MySQL and PostgreSQL.
     CLOUD_STORAGE = 4;
   }
 
@@ -646,55 +650,58 @@ message DatabaseInstance {
   optional string write_endpoint = 52
       [(google.api.field_behavior) = OUTPUT_ONLY];
 
-  // The pair of a primary instance and disaster recovery (DR) replica.
+  // A primary instance and disaster recovery (DR) replica pair.
   // A DR replica is a cross-region replica that you designate
   // for failover in the event that the primary instance
-  // has regional failure.
+  // experiences regional failure. Only applicable to MySQL.
   optional ReplicationCluster replication_cluster = 54;
 
   // Gemini instance configuration.
   optional GeminiInstanceConfig gemini_config = 55;
 }
 
-// Gemini configuration.
+// Gemini instance configuration.
 message GeminiInstanceConfig {
   // Output only. Whether Gemini is enabled.
   optional bool entitled = 1 [(google.api.field_behavior) = OUTPUT_ONLY];
 
-  // Output only. Whether vacuum management is enabled.
+  // Output only. Whether the vacuum management is enabled.
   optional bool google_vacuum_mgmt_enabled = 2
       [(google.api.field_behavior) = OUTPUT_ONLY];
 
-  // Output only. Whether oom session cancel is enabled.
+  // Output only. Whether canceling the out-of-memory (OOM) session is enabled.
   optional bool oom_session_cancel_enabled = 3
       [(google.api.field_behavior) = OUTPUT_ONLY];
 
-  // Output only. Whether active query is enabled.
+  // Output only. Whether the active query is enabled.
   optional bool active_query_enabled = 4
       [(google.api.field_behavior) = OUTPUT_ONLY];
 
-  // Output only. Whether index advisor is enabled.
+  // Output only. Whether the index advisor is enabled.
   optional bool index_advisor_enabled = 5
       [(google.api.field_behavior) = OUTPUT_ONLY];
 
-  // Output only. Whether flag recommender is enabled.
+  // Output only. Whether the flag recommender is enabled.
   optional bool flag_recommender_enabled = 6
       [(google.api.field_behavior) = OUTPUT_ONLY];
 }
 
-// Primary-DR replica pair
+// A primary instance and disaster recovery (DR) replica pair.
+// A DR replica is a cross-region replica that you designate for failover
+// in the event that the primary instance has regional failure.
+// Only applicable to MySQL.
 message ReplicationCluster {
   // Optional. If the instance is a primary instance, then this field identifies
   // the disaster recovery (DR) replica. A DR replica is an optional
   // configuration for Enterprise Plus edition instances. If the instance is a
-  // read replica, then the field is not set. Users can set this field to set a
-  // designated DR replica for a primary. Removing this field removes the DR
-  // replica.
+  // read replica, then the field is not set. Set this field to a replica name
+  // to designate a DR replica for a primary instance. Remove the replica name
+  // to remove the DR replica designation.
   optional string failover_dr_replica_name = 2
       [(google.api.field_behavior) = OPTIONAL];
 
-  // Output only. read-only field that indicates if the replica is a dr_replica;
-  // not set for a primary.
+  // Output only. Read-only field that indicates whether the replica is a DR
+  // replica. This field is not set if the instance is a primary instance.
   optional bool dr_replica = 4 [(google.api.field_behavior) = OUTPUT_ONLY];
 }
 
@@ -1402,19 +1409,25 @@ message IpConfiguration {
     // The SSL mode is unknown.
     SSL_MODE_UNSPECIFIED = 0;
 
-    // Allow non-SSL/non-TLS and SSL/TLS connections. For SSL/TLS connections,
-    // the client certificate won't be verified.
+    // Allow non-SSL/non-TLS and SSL/TLS connections.
+    // For SSL connections to MySQL and PostgreSQL, the client certificate
+    // isn't verified.
+    //
     // When this value is used, the legacy `require_ssl` flag must be false or
-    // cleared to avoid the conflict between values of two flags.
+    // cleared to avoid a conflict between the values of the two flags.
     ALLOW_UNENCRYPTED_AND_ENCRYPTED = 1;
 
     // Only allow connections encrypted with SSL/TLS.
+    // For SSL connections to MySQL and PostgreSQL, the client certificate
+    // isn't verified.
+    //
     // When this value is used, the legacy `require_ssl` flag must be false or
-    // cleared to avoid the conflict between values of two flags.
+    // cleared to avoid a conflict between the values of the two flags.
     ENCRYPTED_ONLY = 2;
 
     // Only allow connections encrypted with SSL/TLS and with valid
     // client certificates.
+    //
     // When this value is used, the legacy `require_ssl` flag must be true or
     // cleared to avoid the conflict between values of two flags.
     // PostgreSQL clients or users that connect using IAM database
@@ -1424,7 +1437,8 @@ message IpConfiguration {
     // [Cloud SQL
     // Connectors](https://cloud.google.com/sql/docs/postgres/connect-connectors)
     // to enforce client identity verification.
-    // This value is not applicable to SQL Server.
+    //
+    // Only applicable to MySQL and PostgreSQL. Not applicable to SQL Server.
     TRUSTED_CLIENT_CERTIFICATE_REQUIRED = 3;
   }
 
@@ -1470,20 +1484,23 @@ message IpConfiguration {
   // value pairs are valid:
   //
   // For PostgreSQL and MySQL:
+  //
   // * `ssl_mode=ALLOW_UNENCRYPTED_AND_ENCRYPTED` and `require_ssl=false`
   // * `ssl_mode=ENCRYPTED_ONLY` and `require_ssl=false`
   // * `ssl_mode=TRUSTED_CLIENT_CERTIFICATE_REQUIRED` and `require_ssl=true`
   //
   // For SQL Server:
+  //
   // * `ssl_mode=ALLOW_UNENCRYPTED_AND_ENCRYPTED` and `require_ssl=false`
   // * `ssl_mode=ENCRYPTED_ONLY` and `require_ssl=true`
   //
-  // The value of `ssl_mode` gets priority over the value of `require_ssl`. For
-  // example, for the pair `ssl_mode=ENCRYPTED_ONLY` and `require_ssl=false`,
-  // the `ssl_mode=ENCRYPTED_ONLY` means only accept SSL connections, while the
-  // `require_ssl=false` means accept both non-SSL and SSL connections. MySQL
-  // and PostgreSQL databases respect `ssl_mode` in this case and accept only
-  // SSL connections.
+  // The value of `ssl_mode` has priority over the value of `require_ssl`.
+  //
+  // For example, for the pair `ssl_mode=ENCRYPTED_ONLY` and
+  // `require_ssl=false`, `ssl_mode=ENCRYPTED_ONLY` means accept only SSL
+  // connections, while `require_ssl=false` means accept both non-SSL
+  // and SSL connections. In this case, MySQL and PostgreSQL databases respect
+  // `ssl_mode` and accepts only SSL connections.
   SslMode ssl_mode = 8;
 
   // PSC settings for this instance.
@@ -1835,6 +1852,19 @@ message Operation {
     // asynchronously from the promote replica operation executed to the
     // replica.
     RECONFIGURE_OLD_PRIMARY = 44;
+
+    // Indicates that the instance, its read replicas, and its cascading
+    // replicas are in maintenance. Maintenance typically gets initiated on
+    // groups of replicas first, followed by the primary instance. For each
+    // instance, maintenance typically causes the instance to be unavailable for
+    // 1-3 minutes.
+    CLUSTER_MAINTENANCE = 45;
+
+    // Indicates that the instance (and any of its replicas) are currently in
+    // maintenance. This is initiated as a self-service request by using SSM.
+    // Maintenance typically causes the instance to be unavailable for 1-3
+    // minutes.
+    SELF_SERVICE_MAINTENANCE = 46;
   }
 
   // The status of an operation.
@@ -2620,6 +2650,9 @@ enum SqlDatabaseVersion {
   // The database major version is MySQL 8.0 and the minor version is 40.
   MYSQL_8_0_40 = 358;
 
+  // The database version is MySQL 8.4.
+  MYSQL_8_4 = 398;
+
   // The database version is SQL Server 2019 Standard.
   SQLSERVER_2019_STANDARD = 26;
 
