feat: add Firestore CloneDatabase support

Google APIs · copybara-github · commit 3d37c58ad2a4 · 2025-08-01T10:20:59.000-07:00
PiperOrigin-RevId: 789807783
diff --git a/google/firestore/admin/v1/BUILD.bazel b/google/firestore/admin/v1/BUILD.bazel
@@ -32,13 +32,15 @@ proto_library(
         "location.proto",
         "operation.proto",
         "schedule.proto",
+        "snapshot.proto",
         "user_creds.proto",
     ],
     deps = [
         "//google/api:annotations_proto",
         "//google/api:client_proto",
         "//google/api:field_behavior_proto",
         "//google/api:resource_proto",
+        "//google/api:routing_proto",
         "//google/longrunning:operations_proto",
         "//google/type:dayofweek_proto",
         "@com_google_protobuf//:duration_proto",
diff --git a/google/firestore/admin/v1/firestore_admin.proto b/google/firestore/admin/v1/firestore_admin.proto
@@ -20,12 +20,14 @@ import "google/api/annotations.proto";
 import "google/api/client.proto";
 import "google/api/field_behavior.proto";
 import "google/api/resource.proto";
+import "google/api/routing.proto";
 import "google/firestore/admin/v1/backup.proto";
 import "google/firestore/admin/v1/database.proto";
 import "google/firestore/admin/v1/field.proto";
 import "google/firestore/admin/v1/index.proto";
 import "google/firestore/admin/v1/operation.proto";
 import "google/firestore/admin/v1/schedule.proto";
+import "google/firestore/admin/v1/snapshot.proto";
 import "google/firestore/admin/v1/user_creds.proto";
 import "google/longrunning/operations.proto";
 import "google/protobuf/empty.proto";
@@ -458,6 +460,45 @@ service FirestoreAdmin {
     };
     option (google.api.method_signature) = "name";
   }
+
+  // Creates a new database by cloning an existing one.
+  //
+  // The new database must be in the same cloud region or multi-region location
+  // as the existing database. This behaves similar to
+  // [FirestoreAdmin.CreateDatabase][google.firestore.admin.v1.FirestoreAdmin.CreateDatabase]
+  // except instead of creating a new empty database, a new database is created
+  // with the database type, index configuration, and documents from an existing
+  // database.
+  //
+  // The [long-running operation][google.longrunning.Operation] can be used to
+  // track the progress of the clone, with the Operation's
+  // [metadata][google.longrunning.Operation.metadata] field type being the
+  // [CloneDatabaseMetadata][google.firestore.admin.v1.CloneDatabaseMetadata].
+  // The [response][google.longrunning.Operation.response] type is the
+  // [Database][google.firestore.admin.v1.Database] if the clone was
+  // successful. The new database is not readable or writeable until the LRO has
+  // completed.
+  rpc CloneDatabase(CloneDatabaseRequest)
+      returns (google.longrunning.Operation) {
+    option (google.api.http) = {
+      post: "/v1/{parent=projects/*}/databases:clone"
+      body: "*"
+    };
+    option (google.api.routing) = {
+      routing_parameters {
+        field: "pitr_snapshot.database"
+        path_template: "projects/{project_id=*}/**"
+      }
+      routing_parameters {
+        field: "pitr_snapshot.database"
+        path_template: "projects/*/databases/{database_id=*}/**"
+      }
+    };
+    option (google.longrunning.operation_info) = {
+      response_type: "Database"
+      metadata_type: "CloneDatabaseMetadata"
+    };
+  }
 }
 
 // A request to list the Firestore Databases in all locations for a project.
@@ -1137,3 +1178,51 @@ message RestoreDatabaseRequest {
     (google.api.field_behavior) = OPTIONAL
   ];
 }
+
+// The request message for
+// [FirestoreAdmin.CloneDatabase][google.firestore.admin.v1.FirestoreAdmin.CloneDatabase].
+message CloneDatabaseRequest {
+  // Required. The project to clone the database in. Format is
+  // `projects/{project_id}`.
+  string parent = 1 [
+    (google.api.field_behavior) = REQUIRED,
+    (google.api.resource_reference) = {
+      child_type: "firestore.googleapis.com/Database"
+    }
+  ];
+
+  // Required. The ID to use for the database, which will become the final
+  // component of the database's resource name. This database ID must not be
+  // associated with an existing database.
+  //
+  // This value should be 4-63 characters. Valid characters are /[a-z][0-9]-/
+  // with first character a letter and the last a letter or a number. Must not
+  // be UUID-like /[0-9a-f]{8}(-[0-9a-f]{4}){3}-[0-9a-f]{12}/.
+  //
+  // "(default)" database ID is also valid.
+  string database_id = 2 [(google.api.field_behavior) = REQUIRED];
+
+  // Required. Specification of the PITR data to clone from. The source database
+  // must exist.
+  //
+  // The cloned database will be created in the same location as the source
+  // database.
+  PitrSnapshot pitr_snapshot = 6 [(google.api.field_behavior) = REQUIRED];
+
+  // Optional. Encryption configuration for the cloned database.
+  //
+  // If this field is not specified, the cloned database will use
+  // the same encryption configuration as the source database, namely
+  // [use_source_encryption][google.firestore.admin.v1.Database.EncryptionConfig.use_source_encryption].
+  Database.EncryptionConfig encryption_config = 4
+      [(google.api.field_behavior) = OPTIONAL];
+
+  // Optional. Immutable. Tags to be bound to the cloned database.
+  //
+  // The tags should be provided in the format of
+  // `tagKeys/{tag_key_id} -> tagValues/{tag_value_id}`.
+  map<string, string> tags = 5 [
+    (google.api.field_behavior) = IMMUTABLE,
+    (google.api.field_behavior) = OPTIONAL
+  ];
+}
diff --git a/google/firestore/admin/v1/firestore_admin_grpc_service_config.json b/google/firestore/admin/v1/firestore_admin_grpc_service_config.json
@@ -70,6 +70,10 @@
         {
           "service": "google.firestore.admin.v1.FirestoreAdmin",
           "method": "RestoreDatabase"
+        },
+        {
+          "service": "google.firestore.admin.v1.FirestoreAdmin",
+          "method": "CloneDatabase"
         }
       ],
       "timeout": "120s"
