// Copyright 2021 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.spanner.admin.database.v1;

import "google/api/field_behavior.proto";
import "google/api/resource.proto";
import "google/longrunning/operations.proto";
import "google/protobuf/field_mask.proto";
import "google/protobuf/timestamp.proto";
import "google/spanner/admin/database/v1/common.proto";

option csharp_namespace = "Google.Cloud.Spanner.Admin.Database.V1";
option go_package = "google.golang.org/genproto/googleapis/spanner/admin/database/v1;database";
option java_multiple_files = true;
option java_outer_classname = "BackupProto";
option java_package = "com.google.spanner.admin.database.v1";
option php_namespace = "Google\\Cloud\\Spanner\\Admin\\Database\\V1";
option ruby_package = "Google::Cloud::Spanner::Admin::Database::V1";

// A backup of a Cloud Spanner database.
message Backup {
  option (google.api.resource) = {
    type: "spanner.googleapis.com/Backup"
    pattern: "projects/{project}/instances/{instance}/backups/{backup}"
  };

  // Indicates the current state of the backup.
  enum State {
    // Not specified.
    STATE_UNSPECIFIED = 0;

    // The pending backup is still being created. Operations on the
    // backup may fail with `FAILED_PRECONDITION` in this state.
    CREATING = 1;

    // The backup is complete and ready for use.
    READY = 2;
  }

  // Required for the
  // [CreateBackup][google.spanner.admin.database.v1.DatabaseAdmin.CreateBackup]
  // operation. Name of the database from which this backup was created. This
  // needs to be in the same instance as the backup. Values are of the form
  // `projects/<project>/instances/<instance>/databases/<database>`.
  string database = 2 [(google.api.resource_reference) = {
    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
  // from the time the CreateBackup request is processed. Once the `expire_time`
  // has passed, the backup is eligible to be automatically deleted by Cloud
  // Spanner to free the resources used by the backup.
  google.protobuf.Timestamp expire_time = 3;

  // Output only for the
  // [CreateBackup][google.spanner.admin.database.v1.DatabaseAdmin.CreateBackup]
  // operation. Required for the
  // [UpdateBackup][google.spanner.admin.database.v1.DatabaseAdmin.UpdateBackup]
  // operation.
  //
  // A globally unique identifier for the backup which cannot be
  // changed. Values are of the form
  // `projects/<project>/instances/<instance>/backups/[a-z][a-z0-9_\-]*[a-z0-9]`
  // The final segment of the name must be between 2 and 60 characters
  // in length.
  //
  // The backup is stored in the location(s) specified in the instance
  // configuration of the instance containing the backup, identified
  // by the prefix of the backup name of the form
  // `projects/<project>/instances/<instance>`.
  string name = 1;

  // 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.
  int64 size_bytes = 5 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The current state of the backup.
  State state = 6 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The names of the restored databases that reference the backup.
  // The database names are of
  // the form `projects/<project>/instances/<instance>/databases/<database>`.
  // Referencing databases may exist in different instances. The existence of
  // any referencing database prevents the backup from being deleted. When a
  // restored database from the backup enters the `READY` state, the reference
  // to the backup is removed.
  repeated string referencing_databases = 7 [
    (google.api.field_behavior) = OUTPUT_ONLY,
    (google.api.resource_reference) = {
      type: "spanner.googleapis.com/Database"
    }
  ];

  // Output only. The encryption information for the backup.
  EncryptionInfo encryption_info = 8
      [(google.api.field_behavior) = OUTPUT_ONLY];
}

// The request for
// [CreateBackup][google.spanner.admin.database.v1.DatabaseAdmin.CreateBackup].
message CreateBackupRequest {
  // Required. The name of the instance in which the backup will be
  // created. This must be the same instance that contains the database the
  // backup will be created from. The backup will be stored in the
  // location(s) specified in the instance configuration of this
  // instance. Values are of the form
  // `projects/<project>/instances/<instance>`.
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "spanner.googleapis.com/Instance"
    }
  ];

  // Required. The id of the backup to be created. The `backup_id` appended to
  // `parent` forms the full backup name of the form
  // `projects/<project>/instances/<instance>/backups/<backup_id>`.
  string backup_id = 2 [(google.api.field_behavior) = REQUIRED];

  // Required. The backup to create.
  Backup backup = 3 [(google.api.field_behavior) = REQUIRED];

  // Optional. The encryption configuration used to encrypt the backup. If this
  // field is not specified, the backup will use the same encryption
  // configuration as the database by default, namely
  // [encryption_type][google.spanner.admin.database.v1.CreateBackupEncryptionConfig.encryption_type]
  // = `USE_DATABASE_ENCRYPTION`.
  CreateBackupEncryptionConfig encryption_config = 4
      [(google.api.field_behavior) = OPTIONAL];
}

