@google-cloud/spanner-api 0.1.0

package/build/protos/google/spanner/admin/database/v1/backup_schedule.proto

@@ -0,0 +1,230 @@
+// 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.spanner.admin.database.v1;
+
+import "google/api/field_behavior.proto";
+import "google/api/resource.proto";
+import "google/protobuf/duration.proto";
+import "google/protobuf/field_mask.proto";
+import "google/protobuf/timestamp.proto";
+import "google/spanner/admin/database/v1/backup.proto";
+
+option csharp_namespace = "Google.Cloud.Spanner.Admin.Database.V1";
+option go_package = "cloud.google.com/go/spanner/admin/database/apiv1/databasepb;databasepb";
+option java_multiple_files = true;
+option java_outer_classname = "BackupScheduleProto";
+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";
+
+// Defines specifications of the backup schedule.
+message BackupScheduleSpec {
+  // Required.
+  oneof schedule_spec {
+    // Cron style schedule specification.
+    CrontabSpec cron_spec = 1;
+  }
+}
+
+// BackupSchedule expresses the automated backup creation specification for a
+// Spanner database.
+// Next ID: 10
+message BackupSchedule {
+  option (google.api.resource) = {
+    type: "spanner.googleapis.com/BackupSchedule"
+    pattern: "projects/{project}/instances/{instance}/databases/{database}/backupSchedules/{schedule}"
+    plural: "backupSchedules"
+    singular: "backupSchedule"
+  };
+
+  // Identifier. Output only for the
+  // [CreateBackupSchedule][DatabaseAdmin.CreateBackupSchededule] operation.
+  // Required for the
+  // [UpdateBackupSchedule][google.spanner.admin.database.v1.DatabaseAdmin.UpdateBackupSchedule]
+  // operation. A globally unique identifier for the backup schedule which
+  // cannot be changed. Values are of the form
+  // `projects/<project>/instances/<instance>/databases/<database>/backupSchedules/[a-z][a-z0-9_\-]*[a-z0-9]`
+  // The final segment of the name must be between 2 and 60 characters in
+  // length.
+  string name = 1 [(google.api.field_behavior) = IDENTIFIER];
+
+  // Optional. The schedule specification based on which the backup creations
+  // are triggered.
+  BackupScheduleSpec spec = 6 [(google.api.field_behavior) = OPTIONAL];
+
+  // Optional. The retention duration of a backup that must be at least 6 hours
+  // and at most 366 days. The backup is eligible to be automatically deleted
+  // once the retention period has elapsed.
+  google.protobuf.Duration retention_duration = 3
+      [(google.api.field_behavior) = OPTIONAL];
+
+  // Optional. The encryption configuration that will be used to encrypt the
+  // backup. If this field is not specified, the backup will use the same
+  // encryption configuration as the database.
+  CreateBackupEncryptionConfig encryption_config = 4
+      [(google.api.field_behavior) = OPTIONAL];
+
+  // Required. Backup type spec determines the type of backup that is created by
+  // the backup schedule. Currently, only full backups are supported.
+  oneof backup_type_spec {
+    // The schedule creates only full backups.
+    FullBackupSpec full_backup_spec = 7;
+
+    // The schedule creates incremental backup chains.
+    IncrementalBackupSpec incremental_backup_spec = 8;
+  }
+
+  // Output only. The timestamp at which the schedule was last updated.
+  // If the schedule has never been updated, this field contains the timestamp
+  // when the schedule was first created.
+  google.protobuf.Timestamp update_time = 9
+      [(google.api.field_behavior) = OUTPUT_ONLY];
+}
+
+// CrontabSpec can be used to specify the version time and frequency at
+// which the backup should be created.
+message CrontabSpec {
+  // Required. Textual representation of the crontab. User can customize the
+  // backup frequency and the backup version time using the cron
+  // expression. The version time must be in UTC timezone.
+  //
+  // The backup will contain an externally consistent copy of the
+  // database at the version time. Allowed frequencies are 12 hour, 1 day,
+  // 1 week and 1 month. Examples of valid cron specifications:
+  //   * `0 2/12 * * * ` : every 12 hours at (2, 14) hours past midnight in UTC.
+  //   * `0 2,14 * * * ` : every 12 hours at (2,14) hours past midnight in UTC.
+  //   * `0 2 * * * `    : once a day at 2 past midnight in UTC.
+  //   * `0 2 * * 0 `    : once a week every Sunday at 2 past midnight in UTC.
+  //   * `0 2 8 * * `    : once a month on 8th day at 2 past midnight in UTC.
+  string text = 1 [(google.api.field_behavior) = REQUIRED];
+
+  // Output only. The time zone of the times in `CrontabSpec.text`. Currently
+  // only UTC is supported.
+  string time_zone = 2 [(google.api.field_behavior) = OUTPUT_ONLY];
+
+  // Output only. Schedule backups will contain an externally consistent copy
+  // of the database at the version time specified in
+  // `schedule_spec.cron_spec`. However, Spanner may not initiate the creation
+  // of the scheduled backups at that version time. Spanner will initiate
+  // the creation of scheduled backups within the time window bounded by the
+  // version_time specified in `schedule_spec.cron_spec` and version_time +
+  // `creation_window`.
+  google.protobuf.Duration creation_window = 3
+      [(google.api.field_behavior) = OUTPUT_ONLY];
+}
+
+// The request for
+// [CreateBackupSchedule][google.spanner.admin.database.v1.DatabaseAdmin.CreateBackupSchedule].
+message CreateBackupScheduleRequest {
+  // Required. The name of the database that this backup schedule applies to.
+  string parent = 1 [
+    (google.api.field_behavior) = REQUIRED,
+    (google.api.resource_reference) = {
+      type: "spanner.googleapis.com/Database"
+    }
+  ];
+
+  // Required. The Id to use for the backup schedule. The `backup_schedule_id`
+  // appended to `parent` forms the full backup schedule name of the form
+  // `projects/<project>/instances/<instance>/databases/<database>/backupSchedules/<backup_schedule_id>`.
+  string backup_schedule_id = 2 [(google.api.field_behavior) = REQUIRED];
+
+  // Required. The backup schedule to create.
+  BackupSchedule backup_schedule = 3 [(google.api.field_behavior) = REQUIRED];
+}
+
+// The request for
+// [GetBackupSchedule][google.spanner.admin.database.v1.DatabaseAdmin.GetBackupSchedule].
+message GetBackupScheduleRequest {
+  // Required. The name of the schedule to retrieve.
+  // Values are of the form
+  // `projects/<project>/instances/<instance>/databases/<database>/backupSchedules/<backup_schedule_id>`.
+  string name = 1 [
+    (google.api.field_behavior) = REQUIRED,
+    (google.api.resource_reference) = {
+      type: "spanner.googleapis.com/BackupSchedule"
+    }
+  ];
+}
+
+// The request for
+// [DeleteBackupSchedule][google.spanner.admin.database.v1.DatabaseAdmin.DeleteBackupSchedule].
+message DeleteBackupScheduleRequest {
+  // Required. The name of the schedule to delete.
+  // Values are of the form
+  // `projects/<project>/instances/<instance>/databases/<database>/backupSchedules/<backup_schedule_id>`.
+  string name = 1 [
+    (google.api.field_behavior) = REQUIRED,
+    (google.api.resource_reference) = {
+      type: "spanner.googleapis.com/BackupSchedule"
+    }
+  ];
+}
+
+// The request for
+// [ListBackupSchedules][google.spanner.admin.database.v1.DatabaseAdmin.ListBackupSchedules].
+message ListBackupSchedulesRequest {
+  // Required. Database is the parent resource whose backup schedules should be
+  // listed. Values are of the form
+  // projects/<project>/instances/<instance>/databases/<database>
+  string parent = 1 [
+    (google.api.field_behavior) = REQUIRED,
+    (google.api.resource_reference) = {
+      type: "spanner.googleapis.com/Database"
+    }
+  ];
+
+  // Optional. Number of backup schedules to be returned in the response. If 0
+  // or less, defaults to the server's maximum allowed page size.
+  int32 page_size = 2 [(google.api.field_behavior) = OPTIONAL];
+
+  // Optional. If non-empty, `page_token` should contain a
+  // [next_page_token][google.spanner.admin.database.v1.ListBackupSchedulesResponse.next_page_token]
+  // from a previous
+  // [ListBackupSchedulesResponse][google.spanner.admin.database.v1.ListBackupSchedulesResponse]
+  // to the same `parent`.
+  string page_token = 4 [(google.api.field_behavior) = OPTIONAL];
+}
+
+// The response for
+// [ListBackupSchedules][google.spanner.admin.database.v1.DatabaseAdmin.ListBackupSchedules].
+message ListBackupSchedulesResponse {
+  // The list of backup schedules for a database.
+  repeated BackupSchedule backup_schedules = 1;
+
+  // `next_page_token` can be sent in a subsequent
+  // [ListBackupSchedules][google.spanner.admin.database.v1.DatabaseAdmin.ListBackupSchedules]
+  // call to fetch more of the schedules.
+  string next_page_token = 2;
+}
+
+// The request for
+// [UpdateBackupScheduleRequest][google.spanner.admin.database.v1.DatabaseAdmin.UpdateBackupSchedule].
+message UpdateBackupScheduleRequest {
+  // Required. The backup schedule to update. `backup_schedule.name`, and the
+  // fields to be updated as specified by `update_mask` are required. Other
+  // fields are ignored.
+  BackupSchedule backup_schedule = 1 [(google.api.field_behavior) = REQUIRED];
+
+  // Required. A mask specifying which fields in the BackupSchedule resource
+  // should be updated. This mask is relative to the BackupSchedule resource,
+  // not to the request message. The field mask must always be
+  // specified; this prevents any future fields from being erased
+  // accidentally.
+  google.protobuf.FieldMask update_mask = 2
+      [(google.api.field_behavior) = REQUIRED];
+}