diff --git a/google/firestore/admin/v1/firestore_v1.yaml b/google/firestore/admin/v1/firestore_v1.yaml
@@ -10,6 +10,7 @@ apis:
 
 types:
 - name: google.firestore.admin.v1.BulkDeleteDocumentsMetadata
+- name: google.firestore.admin.v1.CloneDatabaseMetadata
 - name: google.firestore.admin.v1.CreateDatabaseMetadata
 - name: google.firestore.admin.v1.DeleteDatabaseMetadata
 - name: google.firestore.admin.v1.ExportDocumentsMetadata
diff --git a/google/firestore/admin/v1/operation.proto b/google/firestore/admin/v1/operation.proto
@@ -18,6 +18,7 @@ package google.firestore.admin.v1;
 
 import "google/api/resource.proto";
 import "google/firestore/admin/v1/index.proto";
+import "google/firestore/admin/v1/snapshot.proto";
 import "google/protobuf/timestamp.proto";
 
 option csharp_namespace = "Google.Cloud.Firestore.Admin.V1";
@@ -259,6 +260,30 @@ message RestoreDatabaseMetadata {
   Progress progress_percentage = 8;
 }
 
+// Metadata for the [long-running operation][google.longrunning.Operation] from
+// the [CloneDatabase][google.firestore.admin.v1.CloneDatabase] request.
+message CloneDatabaseMetadata {
+  // The time the clone was started.
+  google.protobuf.Timestamp start_time = 1;
+
+  // The time the clone finished, unset for ongoing clones.
+  google.protobuf.Timestamp end_time = 2;
+
+  // The operation state of the clone.
+  OperationState operation_state = 3;
+
+  // The name of the database being cloned to.
+  string database = 4 [(google.api.resource_reference) = {
+    type: "firestore.googleapis.com/Database"
+  }];
+
+  // The snapshot from which this database was cloned.
+  PitrSnapshot pitr_snapshot = 7;
+
+  // How far along the clone is as an estimated percentage of remaining time.
+  Progress progress_percentage = 6;
+}
+
 // Describes the progress of the operation.
 // Unit of work is generic and must be interpreted based on where
 // [Progress][google.firestore.admin.v1.Progress] is used.
diff --git a/google/firestore/admin/v1/snapshot.proto b/google/firestore/admin/v1/snapshot.proto
@@ -0,0 +1,53 @@
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+syntax = "proto3";
+
+package google.firestore.admin.v1;
+
+import "google/api/field_behavior.proto";
+import "google/api/resource.proto";
+import "google/protobuf/timestamp.proto";
+
+option csharp_namespace = "Google.Cloud.Firestore.Admin.V1";
+option go_package = "cloud.google.com/go/firestore/apiv1/admin/adminpb;adminpb";
+option java_multiple_files = true;
+option java_outer_classname = "PitrSnapshotProto";
+option java_package = "com.google.firestore.admin.v1";
+option objc_class_prefix = "GCFS";
+option php_namespace = "Google\\Cloud\\Firestore\\Admin\\V1";
+option ruby_package = "Google::Cloud::Firestore::Admin::V1";
+
+// A consistent snapshot of a database at a specific point in time.
+// A PITR (Point-in-time recovery) snapshot with previous versions of a
+// database's data is available for every minute up to the associated database's
+// data retention period. If the PITR feature is enabled, the retention period
+// is 7 days; otherwise, it is one hour.
+message PitrSnapshot {
+  // Required. The name of the database that this was a snapshot of. Format:
+  // `projects/{project}/databases/{database}`.
+  string database = 1 [
+    (google.api.field_behavior) = REQUIRED,
+    (google.api.resource_reference) = {
+      type: "firestore.googleapis.com/Database"
+    }
+  ];
+
+  // Output only. Public UUID of the database the snapshot was associated with.
+  bytes database_uid = 2 [(google.api.field_behavior) = OUTPUT_ONLY];
+
+  // Required. Snapshot time of the database.
+  google.protobuf.Timestamp snapshot_time = 3
+      [(google.api.field_behavior) = REQUIRED];
+}