// Metadata type for the operation returned by
// [CreateBackup][google.spanner.admin.database.v1.DatabaseAdmin.CreateBackup].
message CreateBackupMetadata {
  // The name of the backup being created.
  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 [(google.api.resource_reference) = {
    type: "spanner.googleapis.com/Database"
  }];

  // The progress of the
  // [CreateBackup][google.spanner.admin.database.v1.DatabaseAdmin.CreateBackup]
  // operation.
  OperationProgress progress = 3;

  // The time at which cancellation of this operation was received.
  // [Operations.CancelOperation][google.longrunning.Operations.CancelOperation]
  // starts asynchronous cancellation on a long-running operation. The server
  // makes a best effort to cancel the operation, but success is not guaranteed.
  // Clients can use
  // [Operations.GetOperation][google.longrunning.Operations.GetOperation] or
  // other methods to check whether the cancellation succeeded or whether the
  // operation completed despite cancellation. On successful cancellation,
  // the operation is not deleted; instead, it becomes an operation with
  // an [Operation.error][google.longrunning.Operation.error] value with a
  // [google.rpc.Status.code][google.rpc.Status.code] of 1,
  // corresponding to `Code.CANCELLED`.
  google.protobuf.Timestamp cancel_time = 4;
}

// The request for
// [UpdateBackup][google.spanner.admin.database.v1.DatabaseAdmin.UpdateBackup].
message UpdateBackupRequest {
  // Required. The backup to update. `backup.name`, and the fields to be updated
  // as specified by `update_mask` are required. Other fields are ignored.
  // Update is only supported for the following fields:
  //  * `backup.expire_time`.
  Backup backup = 1 [(google.api.field_behavior) = REQUIRED];

  // Required. A mask specifying which fields (e.g. `expire_time`) in the
  // Backup resource should be updated. This mask is relative to the Backup
  // resource, not to the request message. The field mask must always be
  // specified; this prevents any future fields from being erased accidentally
  // by clients that do not know about them.
  google.protobuf.FieldMask update_mask = 2
      [(google.api.field_behavior) = REQUIRED];
}

// The request for
// [GetBackup][google.spanner.admin.database.v1.DatabaseAdmin.GetBackup].
message GetBackupRequest {
  // Required. Name of the backup.
  // Values are of the form
  // `projects/<project>/instances/<instance>/backups/<backup>`.
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = { type: "spanner.googleapis.com/Backup" }
  ];
}

// The request for
// [DeleteBackup][google.spanner.admin.database.v1.DatabaseAdmin.DeleteBackup].
message DeleteBackupRequest {
  // Required. Name of the backup to delete.
  // Values are of the form
  // `projects/<project>/instances/<instance>/backups/<backup>`.
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = { type: "spanner.googleapis.com/Backup" }
  ];
}

