feat: add CRUD APIs on Databases

Google APIs · copybara-github · commit fc225fe488a3 · 2025-09-26T10:41:27.000-07:00
feat: add PG 17 as a Database version
chore: annotate `EncryptionConfig.kms_key_name`, `SecondaryConfig.primary_cluster_name`, `PrimaryConfig.secondary_cluster_names`, and `PscInstanceConfig.service_attachment_link` with what resource they're referencing
feat: add configuration for Managed Connection Pool
feat: update `Database.charset` to be immutable
feat: add additional fields to Database object to specify the collation type, character type, if it is a template database, and the template to use for the database
feat: add field to ExecuteSQL request to just validate the sql statement
feat: add fields on the estimated/actual start/end times for an Upgrade Cluster operation
docs: specify that the STOPPED state is not used for clusters anymore

PiperOrigin-RevId: 811874303
diff --git a/google/cloud/alloydb/v1/alloydb_v1_grpc_service_config.json b/google/cloud/alloydb/v1/alloydb_v1_grpc_service_config.json
@@ -9,7 +9,11 @@
       { "service": "google.cloud.alloydb.v1.AlloyDBAdmin", "method": "GetBackup" },
       { "service": "google.cloud.alloydb.v1.AlloyDBAdmin", "method": "ListSupportedDatabaseFlags" },
       { "service": "google.cloud.alloydb.v1.AlloyDBAdmin", "method": "GenerateClientCertificate" },
