feat: adds PITR fields to backup and database

PiperOrigin-RevId: 354462069

google/spanner/admin/database/v1/backup.proto

@@ -61,6 +61,12 @@ message Backup {
                          type: "spanner.googleapis.com/Database"
                        }];
 
+  // The backup will contain an externally consistent copy of the database at
+  // the timestamp specified by `version_time`. If `version_time` is not
+  // specified, the system will set `version_time` to the `create_time` of the
+  // backup.
+  google.protobuf.Timestamp version_time = 9;
+
   // Required for the [CreateBackup][google.spanner.admin.database.v1.DatabaseAdmin.CreateBackup]
   // operation. The expiration time of the backup, with microseconds
   // granularity that must be at least 6 hours and at most 366 days
@@ -84,10 +90,9 @@ message Backup {
   // `projects/<project>/instances/<instance>`.
   string name = 1;
 
-  // Output only. The backup will contain an externally consistent
-  // copy of the database at the timestamp specified by
-  // `create_time`. `create_time` is approximately the time the
-  // [CreateBackup][google.spanner.admin.database.v1.DatabaseAdmin.CreateBackup] request is received.
+  // Output only. The time the [CreateBackup][google.spanner.admin.database.v1.DatabaseAdmin.CreateBackup]
+  // request is received. If the request does not specify `version_time`, the
+  // `version_time` of the backup will be equivalent to the `create_time`.
   google.protobuf.Timestamp create_time = 4 [(google.api.field_behavior) = OUTPUT_ONLY];
 
   // Output only. Size of the backup in bytes.
@@ -134,10 +139,14 @@ message CreateBackupRequest {
 // [CreateBackup][google.spanner.admin.database.v1.DatabaseAdmin.CreateBackup].
 message CreateBackupMetadata {
   // The name of the backup being created.
-  string name = 1;
+  string name = 1 [(google.api.resource_reference) = {
+                     type: "spanner.googleapis.com/Backup"
+                   }];
 
   // The name of the database the backup is created from.
-  string database = 2;
+  string database = 2 [(google.api.resource_reference) = {
+                         type: "spanner.googleapis.com/Database"
+                       }];
 
   // The progress of the
   // [CreateBackup][google.spanner.admin.database.v1.DatabaseAdmin.CreateBackup] operation.
@@ -311,9 +320,9 @@ message ListBackupOperationsRequest {
   //   * `done:true` - The operation is complete.
   //   * `metadata.database:prod` - The database the backup was taken from has
   //      a name containing the string "prod".
-  //   * `(metadata.@type=type.googleapis.com/google.spanner.admin.database.v1.CreateBackupMetadata) AND` <br/>
-  //     `(metadata.name:howl) AND` <br/>
-  //     `(metadata.progress.start_time < \"2018-03-28T14:50:00Z\") AND` <br/>
+  //   * `(metadata.@type=type.googleapis.com/google.spanner.admin.database.v1.CreateBackupMetadata) AND` \
+  //     `(metadata.name:howl) AND` \
+  //     `(metadata.progress.start_time < \"2018-03-28T14:50:00Z\") AND` \
   //     `(error:*)` - Returns operations where:
   //     * The operation's metadata type is [CreateBackupMetadata][google.spanner.admin.database.v1.CreateBackupMetadata].
   //     * The backup name contains the string "howl".
@@ -355,12 +364,23 @@ message ListBackupOperationsResponse {
 // Information about a backup.
 message BackupInfo {
   // Name of the backup.
-  string backup = 1;
+  string backup = 1 [(google.api.resource_reference) = {
+                       type: "spanner.googleapis.com/Backup"
+                     }];
 
   // The backup contains an externally consistent copy of `source_database` at
-  // the timestamp specified by `create_time`.
+  // the timestamp specified by `version_time`. If the
+  // [CreateBackup][google.spanner.admin.database.v1.DatabaseAdmin.CreateBackup] request did not specify
+  // `version_time`, the `version_time` of the backup is equivalent to the
+  // `create_time`.
+  google.protobuf.Timestamp version_time = 4;
+
+  // The time the [CreateBackup][google.spanner.admin.database.v1.DatabaseAdmin.CreateBackup] request was
+  // received.
   google.protobuf.Timestamp create_time = 2;
 
   // Name of the database the backup was created from.
-  string source_database = 3;
+  string source_database = 3 [(google.api.resource_reference) = {
+                                type: "spanner.googleapis.com/Database"
+                              }];
 }

google/spanner/admin/database/v1/spanner_database_admin.proto

@@ -368,6 +368,17 @@ message Database {
   // Output only. Applicable only for restored databases. Contains information
   // about the restore source.
   RestoreInfo restore_info = 4 [(google.api.field_behavior) = OUTPUT_ONLY];
+
+  // Output only. The period in which Cloud Spanner retains all versions of data
+  // for the database. This is the same as the value of version_retention_period
+  // database option set using
+  // [UpdateDatabaseDdl][google.spanner.admin.database.v1.DatabaseAdmin.UpdateDatabaseDdl]. Defaults to 1 hour,
+  // if not set.
+  string version_retention_period = 6 [(google.api.field_behavior) = OUTPUT_ONLY];
+
+  // Output only. Earliest timestamp at which older versions of the data can be
+  // read.
+  google.protobuf.Timestamp earliest_version_time = 7 [(google.api.field_behavior) = OUTPUT_ONLY];
 }
 
 // The request for [ListDatabases][google.spanner.admin.database.v1.DatabaseAdmin.ListDatabases].
@@ -535,6 +546,8 @@ message DropDatabaseRequest {
 // The request for [GetDatabaseDdl][google.spanner.admin.database.v1.DatabaseAdmin.GetDatabaseDdl].
 message GetDatabaseDdlRequest {
   // Required. The database whose schema we wish to get.
+  // Values are of the form
+  // `projects/<project>/instances/<instance>/databases/<database>`
   string database = 1 [
     (google.api.field_behavior) = REQUIRED,
     (google.api.resource_reference) = {
@@ -590,11 +603,11 @@ message ListDatabaseOperationsRequest {
   // Here are a few examples:
   //
   //   * `done:true` - The operation is complete.
-  //   * `(metadata.@type=type.googleapis.com/google.spanner.admin.database.v1.RestoreDatabaseMetadata) AND` <br/>
-  //     `(metadata.source_type:BACKUP) AND` <br/>
-  //     `(metadata.backup_info.backup:backup_howl) AND` <br/>
-  //     `(metadata.name:restored_howl) AND` <br/>
-  //     `(metadata.progress.start_time < \"2018-03-28T14:50:00Z\") AND` <br/>
+  //   * `(metadata.@type=type.googleapis.com/google.spanner.admin.database.v1.RestoreDatabaseMetadata) AND` \
+  //     `(metadata.source_type:BACKUP) AND` \
+  //     `(metadata.backup_info.backup:backup_howl) AND` \
+  //     `(metadata.name:restored_howl) AND` \
+  //     `(metadata.progress.start_time < \"2018-03-28T14:50:00Z\") AND` \
   //     `(error:*)` - Return operations where:
   //     * The operation's metadata type is [RestoreDatabaseMetadata][google.spanner.admin.database.v1.RestoreDatabaseMetadata].
   //     * The database is restored from a backup.
@@ -666,7 +679,9 @@ message RestoreDatabaseRequest {
 // [RestoreDatabase][google.spanner.admin.database.v1.DatabaseAdmin.RestoreDatabase].
 message RestoreDatabaseMetadata {
   // Name of the database being created and restored to.
-  string name = 1;
+  string name = 1 [(google.api.resource_reference) = {
+                     type: "spanner.googleapis.com/Database"
+                   }];
 
   // The type of the restore source.
   RestoreSourceType source_type = 2;
@@ -716,7 +731,9 @@ message RestoreDatabaseMetadata {
 // completion of a database restore, and cannot be cancelled.
 message OptimizeRestoredDatabaseMetadata {
   // Name of the restored database being optimized.
-  string name = 1;
+  string name = 1 [(google.api.resource_reference) = {
+                     type: "spanner.googleapis.com/Database"
+                   }];
 
   // The progress of the post-restore optimizations.
   OperationProgress progress = 2;