package/build/protos/google/spanner/admin/database/v1/common.proto

@@ -0,0 +1,132 @@
+// 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.spanner.admin.database.v1;
+
+import "google/api/field_behavior.proto";
+import "google/api/resource.proto";
+import "google/protobuf/timestamp.proto";
+import "google/rpc/status.proto";
+
+option csharp_namespace = "Google.Cloud.Spanner.Admin.Database.V1";
+option go_package = "cloud.google.com/go/spanner/admin/database/apiv1/databasepb;databasepb";
+option java_multiple_files = true;
+option java_outer_classname = "CommonProto";
+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";
+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: "cloudkms.googleapis.com/CryptoKeyVersion"
+  pattern: "projects/{project}/locations/{location}/keyRings/{key_ring}/cryptoKeys/{crypto_key}/cryptoKeyVersions/{crypto_key_version}"
+};
+
+// Encapsulates progress related information for a Cloud Spanner long
+// running operation.
+message OperationProgress {
+  // Percent completion of the operation.
+  // Values are between 0 and 100 inclusive.
+  int32 progress_percent = 1;
+
+  // Time the request was received.
+  google.protobuf.Timestamp start_time = 2;
+
+  // If set, the time at which this operation failed or was completed
+  // successfully.
+  google.protobuf.Timestamp end_time = 3;
+}
+
+// Encryption configuration for a Cloud Spanner database.
+message EncryptionConfig {
+  // The Cloud KMS key to be used for encrypting and decrypting
+  // the database. Values are of the form
+  // `projects/<project>/locations/<location>/keyRings/<key_ring>/cryptoKeys/<kms_key_name>`.
+  string kms_key_name = 2 [(google.api.resource_reference) = {
+    type: "cloudkms.googleapis.com/CryptoKey"
+  }];
+
+  // Specifies the KMS configuration for the one or more keys used to encrypt
+  // the database. Values are of the form
+  // `projects/<project>/locations/<location>/keyRings/<key_ring>/cryptoKeys/<kms_key_name>`.
+  //
+  // The keys referenced by kms_key_names must fully cover all
+  // regions of the database instance configuration. Some examples:
+  // * For single region database instance configs, specify a single regional
+  // location KMS key.
+  // * For multi-regional database instance configs of type GOOGLE_MANAGED,
+  // either specify a multi-regional location KMS key or multiple regional
+  // location KMS keys that cover all regions in the instance config.
+  // * For a database instance config of type USER_MANAGED, please specify only
+  // regional location KMS keys to cover each region in the instance config.
+  // Multi-regional location KMS keys are not supported for USER_MANAGED
+  // instance configs.
+  repeated string kms_key_names = 3 [(google.api.resource_reference) = {
+    type: "cloudkms.googleapis.com/CryptoKey"
+  }];
+}
+
+// Encryption information for a Cloud Spanner database or backup.
+message EncryptionInfo {
+  // Possible encryption types.
+  enum Type {
+    // Encryption type was not specified, though data at rest remains encrypted.
+    TYPE_UNSPECIFIED = 0;
+
+    // The data is encrypted at rest with a key that is
+    // fully managed by Google. No key version or status will be populated.
+    // This is the default state.
+    GOOGLE_DEFAULT_ENCRYPTION = 1;
+
+    // The data is encrypted at rest with a key that is
+    // managed by the customer. The active version of the key. `kms_key_version`
+    // will be populated, and `encryption_status` may be populated.
+    CUSTOMER_MANAGED_ENCRYPTION = 2;
+  }
+
+  // Output only. The type of encryption.
+  Type encryption_type = 3 [(google.api.field_behavior) = OUTPUT_ONLY];
+
+  // Output only. If present, the status of a recent encrypt/decrypt call on
+  // underlying data for this database or backup. Regardless of status, data is
+  // always encrypted at rest.
+  google.rpc.Status encryption_status = 4
+      [(google.api.field_behavior) = OUTPUT_ONLY];
+
+  // Output only. A Cloud KMS key version that is being used to protect the
+  // database or backup.
+  string kms_key_version = 2 [
+    (google.api.field_behavior) = OUTPUT_ONLY,
+    (google.api.resource_reference) = {
+      type: "cloudkms.googleapis.com/CryptoKeyVersion"
+    }
+  ];
+}
+
+// Indicates the dialect type of a database.
+enum DatabaseDialect {
+  // Default value. This value will create a database with the
+  // GOOGLE_STANDARD_SQL dialect.
+  DATABASE_DIALECT_UNSPECIFIED = 0;
+
+  // GoogleSQL supported SQL.
+  GOOGLE_STANDARD_SQL = 1;
+
+  // PostgreSQL supported SQL.
+  POSTGRESQL = 2;
+}