-      { "service": "google.cloud.alloydb.v1.AlloyDBAdmin", "method": "GetConnectionInfo" }
+      { "service": "google.cloud.alloydb.v1.AlloyDBAdmin", "method": "GetConnectionInfo" },
+      { "service":"google.cloud.alloydb.v1.AlloyDBAdmin", "method": "CreateDatabase"},
+      { "service":"google.cloud.alloydb.v1.AlloyDBAdmin", "method": "GetDatabase"},
+      { "service": "google.cloud.alloydb.v1.AlloyDBAdmin", "method": "UpdateDatabase" },
+      { "service": "google.cloud.alloydb.v1.AlloyDBAdmin", "method": "DeleteDatabase" }
     ],
     "timeout": "60s",
     "retryPolicy": {
diff --git a/google/cloud/alloydb/v1/resources.proto b/google/cloud/alloydb/v1/resources.proto
@@ -42,6 +42,14 @@ option (google.api.resource_definition) = {
   type: "compute.googleapis.com/Network"
   pattern: "projects/{project}/global/networks/{network}"
 };
+option (google.api.resource_definition) = {
+  type: "cloudkms.googleapis.com/CryptoKey"
+  pattern: "projects/{project}/locations/{location}/keyRings/{key_ring}/cryptoKeys/{crypto_key}"
+};
+option (google.api.resource_definition) = {
+  type: "compute.googleapis.com/ServiceAttachment"
+  pattern: "projects/{project}/regions/{region}/serviceAttachments/{service_attachment}"
+};
 
 // View on Instance. Pass this enum to rpcs that returns an Instance message to
 // control which subsets of fields to get.
@@ -92,6 +100,9 @@ enum DatabaseVersion {
 
   // The database version is Postgres 16.
   POSTGRES_16 = 4;
+
+  // The database version is Postgres 17.
+  POSTGRES_17 = 5;
 }
 
 // Subscription_type added to distinguish between Standard and Trial
@@ -150,7 +161,9 @@ message EncryptionConfig {
   // The fully-qualified resource name of the KMS key.
   // Each Cloud KMS key is regionalized and has the following format:
   // projects/[PROJECT]/locations/[REGION]/keyRings/[RING]/cryptoKeys/[KEY_NAME]
-  string kms_key_name = 1;
+  string kms_key_name = 1 [(google.api.resource_reference) = {
+    type: "cloudkms.googleapis.com/CryptoKey"
+  }];
 }
 
 // EncryptionInfo describes the encryption information of a cluster or a backup.
@@ -495,7 +508,9 @@ message Cluster {
   message SecondaryConfig {
     // The name of the primary cluster name with the format:
     // * projects/{project}/locations/{region}/clusters/{cluster_id}
-    string primary_cluster_name = 1;
+    string primary_cluster_name = 1 [(google.api.resource_reference) = {
+      type: "alloydb.googleapis.com/Cluster"
+    }];
   }
 
   // Configuration for the primary cluster. It has the list of clusters that are
@@ -504,8 +519,12 @@ message Cluster {
   message PrimaryConfig {
     // Output only. Names of the clusters that are replicating from this
     // cluster.
-    repeated string secondary_cluster_names = 1
-        [(google.api.field_behavior) = OUTPUT_ONLY];
+    repeated string secondary_cluster_names = 1 [
+      (google.api.field_behavior) = OUTPUT_ONLY,
+      (google.api.resource_reference) = {
+        type: "alloydb.googleapis.com/Cluster"
+      }
+    ];
   }
 
   // PscConfig contains PSC related configuration at a cluster level.
@@ -543,11 +562,8 @@ message Cluster {
     // The cluster is active and running.
     READY = 1;
 
-    // The cluster is stopped. All instances in the cluster are stopped.
-    // Customers can start a stopped cluster at any point and all their
-    // instances will come back to life with same names and IP resources. In
-    // this state, customer pays for storage.
-    // Associated backups could also be present in a stopped cluster.
+    // This is unused. Even when all instances in the cluster are stopped, the
+    // cluster remains in READY state.
     STOPPED = 2;
 
     // The cluster is empty and has no associated resources.
@@ -942,8 +958,12 @@ message Instance {
     // Service Connect (PSC) is enabled for the instance.
     // The name of the resource will be in the format of
     // `projects/<alloydb-tenant-project-number>/regions/<region-name>/serviceAttachments/<service-attachment-name>`
-    string service_attachment_link = 1
-        [(google.api.field_behavior) = OUTPUT_ONLY];
+    string service_attachment_link = 1 [
+      (google.api.field_behavior) = OUTPUT_ONLY,
+      (google.api.resource_reference) = {
+        type: "compute.googleapis.com/ServiceAttachment"
+      }
+    ];
 
     // Optional. List of consumer projects that are allowed to create
     // PSC endpoints to service-attachments to this instance.
@@ -1008,6 +1028,18 @@ message Instance {
         [(google.api.field_behavior) = OPTIONAL];
   }
 
+  // Configuration for Managed Connection Pool (MCP).
+  message ConnectionPoolConfig {
+    // Optional. Whether to enable Managed Connection Pool (MCP).
+    bool enabled = 12 [(google.api.field_behavior) = OPTIONAL];
+
+    // Optional. Connection Pool flags, as a list of "key": "value" pairs.
+    map<string, string> flags = 13 [(google.api.field_behavior) = OPTIONAL];
+
+    // Output only. The number of running poolers per instance.
+    int32 pooler_count = 14 [(google.api.field_behavior) = OUTPUT_ONLY];
+  }
+
   // Instance State
   enum State {
     // The state of the instance is unknown.
@@ -1246,6 +1278,10 @@ message Instance {
   // etc.). Please refer to the API documentation for more details.
   ActivationPolicy activation_policy = 35
       [(google.api.field_behavior) = OPTIONAL];
+
+  // Optional. The configuration for Managed Connection Pool (MCP).
+  ConnectionPoolConfig connection_pool_config = 37
+      [(google.api.field_behavior) = OPTIONAL];
 }
 
 // ConnectionInfo singleton resource.
@@ -1634,13 +1670,38 @@ message Database {
   // `projects/{project}/locations/{location}/clusters/{cluster}/databases/{database}`.
   string name = 1 [(google.api.field_behavior) = IDENTIFIER];
 
-  // Optional. Charset for the database.
+  // Optional. Immutable. Charset for the database.
   // This field can contain any PostgreSQL supported charset name.
   // Example values include "UTF8", "SQL_ASCII", etc.
-  string charset = 2 [(google.api.field_behavior) = OPTIONAL];
+  string charset = 2 [
+    (google.api.field_behavior) = OPTIONAL,
+    (google.api.field_behavior) = IMMUTABLE
+  ];
 
-  // Optional. Collation for the database.
-  // Name of the custom or native collation for postgres.
-  // Example values include "C", "POSIX", etc
-  string collation = 3 [(google.api.field_behavior) = OPTIONAL];
+  // Optional. Immutable. lc_collate for the database.
+  // String sort order.
+  // Example values include "C", "POSIX", etc.
+  string collation = 3 [
+    (google.api.field_behavior) = OPTIONAL,
+    (google.api.field_behavior) = IMMUTABLE
+  ];
+
+  // Optional. Immutable. lc_ctype for the database.
+  // Character classification (What is a letter? The upper-case equivalent?).
+  // Example values include "C", "POSIX", etc.
+  string character_type = 4 [
+    (google.api.field_behavior) = OPTIONAL,
+    (google.api.field_behavior) = IMMUTABLE
+  ];
+
+  // Input only. Immutable. Template of the database to be used for creating a
+  // new database.
+  string database_template = 6 [
+    (google.api.field_behavior) = INPUT_ONLY,
+    (google.api.field_behavior) = IMMUTABLE
+  ];
+
+  // Optional. Whether the database is a template database.
+  optional bool is_template_database = 7
+      [(google.api.field_behavior) = OPTIONAL];
 }
diff --git a/google/cloud/alloydb/v1/service.proto b/google/cloud/alloydb/v1/service.proto
@@ -1606,6 +1606,10 @@ message ExecuteSqlRequest {
   // Required. SQL statement to execute on database. Any valid statement is
   // permitted, including DDL, DML, DQL statements.
   string sql_statement = 4 [(google.api.field_behavior) = REQUIRED];
+
+  // Optional. If set, validates the sql statement by performing
+  // syntax and semantic validation and doesn't execute the query.
+  bool validate_only = 6 [(google.api.field_behavior) = OPTIONAL];
 }
 
 // Execute a SQL statement response.
@@ -1976,6 +1980,23 @@ message OperationMetadata {
 message UpgradeClusterStatus {
   // Status of an upgrade stage.
   message StageStatus {
+    // Timing information for the stage execution.
+    message StageSchedule {
+      // When the stage is expected to start. Set only if the stage has not
+      // started yet.
+      google.protobuf.Timestamp estimated_start_time = 1;
+
+      // Actual start time of the stage. Set only if the stage has started.
+      google.protobuf.Timestamp actual_start_time = 2;
+
+      // When the stage is expected to end. Set only if the stage has not
+      // completed yet.
+      google.protobuf.Timestamp estimated_end_time = 3;
+
+      // Actual end time of the stage. Set only if the stage has completed.
+      google.protobuf.Timestamp actual_end_time = 4;
+    }
+
     // Stage specific status information, if any.
     oneof stage_specific_status {
       // Read pool instances upgrade metadata.
@@ -1987,6 +2008,9 @@ message UpgradeClusterStatus {
 
     // State of this stage.
     UpgradeClusterResponse.Status state = 2;
+
+    // Output only. Timing information for the stage execution.
+    StageSchedule schedule = 3 [(google.api.field_behavior) = OUTPUT_ONLY];
   }
 
   // Read pool instances upgrade specific status.
@@ -2173,7 +2197,7 @@ message DeleteUserRequest {
   bool validate_only = 3 [(google.api.field_behavior) = OPTIONAL];
 }
 
-// Message for requesting list of Databases.
+// Message for ListDatabases request.
 message ListDatabasesRequest {
   // Required. Parent value for ListDatabasesRequest.
   string parent = 1 [
@@ -2199,9 +2223,9 @@ message ListDatabasesRequest {
   string filter = 4 [(google.api.field_behavior) = OPTIONAL];
 }
 
-// Message for response to listing Databases.
+// Message for ListDatabases response.
 message ListDatabasesResponse {
-  // The list of databases
+  // The list of databases.
   repeated Database databases = 1;
 
   // A token identifying the next page of results the server should return.
