From 3b236df084cf9222c529a2890f90e3a4ff0f2dfd Mon Sep 17 00:00:00 2001 From: Google APIs Date: Wed, 14 Apr 2021 07:34:31 -0700 Subject: [PATCH] feat(spanner): add `progress` field to `UpdateDatabaseDdlMetadata` PiperOrigin-RevId: 368426665 --- google/spanner/admin/database/v1/backup.proto | 156 ++++++------- google/spanner/admin/database/v1/common.proto | 18 +- .../database/v1/spanner_database_admin.proto | 208 ++++++++---------- google/spanner/v1/BUILD.bazel | 1 + google/spanner/v1/commit_response.proto | 52 +++++ google/spanner/v1/spanner.proto | 35 +-- 6 files changed, 228 insertions(+), 242 deletions(-) create mode 100644 google/spanner/v1/commit_response.proto diff --git a/google/spanner/admin/database/v1/backup.proto b/google/spanner/admin/database/v1/backup.proto index 31fdb5326..ba57c1731 100644 --- a/google/spanner/admin/database/v1/backup.proto +++ b/google/spanner/admin/database/v1/backup.proto @@ -22,6 +22,7 @@ import "google/longrunning/operations.proto"; import "google/protobuf/field_mask.proto"; import "google/protobuf/timestamp.proto"; import "google/spanner/admin/database/v1/common.proto"; +import "google/api/annotations.proto"; option csharp_namespace = "Google.Cloud.Spanner.Admin.Database.V1"; option go_package = "google.golang.org/genproto/googleapis/spanner/admin/database/v1;database"; @@ -51,14 +52,14 @@ message Backup { 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 + // 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//instances//databases/`. string database = 2 [(google.api.resource_reference) = { - type: "spanner.googleapis.com/Database" - }]; + 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 @@ -66,8 +67,7 @@ message Backup { // backup. google.protobuf.Timestamp version_time = 9; - // Required for the - // [CreateBackup][google.spanner.admin.database.v1.DatabaseAdmin.CreateBackup] + // 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` @@ -75,11 +75,8 @@ message Backup { // 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. + // 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 @@ -93,12 +90,10 @@ message Backup { // `projects//instances/`. string name = 1; - // Output only. The time the - // [CreateBackup][google.spanner.admin.database.v1.DatabaseAdmin.CreateBackup] + // 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]; + 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]; @@ -121,12 +116,10 @@ message Backup { ]; // Output only. The encryption information for the backup. - EncryptionInfo encryption_info = 8 - [(google.api.field_behavior) = OUTPUT_ONLY]; + EncryptionInfo encryption_info = 8 [(google.api.field_behavior) = OUTPUT_ONLY]; } -// The request for -// [CreateBackup][google.spanner.admin.database.v1.DatabaseAdmin.CreateBackup]. +// 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 @@ -149,31 +142,29 @@ message CreateBackupRequest { // 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]; + // 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" } - ]; + 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" - }]; + type: "spanner.googleapis.com/Database" + }]; // The progress of the - // [CreateBackup][google.spanner.admin.database.v1.DatabaseAdmin.CreateBackup] - // operation. + // [CreateBackup][google.spanner.admin.database.v1.DatabaseAdmin.CreateBackup] operation. OperationProgress progress = 3; // The time at which cancellation of this operation was received. @@ -191,8 +182,7 @@ message CreateBackupMetadata { google.protobuf.Timestamp cancel_time = 4; } -// The request for -// [UpdateBackup][google.spanner.admin.database.v1.DatabaseAdmin.UpdateBackup]. +// 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. @@ -205,36 +195,36 @@ message UpdateBackupRequest { // 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]; + google.protobuf.FieldMask update_mask = 2 [(google.api.field_behavior) = REQUIRED]; } -// The request for -// [GetBackup][google.spanner.admin.database.v1.DatabaseAdmin.GetBackup]. +// The request for [GetBackup][google.spanner.admin.database.v1.DatabaseAdmin.GetBackup]. message GetBackupRequest { // Required. Name of the backup. // Values are of the form // `projects//instances//backups/`. string name = 1 [ (google.api.field_behavior) = REQUIRED, - (google.api.resource_reference) = { type: "spanner.googleapis.com/Backup" } + (google.api.resource_reference) = { + type: "spanner.googleapis.com/Backup" + } ]; } -// The request for -// [DeleteBackup][google.spanner.admin.database.v1.DatabaseAdmin.DeleteBackup]. +// 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//instances//backups/`. string name = 1 [ (google.api.field_behavior) = REQUIRED, - (google.api.resource_reference) = { type: "spanner.googleapis.com/Backup" } + (google.api.resource_reference) = { + type: "spanner.googleapis.com/Backup" + } ]; } -// The request for -// [ListBackups][google.spanner.admin.database.v1.DatabaseAdmin.ListBackups]. +// 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//instances/`. @@ -253,9 +243,7 @@ message ListBackupsRequest { // 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: + // The following fields in the [Backup][google.spanner.admin.database.v1.Backup] are eligible for filtering: // // * `name` // * `database` @@ -289,23 +277,21 @@ message ListBackupsRequest { 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`. + // [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]. +// 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. + // [ListBackups][google.spanner.admin.database.v1.DatabaseAdmin.ListBackups] call to fetch more + // of the matching backups. string next_page_token = 2; } @@ -335,9 +321,7 @@ message ListBackupOperationsRequest { // * `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 + // for [CreateBackupMetadata][google.spanner.admin.database.v1.CreateBackupMetadata] is // `type.googleapis.com/google.spanner.admin.database.v1.CreateBackupMetadata`. // * `metadata.` - any field in metadata.value. // * `error` - Error associated with the long-running operation. @@ -357,8 +341,7 @@ message ListBackupOperationsRequest { // `(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 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. @@ -370,9 +353,8 @@ message ListBackupOperationsRequest { // 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`. + // from a previous [ListBackupOperationsResponse][google.spanner.admin.database.v1.ListBackupOperationsResponse] to the + // same `parent` and with the same `filter`. string page_token = 4; } @@ -383,11 +365,11 @@ message ListBackupOperationsResponse { // 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. + // [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 @@ -399,26 +381,25 @@ message ListBackupOperationsResponse { // Information about a backup. message BackupInfo { // Name of the backup. - string backup = 1 [ - (google.api.resource_reference) = { type: "spanner.googleapis.com/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`. + // [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. + // 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" - }]; + type: "spanner.googleapis.com/Database" + }]; } // Encryption configuration for the backup to create. @@ -430,10 +411,9 @@ message CreateBackupEncryptionConfig { // 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. + // [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. @@ -449,8 +429,8 @@ message CreateBackupEncryptionConfig { // 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 + // [encryption_type][google.spanner.admin.database.v1.CreateBackupEncryptionConfig.encryption_type] is + // `CUSTOMER_MANAGED_ENCRYPTION`. Values are of the form // `projects//locations//keyRings//cryptoKeys/`. string kms_key_name = 2 [ (google.api.field_behavior) = OPTIONAL, diff --git a/google/spanner/admin/database/v1/common.proto b/google/spanner/admin/database/v1/common.proto index 24d7c2d08..29aabff0b 100644 --- a/google/spanner/admin/database/v1/common.proto +++ b/google/spanner/admin/database/v1/common.proto @@ -20,6 +20,7 @@ import "google/api/field_behavior.proto"; import "google/api/resource.proto"; import "google/protobuf/timestamp.proto"; import "google/rpc/status.proto"; +import "google/api/annotations.proto"; option csharp_namespace = "Google.Cloud.Spanner.Admin.Database.V1"; option go_package = "google.golang.org/genproto/googleapis/spanner/admin/database/v1;database"; @@ -58,8 +59,8 @@ message EncryptionConfig { // the database. Values are of the form // `projects//locations//keyRings//cryptoKeys/`. string kms_key_name = 2 [(google.api.resource_reference) = { - type: "cloudkms.googleapis.com/CryptoKey" - }]; + type: "cloudkms.googleapis.com/CryptoKey" + }]; } // Encryption information for a Cloud Spanner database or backup. @@ -83,14 +84,13 @@ message EncryptionInfo { // 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. 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. + // 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) = { diff --git a/google/spanner/admin/database/v1/spanner_database_admin.proto b/google/spanner/admin/database/v1/spanner_database_admin.proto index f09cf073b..668e8a046 100644 --- a/google/spanner/admin/database/v1/spanner_database_admin.proto +++ b/google/spanner/admin/database/v1/spanner_database_admin.proto @@ -65,11 +65,10 @@ service DatabaseAdmin { // have a name of the format `/operations/` and // can be used to track preparation of the database. The // [metadata][google.longrunning.Operation.metadata] field type is - // [CreateDatabaseMetadata][google.spanner.admin.database.v1.CreateDatabaseMetadata]. - // The [response][google.longrunning.Operation.response] field type is + // [CreateDatabaseMetadata][google.spanner.admin.database.v1.CreateDatabaseMetadata]. The + // [response][google.longrunning.Operation.response] field type is // [Database][google.spanner.admin.database.v1.Database], if successful. - rpc CreateDatabase(CreateDatabaseRequest) - returns (google.longrunning.Operation) { + rpc CreateDatabase(CreateDatabaseRequest) returns (google.longrunning.Operation) { option (google.api.http) = { post: "/v1/{parent=projects/*/instances/*}/databases" body: "*" @@ -95,10 +94,8 @@ service DatabaseAdmin { // the format `/operations/` and can be used to // track execution of the schema change(s). The // [metadata][google.longrunning.Operation.metadata] field type is - // [UpdateDatabaseDdlMetadata][google.spanner.admin.database.v1.UpdateDatabaseDdlMetadata]. - // The operation has no response. - rpc UpdateDatabaseDdl(UpdateDatabaseDdlRequest) - returns (google.longrunning.Operation) { + // [UpdateDatabaseDdlMetadata][google.spanner.admin.database.v1.UpdateDatabaseDdlMetadata]. The operation has no response. + rpc UpdateDatabaseDdl(UpdateDatabaseDdlRequest) returns (google.longrunning.Operation) { option (google.api.http) = { patch: "/v1/{database=projects/*/instances/*/databases/*}/ddl" body: "*" @@ -137,8 +134,7 @@ service DatabaseAdmin { // permission on [resource][google.iam.v1.SetIamPolicyRequest.resource]. // For backups, authorization requires `spanner.backups.setIamPolicy` // permission on [resource][google.iam.v1.SetIamPolicyRequest.resource]. - rpc SetIamPolicy(google.iam.v1.SetIamPolicyRequest) - returns (google.iam.v1.Policy) { + rpc SetIamPolicy(google.iam.v1.SetIamPolicyRequest) returns (google.iam.v1.Policy) { option (google.api.http) = { post: "/v1/{resource=projects/*/instances/*/databases/*}:setIamPolicy" body: "*" @@ -158,8 +154,7 @@ service DatabaseAdmin { // [resource][google.iam.v1.GetIamPolicyRequest.resource]. // For backups, authorization requires `spanner.backups.getIamPolicy` // permission on [resource][google.iam.v1.GetIamPolicyRequest.resource]. - rpc GetIamPolicy(google.iam.v1.GetIamPolicyRequest) - returns (google.iam.v1.Policy) { + rpc GetIamPolicy(google.iam.v1.GetIamPolicyRequest) returns (google.iam.v1.Policy) { option (google.api.http) = { post: "/v1/{resource=projects/*/instances/*/databases/*}:getIamPolicy" body: "*" @@ -181,8 +176,7 @@ service DatabaseAdmin { // Calling this method on a backup that does not exist will // result in a NOT_FOUND error if the user has // `spanner.backups.list` permission on the containing instance. - rpc TestIamPermissions(google.iam.v1.TestIamPermissionsRequest) - returns (google.iam.v1.TestIamPermissionsResponse) { + rpc TestIamPermissions(google.iam.v1.TestIamPermissionsRequest) returns (google.iam.v1.TestIamPermissionsResponse) { option (google.api.http) = { post: "/v1/{resource=projects/*/instances/*/databases/*}:testIamPermissions" body: "*" @@ -200,12 +194,12 @@ service DatabaseAdmin { // `projects//instances//backups//operations/` // and can be used to track creation of the backup. The // [metadata][google.longrunning.Operation.metadata] field type is - // [CreateBackupMetadata][google.spanner.admin.database.v1.CreateBackupMetadata]. - // The [response][google.longrunning.Operation.response] field type is - // [Backup][google.spanner.admin.database.v1.Backup], if successful. - // Cancelling the returned operation will stop the creation and delete the - // backup. There can be only one pending backup creation per database. Backup - // creation of different databases can run concurrently. + // [CreateBackupMetadata][google.spanner.admin.database.v1.CreateBackupMetadata]. The + // [response][google.longrunning.Operation.response] field type is + // [Backup][google.spanner.admin.database.v1.Backup], if successful. Cancelling the returned operation will stop the + // creation and delete the backup. + // There can be only one pending backup creation per database. Backup creation + // of different databases can run concurrently. rpc CreateBackup(CreateBackupRequest) returns (google.longrunning.Operation) { option (google.api.http) = { post: "/v1/{parent=projects/*/instances/*}/backups" @@ -218,8 +212,7 @@ service DatabaseAdmin { }; } - // Gets metadata on a pending or completed - // [Backup][google.spanner.admin.database.v1.Backup]. + // Gets metadata on a pending or completed [Backup][google.spanner.admin.database.v1.Backup]. rpc GetBackup(GetBackupRequest) returns (Backup) { option (google.api.http) = { get: "/v1/{name=projects/*/instances/*/backups/*}" @@ -227,8 +220,7 @@ service DatabaseAdmin { option (google.api.method_signature) = "name"; } - // Updates a pending or completed - // [Backup][google.spanner.admin.database.v1.Backup]. + // Updates a pending or completed [Backup][google.spanner.admin.database.v1.Backup]. rpc UpdateBackup(UpdateBackupRequest) returns (Backup) { option (google.api.http) = { patch: "/v1/{backup.name=projects/*/instances/*/backups/*}" @@ -237,8 +229,7 @@ service DatabaseAdmin { option (google.api.method_signature) = "backup,update_mask"; } - // Deletes a pending or completed - // [Backup][google.spanner.admin.database.v1.Backup]. + // Deletes a pending or completed [Backup][google.spanner.admin.database.v1.Backup]. rpc DeleteBackup(DeleteBackupRequest) returns (google.protobuf.Empty) { option (google.api.http) = { delete: "/v1/{name=projects/*/instances/*/backups/*}" @@ -273,8 +264,7 @@ service DatabaseAdmin { // Once the restore operation completes, a new restore operation can be // initiated, without waiting for the optimize operation associated with the // first restore to complete. - rpc RestoreDatabase(RestoreDatabaseRequest) - returns (google.longrunning.Operation) { + rpc RestoreDatabase(RestoreDatabaseRequest) returns (google.longrunning.Operation) { option (google.api.http) = { post: "/v1/{parent=projects/*/instances/*}/databases:restore" body: "*" @@ -294,8 +284,7 @@ service DatabaseAdmin { // `metadata.type_url` describes the type of the metadata. Operations returned // include those that have completed/failed/canceled within the last 7 days, // and pending operations. - rpc ListDatabaseOperations(ListDatabaseOperationsRequest) - returns (ListDatabaseOperationsResponse) { + rpc ListDatabaseOperations(ListDatabaseOperationsRequest) returns (ListDatabaseOperationsResponse) { option (google.api.http) = { get: "/v1/{parent=projects/*/instances/*}/databaseOperations" }; @@ -312,8 +301,7 @@ service DatabaseAdmin { // and pending operations. Operations returned are ordered by // `operation.metadata.value.progress.start_time` in descending order starting // from the most recently started operation. - rpc ListBackupOperations(ListBackupOperationsRequest) - returns (ListBackupOperationsResponse) { + rpc ListBackupOperations(ListBackupOperationsRequest) returns (ListBackupOperationsResponse) { option (google.api.http) = { get: "/v1/{parent=projects/*/instances/*}/backupOperations" }; @@ -375,8 +363,7 @@ message Database { State state = 2 [(google.api.field_behavior) = OUTPUT_ONLY]; // Output only. If exists, the time at which the database creation started. - google.protobuf.Timestamp create_time = 3 - [(google.api.field_behavior) = OUTPUT_ONLY]; + google.protobuf.Timestamp create_time = 3 [(google.api.field_behavior) = OUTPUT_ONLY]; // Output only. Applicable only for restored databases. Contains information // about the restore source. @@ -386,8 +373,7 @@ message Database { // field contains the encryption configuration for the database. // For databases that are using Google default or other types of encryption, // this field is empty. - EncryptionConfig encryption_config = 5 - [(google.api.field_behavior) = OUTPUT_ONLY]; + EncryptionConfig encryption_config = 5 [(google.api.field_behavior) = OUTPUT_ONLY]; // Output only. For databases that are using customer managed encryption, this // field contains the encryption information for the database, such as @@ -398,28 +384,24 @@ message Database { // // This field is propagated lazily from the backend. There might be a delay // from when a key version is being used and when it appears in this field. - repeated EncryptionInfo encryption_info = 8 - [(google.api.field_behavior) = OUTPUT_ONLY]; + repeated EncryptionInfo encryption_info = 8 [(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]; + // [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. This value is continuously updated by Cloud Spanner and becomes stale // the moment it is queried. If you are using this value to recover data, make // sure to account for the time from the moment when the value is queried to // the moment when you initiate the recovery. - google.protobuf.Timestamp earliest_version_time = 7 - [(google.api.field_behavior) = OUTPUT_ONLY]; + google.protobuf.Timestamp earliest_version_time = 7 [(google.api.field_behavior) = OUTPUT_ONLY]; } -// The request for -// [ListDatabases][google.spanner.admin.database.v1.DatabaseAdmin.ListDatabases]. +// The request for [ListDatabases][google.spanner.admin.database.v1.DatabaseAdmin.ListDatabases]. message ListDatabasesRequest { // Required. The instance whose databases should be listed. // Values are of the form `projects//instances/`. @@ -435,26 +417,23 @@ message ListDatabasesRequest { int32 page_size = 3; // If non-empty, `page_token` should contain a - // [next_page_token][google.spanner.admin.database.v1.ListDatabasesResponse.next_page_token] - // from a previous - // [ListDatabasesResponse][google.spanner.admin.database.v1.ListDatabasesResponse]. + // [next_page_token][google.spanner.admin.database.v1.ListDatabasesResponse.next_page_token] from a + // previous [ListDatabasesResponse][google.spanner.admin.database.v1.ListDatabasesResponse]. string page_token = 4; } -// The response for -// [ListDatabases][google.spanner.admin.database.v1.DatabaseAdmin.ListDatabases]. +// The response for [ListDatabases][google.spanner.admin.database.v1.DatabaseAdmin.ListDatabases]. message ListDatabasesResponse { // Databases that matched the request. repeated Database databases = 1; // `next_page_token` can be sent in a subsequent - // [ListDatabases][google.spanner.admin.database.v1.DatabaseAdmin.ListDatabases] - // call to fetch more of the matching databases. + // [ListDatabases][google.spanner.admin.database.v1.DatabaseAdmin.ListDatabases] call to fetch more + // of the matching databases. string next_page_token = 2; } -// The request for -// [CreateDatabase][google.spanner.admin.database.v1.DatabaseAdmin.CreateDatabase]. +// The request for [CreateDatabase][google.spanner.admin.database.v1.DatabaseAdmin.CreateDatabase]. message CreateDatabaseRequest { // Required. The name of the instance that will serve the new database. // Values are of the form `projects//instances/`. @@ -478,11 +457,10 @@ message CreateDatabaseRequest { // if there is an error in any statement, the database is not created. repeated string extra_statements = 3 [(google.api.field_behavior) = OPTIONAL]; - // Optional. The encryption configuration for the database. If this field is - // not specified, Cloud Spanner will encrypt/decrypt all data at rest using + // Optional. The encryption configuration for the database. If this field is not + // specified, Cloud Spanner will encrypt/decrypt all data at rest using // Google default encryption. - EncryptionConfig encryption_config = 4 - [(google.api.field_behavior) = OPTIONAL]; + EncryptionConfig encryption_config = 4 [(google.api.field_behavior) = OPTIONAL]; } // Metadata type for the operation returned by @@ -490,12 +468,11 @@ message CreateDatabaseRequest { message CreateDatabaseMetadata { // The database being created. string database = 1 [(google.api.resource_reference) = { - type: "spanner.googleapis.com/Database" - }]; + type: "spanner.googleapis.com/Database" + }]; } -// The request for -// [GetDatabase][google.spanner.admin.database.v1.DatabaseAdmin.GetDatabase]. +// The request for [GetDatabase][google.spanner.admin.database.v1.DatabaseAdmin.GetDatabase]. message GetDatabaseRequest { // Required. The name of the requested database. Values are of the form // `projects//instances//databases/`. @@ -521,8 +498,8 @@ message GetDatabaseRequest { // Each batch of statements is assigned a name which can be used with // the [Operations][google.longrunning.Operations] API to monitor // progress. See the -// [operation_id][google.spanner.admin.database.v1.UpdateDatabaseDdlRequest.operation_id] -// field for more details. +// [operation_id][google.spanner.admin.database.v1.UpdateDatabaseDdlRequest.operation_id] field for more +// details. message UpdateDatabaseDdlRequest { // Required. The database to update. string database = 1 [ @@ -542,20 +519,18 @@ message UpdateDatabaseDdlRequest { // // Specifying an explicit operation ID simplifies determining // whether the statements were executed in the event that the - // [UpdateDatabaseDdl][google.spanner.admin.database.v1.DatabaseAdmin.UpdateDatabaseDdl] - // call is replayed, or the return value is otherwise lost: the - // [database][google.spanner.admin.database.v1.UpdateDatabaseDdlRequest.database] - // and `operation_id` fields can be combined to form the + // [UpdateDatabaseDdl][google.spanner.admin.database.v1.DatabaseAdmin.UpdateDatabaseDdl] call is replayed, + // or the return value is otherwise lost: the [database][google.spanner.admin.database.v1.UpdateDatabaseDdlRequest.database] and + // `operation_id` fields can be combined to form the // [name][google.longrunning.Operation.name] of the resulting - // [longrunning.Operation][google.longrunning.Operation]: - // `/operations/`. + // [longrunning.Operation][google.longrunning.Operation]: `/operations/`. // // `operation_id` should be unique within the database, and must be // a valid identifier: `[a-z][a-z0-9_]*`. Note that // automatically-generated operation IDs always begin with an // underscore. If the named operation already exists, - // [UpdateDatabaseDdl][google.spanner.admin.database.v1.DatabaseAdmin.UpdateDatabaseDdl] - // returns `ALREADY_EXISTS`. + // [UpdateDatabaseDdl][google.spanner.admin.database.v1.DatabaseAdmin.UpdateDatabaseDdl] returns + // `ALREADY_EXISTS`. string operation_id = 3; } @@ -564,8 +539,8 @@ message UpdateDatabaseDdlRequest { message UpdateDatabaseDdlMetadata { // The database being modified. string database = 1 [(google.api.resource_reference) = { - type: "spanner.googleapis.com/Database" - }]; + type: "spanner.googleapis.com/Database" + }]; // For an update this list contains all the statements. For an // individual statement, this list contains only that statement. @@ -580,10 +555,19 @@ message UpdateDatabaseDdlMetadata { // due to resource constraints. When resources become available the operation // will resume and this field will be false again. bool throttled = 4 [(google.api.field_behavior) = OUTPUT_ONLY]; + + // The progress of the + // [UpdateDatabaseDdl][google.spanner.admin.database.v1.DatabaseAdmin.UpdateDatabaseDdl] operations. + // Currently, only index creation statements will have a continuously + // updating progress. + // For non-index creation statements, `progress[i]` will have start time + // and end time populated with commit timestamp of operation, + // as well as a progress of 100% once the operation has completed. + // `progress[i]` is the operation progress for `statements[i]`. + repeated OperationProgress progress = 5; } -// The request for -// [DropDatabase][google.spanner.admin.database.v1.DatabaseAdmin.DropDatabase]. +// The request for [DropDatabase][google.spanner.admin.database.v1.DatabaseAdmin.DropDatabase]. message DropDatabaseRequest { // Required. The database to be dropped. string database = 1 [ @@ -594,8 +578,7 @@ message DropDatabaseRequest { ]; } -// The request for -// [GetDatabaseDdl][google.spanner.admin.database.v1.DatabaseAdmin.GetDatabaseDdl]. +// 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 @@ -608,8 +591,7 @@ message GetDatabaseDdlRequest { ]; } -// The response for -// [GetDatabaseDdl][google.spanner.admin.database.v1.DatabaseAdmin.GetDatabaseDdl]. +// The response for [GetDatabaseDdl][google.spanner.admin.database.v1.DatabaseAdmin.GetDatabaseDdl]. message GetDatabaseDdlResponse { // A list of formatted DDL statements defining the schema of the database // specified in the request. @@ -642,9 +624,7 @@ message ListDatabaseOperationsRequest { // * `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 - // [RestoreDatabaseMetadata][google.spanner.admin.database.v1.RestoreDatabaseMetadata] - // is + // for [RestoreDatabaseMetadata][google.spanner.admin.database.v1.RestoreDatabaseMetadata] is // `type.googleapis.com/google.spanner.admin.database.v1.RestoreDatabaseMetadata`. // * `metadata.` - any field in metadata.value. // * `error` - Error associated with the long-running operation. @@ -664,8 +644,7 @@ message ListDatabaseOperationsRequest { // `(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 operation's metadata type is [RestoreDatabaseMetadata][google.spanner.admin.database.v1.RestoreDatabaseMetadata]. // * The database is restored from a backup. // * The backup name contains "backup_howl". // * The restored database's name contains "restored_howl". @@ -679,9 +658,8 @@ message ListDatabaseOperationsRequest { // If non-empty, `page_token` should contain a // [next_page_token][google.spanner.admin.database.v1.ListDatabaseOperationsResponse.next_page_token] - // from a previous - // [ListDatabaseOperationsResponse][google.spanner.admin.database.v1.ListDatabaseOperationsResponse] - // to the same `parent` and with the same `filter`. + // from a previous [ListDatabaseOperationsResponse][google.spanner.admin.database.v1.ListDatabaseOperationsResponse] to the + // same `parent` and with the same `filter`. string page_token = 4; } @@ -727,18 +705,17 @@ message RestoreDatabaseRequest { // Name of the backup from which to restore. Values are of the form // `projects//instances//backups/`. string backup = 3 [(google.api.resource_reference) = { - type: "spanner.googleapis.com/Backup" - }]; + type: "spanner.googleapis.com/Backup" + }]; } - // Optional. An encryption configuration describing the encryption type and - // key resources in Cloud KMS used to encrypt/decrypt the database to restore - // to. If this field is not specified, the restored database will use the same - // encryption configuration as the backup by default, namely - // [encryption_type][google.spanner.admin.database.v1.RestoreDatabaseEncryptionConfig.encryption_type] - // = `USE_CONFIG_DEFAULT_OR_BACKUP_ENCRYPTION`. - RestoreDatabaseEncryptionConfig encryption_config = 4 - [(google.api.field_behavior) = OPTIONAL]; + // Optional. An encryption configuration describing the encryption type and key + // resources in Cloud KMS used to encrypt/decrypt the database to restore to. + // If this field is not specified, the restored database will use + // the same encryption configuration as the backup by default, namely + // [encryption_type][google.spanner.admin.database.v1.RestoreDatabaseEncryptionConfig.encryption_type] = + // `USE_CONFIG_DEFAULT_OR_BACKUP_ENCRYPTION`. + RestoreDatabaseEncryptionConfig encryption_config = 4 [(google.api.field_behavior) = OPTIONAL]; } // Encryption configuration for the restored database. @@ -749,8 +726,7 @@ message RestoreDatabaseEncryptionConfig { ENCRYPTION_TYPE_UNSPECIFIED = 0; // This is the default option when - // [encryption_config][google.spanner.admin.database.v1.RestoreDatabaseEncryptionConfig] - // is not specified. + // [encryption_config][google.spanner.admin.database.v1.RestoreDatabaseEncryptionConfig] is not specified. USE_CONFIG_DEFAULT_OR_BACKUP_ENCRYPTION = 1; // Use Google default encryption. @@ -764,10 +740,10 @@ message RestoreDatabaseEncryptionConfig { // Required. The encryption type of the restored database. EncryptionType encryption_type = 1 [(google.api.field_behavior) = REQUIRED]; - // Optional. The Cloud KMS key that will be used to encrypt/decrypt the - // restored database. This field should be set only when - // [encryption_type][google.spanner.admin.database.v1.RestoreDatabaseEncryptionConfig.encryption_type] - // is `CUSTOMER_MANAGED_ENCRYPTION`. Values are of the form + // Optional. The Cloud KMS key that will be used to encrypt/decrypt the restored + // database. This field should be set only when + // [encryption_type][google.spanner.admin.database.v1.RestoreDatabaseEncryptionConfig.encryption_type] is + // `CUSTOMER_MANAGED_ENCRYPTION`. Values are of the form // `projects//locations//keyRings//cryptoKeys/`. string kms_key_name = 2 [ (google.api.field_behavior) = OPTIONAL, @@ -782,15 +758,14 @@ message RestoreDatabaseEncryptionConfig { message RestoreDatabaseMetadata { // Name of the database being created and restored to. string name = 1 [(google.api.resource_reference) = { - type: "spanner.googleapis.com/Database" - }]; + type: "spanner.googleapis.com/Database" + }]; // The type of the restore source. RestoreSourceType source_type = 2; // Information about the source used to restore the database, as specified by - // `source` in - // [RestoreDatabaseRequest][google.spanner.admin.database.v1.RestoreDatabaseRequest]. + // `source` in [RestoreDatabaseRequest][google.spanner.admin.database.v1.RestoreDatabaseRequest]. oneof source_info { // Information about the backup used to restore the database. BackupInfo backup_info = 3; @@ -811,8 +786,7 @@ message RestoreDatabaseMetadata { // 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.rpc.Status.code][google.rpc.Status.code] of 1, corresponding to `Code.CANCELLED`. google.protobuf.Timestamp cancel_time = 5; // If exists, the name of the long-running operation that will be used to @@ -822,10 +796,10 @@ message RestoreDatabaseMetadata { // `projects//instances//databases//operations/` // where the is the name of database being created and restored to. // The metadata type of the long-running operation is - // [OptimizeRestoredDatabaseMetadata][google.spanner.admin.database.v1.OptimizeRestoredDatabaseMetadata]. - // This long-running operation will be automatically created by the system - // after the RestoreDatabase long-running operation completes successfully. - // This operation will not be created if the restore was not successful. + // [OptimizeRestoredDatabaseMetadata][google.spanner.admin.database.v1.OptimizeRestoredDatabaseMetadata]. This long-running operation will be + // automatically created by the system after the RestoreDatabase long-running + // operation completes successfully. This operation will not be created if the + // restore was not successful. string optimize_database_operation_name = 6; } @@ -836,8 +810,8 @@ message RestoreDatabaseMetadata { message OptimizeRestoredDatabaseMetadata { // Name of the restored database being optimized. string name = 1 [(google.api.resource_reference) = { - type: "spanner.googleapis.com/Database" - }]; + type: "spanner.googleapis.com/Database" + }]; // The progress of the post-restore optimizations. OperationProgress progress = 2; diff --git a/google/spanner/v1/BUILD.bazel b/google/spanner/v1/BUILD.bazel index 214a7ad08..c450d7e06 100644 --- a/google/spanner/v1/BUILD.bazel +++ b/google/spanner/v1/BUILD.bazel @@ -12,6 +12,7 @@ load("@com_google_googleapis_imports//:imports.bzl", "proto_library_with_info") proto_library( name = "spanner_proto", srcs = [ + "commit_response.proto", "keys.proto", "mutation.proto", "query_plan.proto", diff --git a/google/spanner/v1/commit_response.proto b/google/spanner/v1/commit_response.proto new file mode 100644 index 000000000..1c2df7260 --- /dev/null +++ b/google/spanner/v1/commit_response.proto @@ -0,0 +1,52 @@ +// 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.v1; + +import "google/protobuf/duration.proto"; +import "google/protobuf/timestamp.proto"; +import "google/api/annotations.proto"; + +option csharp_namespace = "Google.Cloud.Spanner.V1"; +option go_package = "google.golang.org/genproto/googleapis/spanner/v1;spanner"; +option java_multiple_files = true; +option java_outer_classname = "CommitResponseProto"; +option java_package = "com.google.spanner.v1"; +option php_namespace = "Google\\Cloud\\Spanner\\V1"; +option ruby_package = "Google::Cloud::Spanner::V1"; + +// The response for [Commit][google.spanner.v1.Spanner.Commit]. +message CommitResponse { + // Additional statistics about a commit. + message CommitStats { + // The total number of mutations for the transaction. Knowing the + // `mutation_count` value can help you maximize the number of mutations + // in a transaction and minimize the number of API round trips. You can + // also monitor this value to prevent transactions from exceeding the system + // [limit](http://cloud.google.com/spanner/quotas#limits_for_creating_reading_updating_and_deleting_data). + // If the number of mutations exceeds the limit, the server returns + // [INVALID_ARGUMENT](http://cloud.google.com/spanner/docs/reference/rest/v1/Code#ENUM_VALUES.INVALID_ARGUMENT). + int64 mutation_count = 1; + } + + // The Cloud Spanner timestamp at which the transaction committed. + google.protobuf.Timestamp commit_timestamp = 1; + + // The statistics about this Commit. Not returned by default. + // For more information, see + // [CommitRequest.return_commit_stats][google.spanner.v1.CommitRequest.return_commit_stats]. + CommitStats commit_stats = 2; +} diff --git a/google/spanner/v1/spanner.proto b/google/spanner/v1/spanner.proto index c43622722..176123f8d 100644 --- a/google/spanner/v1/spanner.proto +++ b/google/spanner/v1/spanner.proto @@ -16,11 +16,11 @@ syntax = "proto3"; package google.spanner.v1; +import public "google/spanner/v1/commit_response.proto"; import "google/api/annotations.proto"; import "google/api/client.proto"; import "google/api/field_behavior.proto"; import "google/api/resource.proto"; -import "google/protobuf/duration.proto"; import "google/protobuf/empty.proto"; import "google/protobuf/struct.proto"; import "google/protobuf/timestamp.proto"; @@ -466,8 +466,9 @@ message RequestOptions { // that belongs to a transaction. // This field is ignored for requests where it's not applicable (e.g. // CommitRequest). - // `request_tag` must be a valid identifier of the form: - // `[a-zA-Z][a-zA-Z0-9_\-]` between 2 and 64 characters in length + // Legal characters for `request_tag` values are all printable characters + // (ASCII 32 - 126) and the length of a request_tag is limited to 50 + // characters. Values that exceed this limit are truncated. string request_tag = 2; // A tag used for statistics collection about this transaction. @@ -477,8 +478,9 @@ message RequestOptions { // to the same transaction. // If this request doesn’t belong to any transaction, transaction_tag will be // ignored. - // `transaction_tag` must be a valid identifier of the format: - // `[a-zA-Z][a-zA-Z0-9_\-]{0,49}` + // Legal characters for `transaction_tag` values are all printable characters + // (ASCII 32 - 126) and the length of a transaction_tag is limited to 50 + // characters. Values that exceed this limit are truncated. string transaction_tag = 3; } @@ -1006,29 +1008,6 @@ message CommitRequest { RequestOptions request_options = 6; } -// The response for [Commit][google.spanner.v1.Spanner.Commit]. -message CommitResponse { - // Additional statistics about a commit. - message CommitStats { - // The total number of mutations for the transaction. Knowing the - // `mutation_count` value can help you maximize the number of mutations - // in a transaction and minimize the number of API round trips. You can - // also monitor this value to prevent transactions from exceeding the system - // [limit](http://cloud.google.com/spanner/quotas#limits_for_creating_reading_updating_and_deleting_data). - // If the number of mutations exceeds the limit, the server returns - // [INVALID_ARGUMENT](http://cloud.google.com/spanner/docs/reference/rest/v1/Code#ENUM_VALUES.INVALID_ARGUMENT). - int64 mutation_count = 1; - } - - // The Cloud Spanner timestamp at which the transaction committed. - google.protobuf.Timestamp commit_timestamp = 1; - - // The statistics about this Commit. Not returned by default. - // For more information, see - // [CommitRequest.return_commit_stats][google.spanner.v1.CommitRequest.return_commit_stats]. - CommitStats commit_stats = 2; -} - // The request for [Rollback][google.spanner.v1.Spanner.Rollback]. message RollbackRequest { // Required. The session in which the transaction to roll back is running.