// The request for
// [ListBackups][google.spanner.admin.database.v1.DatabaseAdmin.ListBackups].
message ListBackupsRequest {
  // Required. The instance to list backups from.  Values are of the
  // form `projects/<project>/instances/<instance>`.
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "spanner.googleapis.com/Instance"
    }
  ];

  // An expression that filters the list of returned backups.
  //
  // A filter expression consists of a field name, a comparison operator, and a
  // value for filtering.
  // The value must be a string, a number, or a boolean. The comparison operator
  // must be one of: `<`, `>`, `<=`, `>=`, `!=`, `=`, or `:`.
  // Colon `:` is the contains operator. Filter rules are not case sensitive.
  //
  // The following fields in the
  // [Backup][google.spanner.admin.database.v1.Backup] are eligible for
  // filtering:
  //
  //   * `name`
  //   * `database`
  //   * `state`
  //   * `create_time`  (and values are of the format YYYY-MM-DDTHH:MM:SSZ)
  //   * `expire_time`  (and values are of the format YYYY-MM-DDTHH:MM:SSZ)
  //   * `version_time` (and values are of the format YYYY-MM-DDTHH:MM:SSZ)
  //   * `size_bytes`
  //
  // You can combine multiple expressions by enclosing each expression in
  // parentheses. By default, expressions are combined with AND logic, but
  // you can specify AND, OR, and NOT logic explicitly.
  //
  // Here are a few examples:
  //
  //   * `name:Howl` - The backup's name contains the string "howl".
  //   * `database:prod`
  //          - The database's name contains the string "prod".
  //   * `state:CREATING` - The backup is pending creation.
  //   * `state:READY` - The backup is fully created and ready for use.
  //   * `(name:howl) AND (create_time < \"2018-03-28T14:50:00Z\")`
  //          - The backup name contains the string "howl" and `create_time`
  //              of the backup is before 2018-03-28T14:50:00Z.
  //   * `expire_time < \"2018-03-28T14:50:00Z\"`
  //          - The backup `expire_time` is before 2018-03-28T14:50:00Z.
  //   * `size_bytes > 10000000000` - The backup's size is greater than 10GB
  string filter = 2;

  // Number of backups to be returned in the response. If 0 or
  // less, defaults to the server's maximum allowed page size.
  int32 page_size = 3;

  // If non-empty, `page_token` should contain a
  // [next_page_token][google.spanner.admin.database.v1.ListBackupsResponse.next_page_token]
  // from a previous
  // [ListBackupsResponse][google.spanner.admin.database.v1.ListBackupsResponse]
  // to the same `parent` and with the same `filter`.
  string page_token = 4;
}

// The response for
// [ListBackups][google.spanner.admin.database.v1.DatabaseAdmin.ListBackups].
message ListBackupsResponse {
  // The list of matching backups. Backups returned are ordered by `create_time`
  // in descending order, starting from the most recent `create_time`.
  repeated Backup backups = 1;

  // `next_page_token` can be sent in a subsequent
  // [ListBackups][google.spanner.admin.database.v1.DatabaseAdmin.ListBackups]
  // call to fetch more of the matching backups.
  string next_page_token = 2;
}

// The request for
// [ListBackupOperations][google.spanner.admin.database.v1.DatabaseAdmin.ListBackupOperations].
message ListBackupOperationsRequest {
  // Required. The instance of the backup operations. Values are of
  // the form `projects/<project>/instances/<instance>`.
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "spanner.googleapis.com/Instance"
    }
  ];

  // An expression that filters the list of returned backup operations.
  //
  // A filter expression consists of a field name, a
  // comparison operator, and a value for filtering.
  // The value must be a string, a number, or a boolean. The comparison operator
  // must be one of: `<`, `>`, `<=`, `>=`, `!=`, `=`, or `:`.
  // Colon `:` is the contains operator. Filter rules are not case sensitive.
  //
  // The following fields in the [operation][google.longrunning.Operation]
  // are eligible for filtering:
  //
  //   * `name` - The name of the long-running operation
  //   * `done` - False if the operation is in progress, else true.
  //   * `metadata.@type` - the type of metadata. For example, the type string
  //      for
  //      [CreateBackupMetadata][google.spanner.admin.database.v1.CreateBackupMetadata]
  //      is
  //      `type.googleapis.com/google.spanner.admin.database.v1.CreateBackupMetadata`.
  //   * `metadata.<field_name>` - any field in metadata.value.
  //   * `error` - Error associated with the long-running operation.
  //   * `response.@type` - the type of response.
  //   * `response.<field_name>` - any field in response.value.
  //
  // You can combine multiple expressions by enclosing each expression in
  // parentheses. By default, expressions are combined with AND logic, but
  // you can specify AND, OR, and NOT logic explicitly.
  //
  // Here are a few examples:
  //
  //   * `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` \
  //     `(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".
  //     * The operation started before 2018-03-28T14:50:00Z.
  //     * The operation resulted in an error.
  string filter = 2;

  // Number of operations to be returned in the response. If 0 or
  // less, defaults to the server's maximum allowed page size.
  int32 page_size = 3;

  // If non-empty, `page_token` should contain a
  // [next_page_token][google.spanner.admin.database.v1.ListBackupOperationsResponse.next_page_token]
  // from a previous
  // [ListBackupOperationsResponse][google.spanner.admin.database.v1.ListBackupOperationsResponse]
  // to the same `parent` and with the same `filter`.
  string page_token = 4;
}

