feat: add CRUD APIs on Databases

Google APIs · copybara-github · commit 8cd780626041 · 2025-09-26T10:43:20.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
fix!: An existing enum `PoolMode` is removed from the `ConnectionPoolConfig`

PiperOrigin-RevId: 811874519
diff --git a/google/cloud/alloydb/v1alpha/alloydb_v1alpha_grpc_service_config.json b/google/cloud/alloydb/v1alpha/alloydb_v1alpha_grpc_service_config.json
@@ -11,7 +11,11 @@
       { "service": "google.cloud.alloydb.v1alpha.AlloyDBAdmin", "method": "GenerateClientCertificate" },
       { "service": "google.cloud.alloydb.v1alpha.AlloyDBAdmin", "method": "GetConnectionInfo" },
       { "service": "google.cloud.alloydb.v1alpha.AlloyDBAdmin", "method": "ListUsers" },
-      { "service": "google.cloud.alloydb.v1alpha.AlloyDBAdmin", "method": "GetUser" }
+      { "service": "google.cloud.alloydb.v1alpha.AlloyDBAdmin", "method": "GetUser" },
+      { "service": "google.cloud.alloydb.v1alpha.AlloyDBAdmin", "method": "CreateDatabase" },
+      { "service": "google.cloud.alloydb.v1alpha.AlloyDBAdmin", "method": "GetDatabase" },
+      { "service": "google.cloud.alloydb.v1alpha.AlloyDBAdmin", "method": "UpdateDatabase" },
+      { "service": "google.cloud.alloydb.v1alpha.AlloyDBAdmin", "method": "DeleteDatabase" }
     ],
     "timeout": "60s",
     "retryPolicy": {
diff --git a/google/cloud/alloydb/v1alpha/resources.proto b/google/cloud/alloydb/v1alpha/resources.proto
@@ -43,6 +43,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.
@@ -93,6 +101,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
@@ -151,7 +162,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.
@@ -496,7 +509,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
@@ -505,8 +520,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.
@@ -544,11 +563,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.
@@ -764,10 +780,10 @@ message Cluster {
     (google.api.field_behavior) = OPTIONAL
   ];
 
-  // Output only. AlloyDB per-cluster service agent email. This service account
-  // is created per-cluster per-project, and is different from that of the
-  // primary service agent which is created per-project. The service account
-  // naming format is subject to change.
+  // Output only. AlloyDB per-cluster service account. This service account is
+  // created per-cluster per-project, and is different from the per-project
+  // service account. The per-cluster service account naming format is subject
+  // to change.
   string service_account_email = 46 [(google.api.field_behavior) = OUTPUT_ONLY];
 }
 
@@ -983,8 +999,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.
@@ -1051,20 +1071,14 @@ message Instance {
 
   // Configuration for Managed Connection Pool (MCP).
   message ConnectionPoolConfig {
-    // The pool mode. Defaults to `POOL_MODE_TRANSACTION`.
-    enum PoolMode {
-      // The pool mode is not specified. Defaults to `POOL_MODE_TRANSACTION`.
-      POOL_MODE_UNSPECIFIED = 0;
-
-      // Server is released back to pool after a client disconnects.
-      POOL_MODE_SESSION = 1;
-
-      // Server is released back to pool after a transaction finishes.
-      POOL_MODE_TRANSACTION = 2;
-    }
-
     // 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
@@ -1725,13 +1739,43 @@ 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. 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. 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_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
+  ];
+
+  // Optional. Whether the database is a template database.
+  // Deprecated in favor of is_template_database.
+  bool is_template = 5
+      [deprecated = true, (google.api.field_behavior) = OPTIONAL];
+
+  // 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/v1alpha/service.proto b/google/cloud/alloydb/v1alpha/service.proto
@@ -492,6 +492,15 @@ service AlloyDBAdmin {
     };
     option (google.api.method_signature) = "parent";
   }
+
+  // Creates a new Database in a given project, location, and cluster.
+  rpc CreateDatabase(CreateDatabaseRequest) returns (Database) {
+    option (google.api.http) = {
+      post: "/v1alpha/{parent=projects/*/locations/*/clusters/*}/databases"
+      body: "database"
+    };
+    option (google.api.method_signature) = "parent,database,database_id";
+  }
 }
 
 // Message for requesting list of Clusters
@@ -1606,6 +1615,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.
@@ -2021,6 +2034,23 @@ message PromoteClusterStatus {
 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.
@@ -2032,6 +2062,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.
@@ -2218,7 +2251,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 [
@@ -2244,12 +2277,29 @@ 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.
   // If this field is omitted, there are no subsequent pages.
   string next_page_token = 2;
 }
+
+// Message for CreateDatabase request.
+message CreateDatabaseRequest {
+  // Required. Value for parent.
+  string parent = 1 [
+    (google.api.field_behavior) = REQUIRED,
+    (google.api.resource_reference) = {
+      child_type: "alloydb.googleapis.com/Database"
+    }
+  ];
+
+  // Required. ID of the requesting object.
+  string database_id = 2 [(google.api.field_behavior) = REQUIRED];
+
+  // Required. The resource being created.
+  Database database = 3 [(google.api.field_behavior) = REQUIRED];
+}