// The response for
// [ListBackupOperations][google.spanner.admin.database.v1.DatabaseAdmin.ListBackupOperations].
message ListBackupOperationsResponse {
  // The list of matching backup [long-running
  // operations][google.longrunning.Operation]. Each operation's name will be
  // prefixed by the backup's name and the operation's
  // [metadata][google.longrunning.Operation.metadata] will be of type
  // [CreateBackupMetadata][google.spanner.admin.database.v1.CreateBackupMetadata].
  // Operations returned include those that are pending or have
  // completed/failed/canceled within the last 7 days. Operations returned are
  // ordered by `operation.metadata.value.progress.start_time` in descending
  // order starting from the most recently started operation.
  repeated google.longrunning.Operation operations = 1;

  // `next_page_token` can be sent in a subsequent
  // [ListBackupOperations][google.spanner.admin.database.v1.DatabaseAdmin.ListBackupOperations]
  // call to fetch more of the matching metadata.
  string next_page_token = 2;
}

// Information about a backup.
message BackupInfo {
  // Name of the backup.
  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 `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 [(google.api.resource_reference) = {
    type: "spanner.googleapis.com/Database"
  }];
}

// Encryption configuration for the backup to create.
message CreateBackupEncryptionConfig {
  // Encryption types for the backup.
  enum EncryptionType {
    // Unspecified. Do not use.
    ENCRYPTION_TYPE_UNSPECIFIED = 0;

    // Use the same encryption configuration as the database. This is the
    // default option when
    // [encryption_config][google.spanner.admin.database.v1.CreateBackupEncryptionConfig]
    // is empty. For example, if the database is using
    // `Customer_Managed_Encryption`, the backup will be using the same Cloud
    // KMS key as the database.
    USE_DATABASE_ENCRYPTION = 1;

    // Use Google default encryption.
    GOOGLE_DEFAULT_ENCRYPTION = 2;

    // Use customer managed encryption. If specified, `kms_key_name`
    // must contain a valid Cloud KMS key.
    CUSTOMER_MANAGED_ENCRYPTION = 3;
  }

  // Required. The encryption type of the backup.
  EncryptionType encryption_type = 1 [(google.api.field_behavior) = REQUIRED];

  // Optional. The Cloud KMS key that will be used to protect the backup.
  // This field should be set only when
  // [encryption_type][google.spanner.admin.database.v1.CreateBackupEncryptionConfig.encryption_type]
  // is `CUSTOMER_MANAGED_ENCRYPTION`. Values are of the form
  // `projects/<project>/locations/<location>/keyRings/<key_ring>/cryptoKeys/<kms_key_name>`.
  string kms_key_name = 2 [
    (google.api.field_behavior) = OPTIONAL,
    (google.api.resource_reference) = {
      type: "cloudkms.googleapis.com/CryptoKey"
    }
  ];
}