diff --git a/google/cloud/spanner_admin_database_v1/proto/backup.proto b/google/cloud/spanner_admin_database_v1/proto/backup.proto deleted file mode 100644 index 31fdb5326c..0000000000 --- a/google/cloud/spanner_admin_database_v1/proto/backup.proto +++ /dev/null @@ -1,461 +0,0 @@ -// 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//instances//databases/`. - 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//instances//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//instances/`. - 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//instances//databases/`. - // 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//instances/`. - 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//instances//backups/`. - 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//instances//backups/`. - 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//instances//backups/`. - 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//instances/`. - 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//instances/`. - 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.` - any field in metadata.value. - // * `error` - Error associated with the long-running operation. - // * `response.@type` - the type of response. - // * `response.` - 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//locations//keyRings//cryptoKeys/`. - string kms_key_name = 2 [ - (google.api.field_behavior) = OPTIONAL, - (google.api.resource_reference) = { - type: "cloudkms.googleapis.com/CryptoKey" - } - ]; -} diff --git a/google/cloud/spanner_admin_database_v1/proto/common.proto b/google/cloud/spanner_admin_database_v1/proto/common.proto deleted file mode 100644 index 24d7c2d080..0000000000 --- a/google/cloud/spanner_admin_database_v1/proto/common.proto +++ /dev/null @@ -1,100 +0,0 @@ -// 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/protobuf/timestamp.proto"; -import "google/rpc/status.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 = "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//locations//keyRings//cryptoKeys/`. - string kms_key_name = 2 [(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" - } - ]; -} diff --git a/google/cloud/spanner_admin_database_v1/proto/spanner_database_admin.proto b/google/cloud/spanner_admin_database_v1/proto/spanner_database_admin.proto deleted file mode 100644 index f09cf073b2..0000000000 --- a/google/cloud/spanner_admin_database_v1/proto/spanner_database_admin.proto +++ /dev/null @@ -1,853 +0,0 @@ -// 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/annotations.proto"; -import "google/api/client.proto"; -import "google/api/field_behavior.proto"; -import "google/api/resource.proto"; -import "google/iam/v1/iam_policy.proto"; -import "google/iam/v1/policy.proto"; -import "google/longrunning/operations.proto"; -import "google/protobuf/empty.proto"; -import "google/protobuf/timestamp.proto"; -import "google/spanner/admin/database/v1/backup.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 = "SpannerDatabaseAdminProto"; -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: "spanner.googleapis.com/Instance" - pattern: "projects/{project}/instances/{instance}" -}; - -// Cloud Spanner Database Admin API -// -// The Cloud Spanner Database Admin API can be used to create, drop, and -// list databases. It also enables updating the schema of pre-existing -// databases. It can be also used to create, delete and list backups for a -// database and to restore from an existing backup. -service DatabaseAdmin { - option (google.api.default_host) = "spanner.googleapis.com"; - option (google.api.oauth_scopes) = - "https://www.googleapis.com/auth/cloud-platform," - "https://www.googleapis.com/auth/spanner.admin"; - - // Lists Cloud Spanner databases. - rpc ListDatabases(ListDatabasesRequest) returns (ListDatabasesResponse) { - option (google.api.http) = { - get: "/v1/{parent=projects/*/instances/*}/databases" - }; - option (google.api.method_signature) = "parent"; - } - - // Creates a new Cloud Spanner database and starts to prepare it for serving. - // The returned [long-running operation][google.longrunning.Operation] will - // 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 - // [Database][google.spanner.admin.database.v1.Database], if successful. - rpc CreateDatabase(CreateDatabaseRequest) - returns (google.longrunning.Operation) { - option (google.api.http) = { - post: "/v1/{parent=projects/*/instances/*}/databases" - body: "*" - }; - option (google.api.method_signature) = "parent,create_statement"; - option (google.longrunning.operation_info) = { - response_type: "google.spanner.admin.database.v1.Database" - metadata_type: "google.spanner.admin.database.v1.CreateDatabaseMetadata" - }; - } - - // Gets the state of a Cloud Spanner database. - rpc GetDatabase(GetDatabaseRequest) returns (Database) { - option (google.api.http) = { - get: "/v1/{name=projects/*/instances/*/databases/*}" - }; - option (google.api.method_signature) = "name"; - } - - // Updates the schema of a Cloud Spanner database by - // creating/altering/dropping tables, columns, indexes, etc. The returned - // [long-running operation][google.longrunning.Operation] will have a name of - // 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) { - option (google.api.http) = { - patch: "/v1/{database=projects/*/instances/*/databases/*}/ddl" - body: "*" - }; - option (google.api.method_signature) = "database,statements"; - option (google.longrunning.operation_info) = { - response_type: "google.protobuf.Empty" - metadata_type: "google.spanner.admin.database.v1.UpdateDatabaseDdlMetadata" - }; - } - - // Drops (aka deletes) a Cloud Spanner database. - // Completed backups for the database will be retained according to their - // `expire_time`. - rpc DropDatabase(DropDatabaseRequest) returns (google.protobuf.Empty) { - option (google.api.http) = { - delete: "/v1/{database=projects/*/instances/*/databases/*}" - }; - option (google.api.method_signature) = "database"; - } - - // Returns the schema of a Cloud Spanner database as a list of formatted - // DDL statements. This method does not show pending schema updates, those may - // be queried using the [Operations][google.longrunning.Operations] API. - rpc GetDatabaseDdl(GetDatabaseDdlRequest) returns (GetDatabaseDdlResponse) { - option (google.api.http) = { - get: "/v1/{database=projects/*/instances/*/databases/*}/ddl" - }; - option (google.api.method_signature) = "database"; - } - - // Sets the access control policy on a database or backup resource. - // Replaces any existing policy. - // - // Authorization requires `spanner.databases.setIamPolicy` - // 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) { - option (google.api.http) = { - post: "/v1/{resource=projects/*/instances/*/databases/*}:setIamPolicy" - body: "*" - additional_bindings { - post: "/v1/{resource=projects/*/instances/*/backups/*}:setIamPolicy" - body: "*" - } - }; - option (google.api.method_signature) = "resource,policy"; - } - - // Gets the access control policy for a database or backup resource. - // Returns an empty policy if a database or backup exists but does not have a - // policy set. - // - // Authorization requires `spanner.databases.getIamPolicy` permission on - // [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) { - option (google.api.http) = { - post: "/v1/{resource=projects/*/instances/*/databases/*}:getIamPolicy" - body: "*" - additional_bindings { - post: "/v1/{resource=projects/*/instances/*/backups/*}:getIamPolicy" - body: "*" - } - }; - option (google.api.method_signature) = "resource"; - } - - // Returns permissions that the caller has on the specified database or backup - // resource. - // - // Attempting this RPC on a non-existent Cloud Spanner database will - // result in a NOT_FOUND error if the user has - // `spanner.databases.list` permission on the containing Cloud - // Spanner instance. Otherwise returns an empty set of permissions. - // 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) { - option (google.api.http) = { - post: "/v1/{resource=projects/*/instances/*/databases/*}:testIamPermissions" - body: "*" - additional_bindings { - post: "/v1/{resource=projects/*/instances/*/backups/*}:testIamPermissions" - body: "*" - } - }; - option (google.api.method_signature) = "resource,permissions"; - } - - // Starts creating a new Cloud Spanner Backup. - // The returned backup [long-running operation][google.longrunning.Operation] - // will have a name of the format - // `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. - rpc CreateBackup(CreateBackupRequest) returns (google.longrunning.Operation) { - option (google.api.http) = { - post: "/v1/{parent=projects/*/instances/*}/backups" - body: "backup" - }; - option (google.api.method_signature) = "parent,backup,backup_id"; - option (google.longrunning.operation_info) = { - response_type: "google.spanner.admin.database.v1.Backup" - metadata_type: "google.spanner.admin.database.v1.CreateBackupMetadata" - }; - } - - // 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/*}" - }; - option (google.api.method_signature) = "name"; - } - - // 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/*}" - body: "backup" - }; - option (google.api.method_signature) = "backup,update_mask"; - } - - // 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/*}" - }; - option (google.api.method_signature) = "name"; - } - - // Lists completed and pending backups. - // Backups returned are ordered by `create_time` in descending order, - // starting from the most recent `create_time`. - rpc ListBackups(ListBackupsRequest) returns (ListBackupsResponse) { - option (google.api.http) = { - get: "/v1/{parent=projects/*/instances/*}/backups" - }; - option (google.api.method_signature) = "parent"; - } - - // Create a new database by restoring from a completed backup. The new - // database must be in the same project and in an instance with the same - // instance configuration as the instance containing - // the backup. The returned database [long-running - // operation][google.longrunning.Operation] has a name of the format - // `projects//instances//databases//operations/`, - // and can be used to track the progress of the operation, and to cancel it. - // The [metadata][google.longrunning.Operation.metadata] field type is - // [RestoreDatabaseMetadata][google.spanner.admin.database.v1.RestoreDatabaseMetadata]. - // The [response][google.longrunning.Operation.response] type - // is [Database][google.spanner.admin.database.v1.Database], if - // successful. Cancelling the returned operation will stop the restore and - // delete the database. - // There can be only one database being restored into an instance at a time. - // 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) { - option (google.api.http) = { - post: "/v1/{parent=projects/*/instances/*}/databases:restore" - body: "*" - }; - option (google.api.method_signature) = "parent,database_id,backup"; - option (google.longrunning.operation_info) = { - response_type: "google.spanner.admin.database.v1.Database" - metadata_type: "google.spanner.admin.database.v1.RestoreDatabaseMetadata" - }; - } - - // Lists database [longrunning-operations][google.longrunning.Operation]. - // A database operation has a name of the form - // `projects//instances//databases//operations/`. - // The long-running operation - // [metadata][google.longrunning.Operation.metadata] field type - // `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) { - option (google.api.http) = { - get: "/v1/{parent=projects/*/instances/*}/databaseOperations" - }; - option (google.api.method_signature) = "parent"; - } - - // Lists the backup [long-running operations][google.longrunning.Operation] in - // the given instance. A backup operation has a name of the form - // `projects//instances//backups//operations/`. - // The long-running operation - // [metadata][google.longrunning.Operation.metadata] field type - // `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. 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) { - option (google.api.http) = { - get: "/v1/{parent=projects/*/instances/*}/backupOperations" - }; - option (google.api.method_signature) = "parent"; - } -} - -// Information about the database restore. -message RestoreInfo { - // The type of the restore source. - RestoreSourceType source_type = 1; - - // Information about the source used to restore the database. - oneof source_info { - // Information about the backup used to restore the database. The backup - // may no longer exist. - BackupInfo backup_info = 2; - } -} - -// A Cloud Spanner database. -message Database { - option (google.api.resource) = { - type: "spanner.googleapis.com/Database" - pattern: "projects/{project}/instances/{instance}/databases/{database}" - }; - - // Indicates the current state of the database. - enum State { - // Not specified. - STATE_UNSPECIFIED = 0; - - // The database is still being created. Operations on the database may fail - // with `FAILED_PRECONDITION` in this state. - CREATING = 1; - - // The database is fully created and ready for use. - READY = 2; - - // The database is fully created and ready for use, but is still - // being optimized for performance and cannot handle full load. - // - // In this state, the database still references the backup - // it was restore from, preventing the backup - // from being deleted. When optimizations are complete, the full performance - // of the database will be restored, and the database will transition to - // `READY` state. - READY_OPTIMIZING = 3; - } - - // Required. The name of the database. Values are of the form - // `projects//instances//databases/`, - // where `` is as specified in the `CREATE DATABASE` - // statement. This name can be passed to other API methods to - // identify the database. - string name = 1 [(google.api.field_behavior) = REQUIRED]; - - // Output only. The current database state. - 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]; - - // 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. For databases that are using customer managed encryption, this - // 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]; - - // Output only. For databases that are using customer managed encryption, this - // field contains the encryption information for the database, such as - // encryption state and the Cloud KMS key versions that are in use. - // - // For databases that are using Google default or other types of encryption, - // this field is empty. - // - // 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]; - - // 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. 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]; -} - -// 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/`. - string parent = 1 [ - (google.api.field_behavior) = REQUIRED, - (google.api.resource_reference) = { - type: "spanner.googleapis.com/Instance" - } - ]; - - // Number of databases 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.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]. -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. - string next_page_token = 2; -} - -// 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/`. - string parent = 1 [ - (google.api.field_behavior) = REQUIRED, - (google.api.resource_reference) = { - type: "spanner.googleapis.com/Instance" - } - ]; - - // Required. A `CREATE DATABASE` statement, which specifies the ID of the - // new database. The database ID must conform to the regular expression - // `[a-z][a-z0-9_\-]*[a-z0-9]` and be between 2 and 30 characters in length. - // If the database ID is a reserved word or if it contains a hyphen, the - // database ID must be enclosed in backticks (`` ` ``). - string create_statement = 2 [(google.api.field_behavior) = REQUIRED]; - - // Optional. A list of DDL statements to run inside the newly created - // database. Statements can create tables, indexes, etc. These - // statements execute atomically with the creation of the database: - // 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 - // Google default encryption. - EncryptionConfig encryption_config = 4 - [(google.api.field_behavior) = OPTIONAL]; -} - -// Metadata type for the operation returned by -// [CreateDatabase][google.spanner.admin.database.v1.DatabaseAdmin.CreateDatabase]. -message CreateDatabaseMetadata { - // The database being created. - string database = 1 [(google.api.resource_reference) = { - type: "spanner.googleapis.com/Database" - }]; -} - -// 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/`. - string name = 1 [ - (google.api.field_behavior) = REQUIRED, - (google.api.resource_reference) = { - type: "spanner.googleapis.com/Database" - } - ]; -} - -// Enqueues the given DDL statements to be applied, in order but not -// necessarily all at once, to the database schema at some point (or -// points) in the future. The server checks that the statements -// are executable (syntactically valid, name tables that exist, etc.) -// before enqueueing them, but they may still fail upon -// later execution (e.g., if a statement from another batch of -// statements is applied first and it conflicts in some way, or if -// there is some data-related problem like a `NULL` value in a column to -// which `NOT NULL` would be added). If a statement fails, all -// subsequent statements in the batch are automatically cancelled. -// -// 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. -message UpdateDatabaseDdlRequest { - // Required. The database to update. - string database = 1 [ - (google.api.field_behavior) = REQUIRED, - (google.api.resource_reference) = { - type: "spanner.googleapis.com/Database" - } - ]; - - // Required. DDL statements to be applied to the database. - repeated string statements = 2 [(google.api.field_behavior) = REQUIRED]; - - // If empty, the new update request is assigned an - // automatically-generated operation ID. Otherwise, `operation_id` - // is used to construct the name of the resulting - // [Operation][google.longrunning.Operation]. - // - // 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 - // [name][google.longrunning.Operation.name] of the resulting - // [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`. - string operation_id = 3; -} - -// Metadata type for the operation returned by -// [UpdateDatabaseDdl][google.spanner.admin.database.v1.DatabaseAdmin.UpdateDatabaseDdl]. -message UpdateDatabaseDdlMetadata { - // The database being modified. - string database = 1 [(google.api.resource_reference) = { - type: "spanner.googleapis.com/Database" - }]; - - // For an update this list contains all the statements. For an - // individual statement, this list contains only that statement. - repeated string statements = 2; - - // Reports the commit timestamps of all statements that have - // succeeded so far, where `commit_timestamps[i]` is the commit - // timestamp for the statement `statements[i]`. - repeated google.protobuf.Timestamp commit_timestamps = 3; - - // Output only. When true, indicates that the operation is throttled e.g - // 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 request for -// [DropDatabase][google.spanner.admin.database.v1.DatabaseAdmin.DropDatabase]. -message DropDatabaseRequest { - // Required. The database to be dropped. - string database = 1 [ - (google.api.field_behavior) = REQUIRED, - (google.api.resource_reference) = { - type: "spanner.googleapis.com/Database" - } - ]; -} - -// 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//instances//databases/` - string database = 1 [ - (google.api.field_behavior) = REQUIRED, - (google.api.resource_reference) = { - type: "spanner.googleapis.com/Database" - } - ]; -} - -// 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. - repeated string statements = 1; -} - -// The request for -// [ListDatabaseOperations][google.spanner.admin.database.v1.DatabaseAdmin.ListDatabaseOperations]. -message ListDatabaseOperationsRequest { - // Required. The instance of the database operations. - // Values are of the form `projects//instances/`. - 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 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 - // [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. - // * `response.@type` - the type of response. - // * `response.` - any field in response.value. - // - // You can combine multiple expressions by enclosing each expression in - // parentheses. By default, expressions are combined with AND logic. However, - // you can specify AND, OR, and NOT logic explicitly. - // - // Here are a few examples: - // - // * `done:true` - The operation is complete. - // * `(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. - // * The backup name contains "backup_howl". - // * The restored database's name contains "restored_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.ListDatabaseOperationsResponse.next_page_token] - // from a previous - // [ListDatabaseOperationsResponse][google.spanner.admin.database.v1.ListDatabaseOperationsResponse] - // to the same `parent` and with the same `filter`. - string page_token = 4; -} - -// The response for -// [ListDatabaseOperations][google.spanner.admin.database.v1.DatabaseAdmin.ListDatabaseOperations]. -message ListDatabaseOperationsResponse { - // The list of matching database [long-running - // operations][google.longrunning.Operation]. Each operation's name will be - // prefixed by the database's name. The operation's - // [metadata][google.longrunning.Operation.metadata] field type - // `metadata.type_url` describes the type of the metadata. - repeated google.longrunning.Operation operations = 1; - - // `next_page_token` can be sent in a subsequent - // [ListDatabaseOperations][google.spanner.admin.database.v1.DatabaseAdmin.ListDatabaseOperations] - // call to fetch more of the matching metadata. - string next_page_token = 2; -} - -// The request for -// [RestoreDatabase][google.spanner.admin.database.v1.DatabaseAdmin.RestoreDatabase]. -message RestoreDatabaseRequest { - // Required. The name of the instance in which to create the - // restored database. This instance must be in the same project and - // have the same instance configuration as the instance containing - // the source backup. Values are of the form - // `projects//instances/`. - string parent = 1 [ - (google.api.field_behavior) = REQUIRED, - (google.api.resource_reference) = { - type: "spanner.googleapis.com/Instance" - } - ]; - - // Required. The id of the database to create and restore to. This - // database must not already exist. The `database_id` appended to - // `parent` forms the full database name of the form - // `projects//instances//databases/`. - string database_id = 2 [(google.api.field_behavior) = REQUIRED]; - - // Required. The source from which to restore. - oneof source { - // 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" - }]; - } - - // 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. -message RestoreDatabaseEncryptionConfig { - // Encryption types for the database to be restored. - enum EncryptionType { - // Unspecified. Do not use. - ENCRYPTION_TYPE_UNSPECIFIED = 0; - - // This is the default option when - // [encryption_config][google.spanner.admin.database.v1.RestoreDatabaseEncryptionConfig] - // is not specified. - USE_CONFIG_DEFAULT_OR_BACKUP_ENCRYPTION = 1; - - // Use Google default encryption. - GOOGLE_DEFAULT_ENCRYPTION = 2; - - // Use customer managed encryption. If specified, `kms_key_name` must - // must contain a valid Cloud KMS key. - CUSTOMER_MANAGED_ENCRYPTION = 3; - } - - // 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 - // `projects//locations//keyRings//cryptoKeys/`. - string kms_key_name = 2 [ - (google.api.field_behavior) = OPTIONAL, - (google.api.resource_reference) = { - type: "cloudkms.googleapis.com/CryptoKey" - } - ]; -} - -// Metadata type for the long-running operation returned by -// [RestoreDatabase][google.spanner.admin.database.v1.DatabaseAdmin.RestoreDatabase]. -message RestoreDatabaseMetadata { - // Name of the database being created and restored to. - string name = 1 [(google.api.resource_reference) = { - 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]. - oneof source_info { - // Information about the backup used to restore the database. - BackupInfo backup_info = 3; - } - - // The progress of the - // [RestoreDatabase][google.spanner.admin.database.v1.DatabaseAdmin.RestoreDatabase] - // operation. - OperationProgress progress = 4; - - // 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 = 5; - - // If exists, the name of the long-running operation that will be used to - // track the post-restore optimization process to optimize the performance of - // the restored database, and remove the dependency on the restore source. - // The name is of the form - // `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. - string optimize_database_operation_name = 6; -} - -// Metadata type for the long-running operation used to track the progress -// of optimizations performed on a newly restored database. This long-running -// operation is automatically created by the system after the successful -// completion of a database restore, and cannot be cancelled. -message OptimizeRestoredDatabaseMetadata { - // Name of the restored database being optimized. - string name = 1 [(google.api.resource_reference) = { - type: "spanner.googleapis.com/Database" - }]; - - // The progress of the post-restore optimizations. - OperationProgress progress = 2; -} - -// Indicates the type of the restore source. -enum RestoreSourceType { - // No restore associated. - TYPE_UNSPECIFIED = 0; - - // A backup was used as the source of the restore. - BACKUP = 1; -} diff --git a/google/cloud/spanner_admin_instance_v1/proto/spanner_instance_admin.proto b/google/cloud/spanner_admin_instance_v1/proto/spanner_instance_admin.proto deleted file mode 100644 index 69043c1b37..0000000000 --- a/google/cloud/spanner_admin_instance_v1/proto/spanner_instance_admin.proto +++ /dev/null @@ -1,604 +0,0 @@ -// 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.instance.v1; - -import "google/api/annotations.proto"; -import "google/api/client.proto"; -import "google/api/field_behavior.proto"; -import "google/api/resource.proto"; -import "google/iam/v1/iam_policy.proto"; -import "google/iam/v1/policy.proto"; -import "google/longrunning/operations.proto"; -import "google/protobuf/empty.proto"; -import "google/protobuf/field_mask.proto"; -import "google/protobuf/timestamp.proto"; - -option csharp_namespace = "Google.Cloud.Spanner.Admin.Instance.V1"; -option go_package = "google.golang.org/genproto/googleapis/spanner/admin/instance/v1;instance"; -option java_multiple_files = true; -option java_outer_classname = "SpannerInstanceAdminProto"; -option java_package = "com.google.spanner.admin.instance.v1"; -option php_namespace = "Google\\Cloud\\Spanner\\Admin\\Instance\\V1"; -option ruby_package = "Google::Cloud::Spanner::Admin::Instance::V1"; - -// Cloud Spanner Instance Admin API -// -// The Cloud Spanner Instance Admin API can be used to create, delete, -// modify and list instances. Instances are dedicated Cloud Spanner serving -// and storage resources to be used by Cloud Spanner databases. -// -// Each instance has a "configuration", which dictates where the -// serving resources for the Cloud Spanner instance are located (e.g., -// US-central, Europe). Configurations are created by Google based on -// resource availability. -// -// Cloud Spanner billing is based on the instances that exist and their -// sizes. After an instance exists, there are no additional -// per-database or per-operation charges for use of the instance -// (though there may be additional network bandwidth charges). -// Instances offer isolation: problems with databases in one instance -// will not affect other instances. However, within an instance -// databases can affect each other. For example, if one database in an -// instance receives a lot of requests and consumes most of the -// instance resources, fewer resources are available for other -// databases in that instance, and their performance may suffer. -service InstanceAdmin { - option (google.api.default_host) = "spanner.googleapis.com"; - option (google.api.oauth_scopes) = - "https://www.googleapis.com/auth/cloud-platform," - "https://www.googleapis.com/auth/spanner.admin"; - - // Lists the supported instance configurations for a given project. - rpc ListInstanceConfigs(ListInstanceConfigsRequest) returns (ListInstanceConfigsResponse) { - option (google.api.http) = { - get: "/v1/{parent=projects/*}/instanceConfigs" - }; - option (google.api.method_signature) = "parent"; - } - - // Gets information about a particular instance configuration. - rpc GetInstanceConfig(GetInstanceConfigRequest) returns (InstanceConfig) { - option (google.api.http) = { - get: "/v1/{name=projects/*/instanceConfigs/*}" - }; - option (google.api.method_signature) = "name"; - } - - // Lists all instances in the given project. - rpc ListInstances(ListInstancesRequest) returns (ListInstancesResponse) { - option (google.api.http) = { - get: "/v1/{parent=projects/*}/instances" - }; - option (google.api.method_signature) = "parent"; - } - - // Gets information about a particular instance. - rpc GetInstance(GetInstanceRequest) returns (Instance) { - option (google.api.http) = { - get: "/v1/{name=projects/*/instances/*}" - }; - option (google.api.method_signature) = "name"; - } - - // Creates an instance and begins preparing it to begin serving. The - // returned [long-running operation][google.longrunning.Operation] - // can be used to track the progress of preparing the new - // instance. The instance name is assigned by the caller. If the - // named instance already exists, `CreateInstance` returns - // `ALREADY_EXISTS`. - // - // Immediately upon completion of this request: - // - // * The instance is readable via the API, with all requested attributes - // but no allocated resources. Its state is `CREATING`. - // - // Until completion of the returned operation: - // - // * Cancelling the operation renders the instance immediately unreadable - // via the API. - // * The instance can be deleted. - // * All other attempts to modify the instance are rejected. - // - // Upon completion of the returned operation: - // - // * Billing for all successfully-allocated resources begins (some types - // may have lower than the requested levels). - // * Databases can be created in the instance. - // * The instance's allocated resource levels are readable via the API. - // * The instance's state becomes `READY`. - // - // The returned [long-running operation][google.longrunning.Operation] will - // have a name of the format `/operations/` and - // can be used to track creation of the instance. The - // [metadata][google.longrunning.Operation.metadata] field type is - // [CreateInstanceMetadata][google.spanner.admin.instance.v1.CreateInstanceMetadata]. - // The [response][google.longrunning.Operation.response] field type is - // [Instance][google.spanner.admin.instance.v1.Instance], if successful. - rpc CreateInstance(CreateInstanceRequest) returns (google.longrunning.Operation) { - option (google.api.http) = { - post: "/v1/{parent=projects/*}/instances" - body: "*" - }; - option (google.api.method_signature) = "parent,instance_id,instance"; - option (google.longrunning.operation_info) = { - response_type: "google.spanner.admin.instance.v1.Instance" - metadata_type: "google.spanner.admin.instance.v1.CreateInstanceMetadata" - }; - } - - // Updates an instance, and begins allocating or releasing resources - // as requested. The returned [long-running - // operation][google.longrunning.Operation] can be used to track the - // progress of updating the instance. If the named instance does not - // exist, returns `NOT_FOUND`. - // - // Immediately upon completion of this request: - // - // * For resource types for which a decrease in the instance's allocation - // has been requested, billing is based on the newly-requested level. - // - // Until completion of the returned operation: - // - // * Cancelling the operation sets its metadata's - // [cancel_time][google.spanner.admin.instance.v1.UpdateInstanceMetadata.cancel_time], and begins - // restoring resources to their pre-request values. The operation - // is guaranteed to succeed at undoing all resource changes, - // after which point it terminates with a `CANCELLED` status. - // * All other attempts to modify the instance are rejected. - // * Reading the instance via the API continues to give the pre-request - // resource levels. - // - // Upon completion of the returned operation: - // - // * Billing begins for all successfully-allocated resources (some types - // may have lower than the requested levels). - // * All newly-reserved resources are available for serving the instance's - // tables. - // * The instance's new resource levels are readable via the API. - // - // The returned [long-running operation][google.longrunning.Operation] will - // have a name of the format `/operations/` and - // can be used to track the instance modification. The - // [metadata][google.longrunning.Operation.metadata] field type is - // [UpdateInstanceMetadata][google.spanner.admin.instance.v1.UpdateInstanceMetadata]. - // The [response][google.longrunning.Operation.response] field type is - // [Instance][google.spanner.admin.instance.v1.Instance], if successful. - // - // Authorization requires `spanner.instances.update` permission on - // resource [name][google.spanner.admin.instance.v1.Instance.name]. - rpc UpdateInstance(UpdateInstanceRequest) returns (google.longrunning.Operation) { - option (google.api.http) = { - patch: "/v1/{instance.name=projects/*/instances/*}" - body: "*" - }; - option (google.api.method_signature) = "instance,field_mask"; - option (google.longrunning.operation_info) = { - response_type: "google.spanner.admin.instance.v1.Instance" - metadata_type: "google.spanner.admin.instance.v1.UpdateInstanceMetadata" - }; - } - - // Deletes an instance. - // - // Immediately upon completion of the request: - // - // * Billing ceases for all of the instance's reserved resources. - // - // Soon afterward: - // - // * The instance and *all of its databases* immediately and - // irrevocably disappear from the API. All data in the databases - // is permanently deleted. - rpc DeleteInstance(DeleteInstanceRequest) returns (google.protobuf.Empty) { - option (google.api.http) = { - delete: "/v1/{name=projects/*/instances/*}" - }; - option (google.api.method_signature) = "name"; - } - - // Sets the access control policy on an instance resource. Replaces any - // existing policy. - // - // Authorization requires `spanner.instances.setIamPolicy` on - // [resource][google.iam.v1.SetIamPolicyRequest.resource]. - rpc SetIamPolicy(google.iam.v1.SetIamPolicyRequest) returns (google.iam.v1.Policy) { - option (google.api.http) = { - post: "/v1/{resource=projects/*/instances/*}:setIamPolicy" - body: "*" - }; - option (google.api.method_signature) = "resource,policy"; - } - - // Gets the access control policy for an instance resource. Returns an empty - // policy if an instance exists but does not have a policy set. - // - // Authorization requires `spanner.instances.getIamPolicy` on - // [resource][google.iam.v1.GetIamPolicyRequest.resource]. - rpc GetIamPolicy(google.iam.v1.GetIamPolicyRequest) returns (google.iam.v1.Policy) { - option (google.api.http) = { - post: "/v1/{resource=projects/*/instances/*}:getIamPolicy" - body: "*" - }; - option (google.api.method_signature) = "resource"; - } - - // Returns permissions that the caller has on the specified instance resource. - // - // Attempting this RPC on a non-existent Cloud Spanner instance resource will - // result in a NOT_FOUND error if the user has `spanner.instances.list` - // permission on the containing Google Cloud Project. Otherwise returns an - // empty set of permissions. - rpc TestIamPermissions(google.iam.v1.TestIamPermissionsRequest) returns (google.iam.v1.TestIamPermissionsResponse) { - option (google.api.http) = { - post: "/v1/{resource=projects/*/instances/*}:testIamPermissions" - body: "*" - }; - option (google.api.method_signature) = "resource,permissions"; - } -} - -message ReplicaInfo { - // Indicates the type of replica. See the [replica types - // documentation](https://cloud.google.com/spanner/docs/replication#replica_types) - // for more details. - enum ReplicaType { - // Not specified. - TYPE_UNSPECIFIED = 0; - - // Read-write replicas support both reads and writes. These replicas: - // - // * Maintain a full copy of your data. - // * Serve reads. - // * Can vote whether to commit a write. - // * Participate in leadership election. - // * Are eligible to become a leader. - READ_WRITE = 1; - - // Read-only replicas only support reads (not writes). Read-only replicas: - // - // * Maintain a full copy of your data. - // * Serve reads. - // * Do not participate in voting to commit writes. - // * Are not eligible to become a leader. - READ_ONLY = 2; - - // Witness replicas don't support reads but do participate in voting to - // commit writes. Witness replicas: - // - // * Do not maintain a full copy of data. - // * Do not serve reads. - // * Vote whether to commit writes. - // * Participate in leader election but are not eligible to become leader. - WITNESS = 3; - } - - // The location of the serving resources, e.g. "us-central1". - string location = 1; - - // The type of replica. - ReplicaType type = 2; - - // If true, this location is designated as the default leader location where - // leader replicas are placed. See the [region types - // documentation](https://cloud.google.com/spanner/docs/instances#region_types) - // for more details. - bool default_leader_location = 3; -} - -// A possible configuration for a Cloud Spanner instance. Configurations -// define the geographic placement of nodes and their replication. -message InstanceConfig { - option (google.api.resource) = { - type: "spanner.googleapis.com/InstanceConfig" - pattern: "projects/{project}/instanceConfigs/{instance_config}" - }; - - // A unique identifier for the instance configuration. Values - // are of the form - // `projects//instanceConfigs/[a-z][-a-z0-9]*` - string name = 1; - - // The name of this instance configuration as it appears in UIs. - string display_name = 2; - - // The geographic placement of nodes in this instance configuration and their - // replication properties. - repeated ReplicaInfo replicas = 3; -} - -// An isolated set of Cloud Spanner resources on which databases can be hosted. -message Instance { - option (google.api.resource) = { - type: "spanner.googleapis.com/Instance" - pattern: "projects/{project}/instances/{instance}" - }; - - // Indicates the current state of the instance. - enum State { - // Not specified. - STATE_UNSPECIFIED = 0; - - // The instance is still being created. Resources may not be - // available yet, and operations such as database creation may not - // work. - CREATING = 1; - - // The instance is fully created and ready to do work such as - // creating databases. - READY = 2; - } - - // Required. A unique identifier for the instance, which cannot be changed - // after the instance is created. Values are of the form - // `projects//instances/[a-z][-a-z0-9]*[a-z0-9]`. The final - // segment of the name must be between 2 and 64 characters in length. - string name = 1; - - // Required. The name of the instance's configuration. Values are of the form - // `projects//instanceConfigs/`. See - // also [InstanceConfig][google.spanner.admin.instance.v1.InstanceConfig] and - // [ListInstanceConfigs][google.spanner.admin.instance.v1.InstanceAdmin.ListInstanceConfigs]. - string config = 2 [(google.api.resource_reference) = { - type: "spanner.googleapis.com/InstanceConfig" - }]; - - // Required. The descriptive name for this instance as it appears in UIs. - // Must be unique per project and between 4 and 30 characters in length. - string display_name = 3; - - // Required. The number of nodes allocated to this instance. This may be zero - // in API responses for instances that are not yet in state `READY`. - // - // See [the - // documentation](https://cloud.google.com/spanner/docs/instances#node_count) - // for more information about nodes. - int32 node_count = 5; - - // Output only. The current instance state. For - // [CreateInstance][google.spanner.admin.instance.v1.InstanceAdmin.CreateInstance], the state must be - // either omitted or set to `CREATING`. For - // [UpdateInstance][google.spanner.admin.instance.v1.InstanceAdmin.UpdateInstance], the state must be - // either omitted or set to `READY`. - State state = 6 [(google.api.field_behavior) = OUTPUT_ONLY]; - - // Cloud Labels are a flexible and lightweight mechanism for organizing cloud - // resources into groups that reflect a customer's organizational needs and - // deployment strategies. Cloud Labels can be used to filter collections of - // resources. They can be used to control how resource metrics are aggregated. - // And they can be used as arguments to policy management rules (e.g. route, - // firewall, load balancing, etc.). - // - // * Label keys must be between 1 and 63 characters long and must conform to - // the following regular expression: `[a-z]([-a-z0-9]*[a-z0-9])?`. - // * Label values must be between 0 and 63 characters long and must conform - // to the regular expression `([a-z]([-a-z0-9]*[a-z0-9])?)?`. - // * No more than 64 labels can be associated with a given resource. - // - // See https://goo.gl/xmQnxf for more information on and examples of labels. - // - // If you plan to use labels in your own code, please note that additional - // characters may be allowed in the future. And so you are advised to use an - // internal label representation, such as JSON, which doesn't rely upon - // specific characters being disallowed. For example, representing labels - // as the string: name + "_" + value would prove problematic if we were to - // allow "_" in a future release. - map labels = 7; - - // Deprecated. This field is not populated. - repeated string endpoint_uris = 8; -} - -// The request for [ListInstanceConfigs][google.spanner.admin.instance.v1.InstanceAdmin.ListInstanceConfigs]. -message ListInstanceConfigsRequest { - // Required. The name of the project for which a list of supported instance - // configurations is requested. Values are of the form - // `projects/`. - string parent = 1 [ - (google.api.field_behavior) = REQUIRED, - (google.api.resource_reference) = { - type: "cloudresourcemanager.googleapis.com/Project" - } - ]; - - // Number of instance configurations to be returned in the response. If 0 or - // less, defaults to the server's maximum allowed page size. - int32 page_size = 2; - - // If non-empty, `page_token` should contain a - // [next_page_token][google.spanner.admin.instance.v1.ListInstanceConfigsResponse.next_page_token] - // from a previous [ListInstanceConfigsResponse][google.spanner.admin.instance.v1.ListInstanceConfigsResponse]. - string page_token = 3; -} - -// The response for [ListInstanceConfigs][google.spanner.admin.instance.v1.InstanceAdmin.ListInstanceConfigs]. -message ListInstanceConfigsResponse { - // The list of requested instance configurations. - repeated InstanceConfig instance_configs = 1; - - // `next_page_token` can be sent in a subsequent - // [ListInstanceConfigs][google.spanner.admin.instance.v1.InstanceAdmin.ListInstanceConfigs] call to - // fetch more of the matching instance configurations. - string next_page_token = 2; -} - -// The request for -// [GetInstanceConfigRequest][google.spanner.admin.instance.v1.InstanceAdmin.GetInstanceConfig]. -message GetInstanceConfigRequest { - // Required. The name of the requested instance configuration. Values are of - // the form `projects//instanceConfigs/`. - string name = 1 [ - (google.api.field_behavior) = REQUIRED, - (google.api.resource_reference) = { - type: "spanner.googleapis.com/InstanceConfig" - } - ]; -} - -// The request for [GetInstance][google.spanner.admin.instance.v1.InstanceAdmin.GetInstance]. -message GetInstanceRequest { - // Required. The name of the requested instance. Values are of the form - // `projects//instances/`. - string name = 1 [ - (google.api.field_behavior) = REQUIRED, - (google.api.resource_reference) = { - type: "spanner.googleapis.com/Instance" - } - ]; - - // If field_mask is present, specifies the subset of [Instance][google.spanner.admin.instance.v1.Instance] fields that - // should be returned. - // If absent, all [Instance][google.spanner.admin.instance.v1.Instance] fields are returned. - google.protobuf.FieldMask field_mask = 2; -} - -// The request for [CreateInstance][google.spanner.admin.instance.v1.InstanceAdmin.CreateInstance]. -message CreateInstanceRequest { - // Required. The name of the project in which to create the instance. Values - // are of the form `projects/`. - string parent = 1 [ - (google.api.field_behavior) = REQUIRED, - (google.api.resource_reference) = { - type: "cloudresourcemanager.googleapis.com/Project" - } - ]; - - // Required. The ID of the instance to create. Valid identifiers are of the - // form `[a-z][-a-z0-9]*[a-z0-9]` and must be between 2 and 64 characters in - // length. - string instance_id = 2 [(google.api.field_behavior) = REQUIRED]; - - // Required. The instance to create. The name may be omitted, but if - // specified must be `/instances/`. - Instance instance = 3 [(google.api.field_behavior) = REQUIRED]; -} - -// The request for [ListInstances][google.spanner.admin.instance.v1.InstanceAdmin.ListInstances]. -message ListInstancesRequest { - // Required. The name of the project for which a list of instances is - // requested. Values are of the form `projects/`. - string parent = 1 [ - (google.api.field_behavior) = REQUIRED, - (google.api.resource_reference) = { - type: "cloudresourcemanager.googleapis.com/Project" - } - ]; - - // Number of instances to be returned in the response. If 0 or less, defaults - // to the server's maximum allowed page size. - int32 page_size = 2; - - // If non-empty, `page_token` should contain a - // [next_page_token][google.spanner.admin.instance.v1.ListInstancesResponse.next_page_token] from a - // previous [ListInstancesResponse][google.spanner.admin.instance.v1.ListInstancesResponse]. - string page_token = 3; - - // An expression for filtering the results of the request. Filter rules are - // case insensitive. The fields eligible for filtering are: - // - // * `name` - // * `display_name` - // * `labels.key` where key is the name of a label - // - // Some examples of using filters are: - // - // * `name:*` --> The instance has a name. - // * `name:Howl` --> The instance's name contains the string "howl". - // * `name:HOWL` --> Equivalent to above. - // * `NAME:howl` --> Equivalent to above. - // * `labels.env:*` --> The instance has the label "env". - // * `labels.env:dev` --> The instance has the label "env" and the value of - // the label contains the string "dev". - // * `name:howl labels.env:dev` --> The instance's name contains "howl" and - // it has the label "env" with its value - // containing "dev". - string filter = 4; -} - -// The response for [ListInstances][google.spanner.admin.instance.v1.InstanceAdmin.ListInstances]. -message ListInstancesResponse { - // The list of requested instances. - repeated Instance instances = 1; - - // `next_page_token` can be sent in a subsequent - // [ListInstances][google.spanner.admin.instance.v1.InstanceAdmin.ListInstances] call to fetch more - // of the matching instances. - string next_page_token = 2; -} - -// The request for [UpdateInstance][google.spanner.admin.instance.v1.InstanceAdmin.UpdateInstance]. -message UpdateInstanceRequest { - // Required. The instance to update, which must always include the instance - // name. Otherwise, only fields mentioned in [field_mask][google.spanner.admin.instance.v1.UpdateInstanceRequest.field_mask] need be included. - Instance instance = 1 [(google.api.field_behavior) = REQUIRED]; - - // Required. A mask specifying which fields in [Instance][google.spanner.admin.instance.v1.Instance] should be updated. - // The field mask must always be specified; this prevents any future fields in - // [Instance][google.spanner.admin.instance.v1.Instance] from being erased accidentally by clients that do not know - // about them. - google.protobuf.FieldMask field_mask = 2 [(google.api.field_behavior) = REQUIRED]; -} - -// The request for [DeleteInstance][google.spanner.admin.instance.v1.InstanceAdmin.DeleteInstance]. -message DeleteInstanceRequest { - // Required. The name of the instance to be deleted. Values are of the form - // `projects//instances/` - string name = 1 [ - (google.api.field_behavior) = REQUIRED, - (google.api.resource_reference) = { - type: "spanner.googleapis.com/Instance" - } - ]; -} - -// Metadata type for the operation returned by -// [CreateInstance][google.spanner.admin.instance.v1.InstanceAdmin.CreateInstance]. -message CreateInstanceMetadata { - // The instance being created. - Instance instance = 1; - - // The time at which the - // [CreateInstance][google.spanner.admin.instance.v1.InstanceAdmin.CreateInstance] request was - // received. - google.protobuf.Timestamp start_time = 2; - - // The time at which this operation was cancelled. If set, this operation is - // in the process of undoing itself (which is guaranteed to succeed) and - // cannot be cancelled again. - google.protobuf.Timestamp cancel_time = 3; - - // The time at which this operation failed or was completed successfully. - google.protobuf.Timestamp end_time = 4; -} - -// Metadata type for the operation returned by -// [UpdateInstance][google.spanner.admin.instance.v1.InstanceAdmin.UpdateInstance]. -message UpdateInstanceMetadata { - // The desired end state of the update. - Instance instance = 1; - - // The time at which [UpdateInstance][google.spanner.admin.instance.v1.InstanceAdmin.UpdateInstance] - // request was received. - google.protobuf.Timestamp start_time = 2; - - // The time at which this operation was cancelled. If set, this operation is - // in the process of undoing itself (which is guaranteed to succeed) and - // cannot be cancelled again. - google.protobuf.Timestamp cancel_time = 3; - - // The time at which this operation failed or was completed successfully. - google.protobuf.Timestamp end_time = 4; -} diff --git a/google/cloud/spanner_v1/proto/keys.proto b/google/cloud/spanner_v1/proto/keys.proto deleted file mode 100644 index d8ce0d6774..0000000000 --- a/google/cloud/spanner_v1/proto/keys.proto +++ /dev/null @@ -1,164 +0,0 @@ -// 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/struct.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 = "KeysProto"; -option java_package = "com.google.spanner.v1"; -option php_namespace = "Google\\Cloud\\Spanner\\V1"; -option ruby_package = "Google::Cloud::Spanner::V1"; - -// KeyRange represents a range of rows in a table or index. -// -// A range has a start key and an end key. These keys can be open or -// closed, indicating if the range includes rows with that key. -// -// Keys are represented by lists, where the ith value in the list -// corresponds to the ith component of the table or index primary key. -// Individual values are encoded as described -// [here][google.spanner.v1.TypeCode]. -// -// For example, consider the following table definition: -// -// CREATE TABLE UserEvents ( -// UserName STRING(MAX), -// EventDate STRING(10) -// ) PRIMARY KEY(UserName, EventDate); -// -// The following keys name rows in this table: -// -// ["Bob", "2014-09-23"] -// ["Alfred", "2015-06-12"] -// -// Since the `UserEvents` table's `PRIMARY KEY` clause names two -// columns, each `UserEvents` key has two elements; the first is the -// `UserName`, and the second is the `EventDate`. -// -// Key ranges with multiple components are interpreted -// lexicographically by component using the table or index key's declared -// sort order. For example, the following range returns all events for -// user `"Bob"` that occurred in the year 2015: -// -// "start_closed": ["Bob", "2015-01-01"] -// "end_closed": ["Bob", "2015-12-31"] -// -// Start and end keys can omit trailing key components. This affects the -// inclusion and exclusion of rows that exactly match the provided key -// components: if the key is closed, then rows that exactly match the -// provided components are included; if the key is open, then rows -// that exactly match are not included. -// -// For example, the following range includes all events for `"Bob"` that -// occurred during and after the year 2000: -// -// "start_closed": ["Bob", "2000-01-01"] -// "end_closed": ["Bob"] -// -// The next example retrieves all events for `"Bob"`: -// -// "start_closed": ["Bob"] -// "end_closed": ["Bob"] -// -// To retrieve events before the year 2000: -// -// "start_closed": ["Bob"] -// "end_open": ["Bob", "2000-01-01"] -// -// The following range includes all rows in the table: -// -// "start_closed": [] -// "end_closed": [] -// -// This range returns all users whose `UserName` begins with any -// character from A to C: -// -// "start_closed": ["A"] -// "end_open": ["D"] -// -// This range returns all users whose `UserName` begins with B: -// -// "start_closed": ["B"] -// "end_open": ["C"] -// -// Key ranges honor column sort order. For example, suppose a table is -// defined as follows: -// -// CREATE TABLE DescendingSortedTable { -// Key INT64, -// ... -// ) PRIMARY KEY(Key DESC); -// -// The following range retrieves all rows with key values between 1 -// and 100 inclusive: -// -// "start_closed": ["100"] -// "end_closed": ["1"] -// -// Note that 100 is passed as the start, and 1 is passed as the end, -// because `Key` is a descending column in the schema. -message KeyRange { - // The start key must be provided. It can be either closed or open. - oneof start_key_type { - // If the start is closed, then the range includes all rows whose - // first `len(start_closed)` key columns exactly match `start_closed`. - google.protobuf.ListValue start_closed = 1; - - // If the start is open, then the range excludes rows whose first - // `len(start_open)` key columns exactly match `start_open`. - google.protobuf.ListValue start_open = 2; - } - - // The end key must be provided. It can be either closed or open. - oneof end_key_type { - // If the end is closed, then the range includes all rows whose - // first `len(end_closed)` key columns exactly match `end_closed`. - google.protobuf.ListValue end_closed = 3; - - // If the end is open, then the range excludes rows whose first - // `len(end_open)` key columns exactly match `end_open`. - google.protobuf.ListValue end_open = 4; - } -} - -// `KeySet` defines a collection of Cloud Spanner keys and/or key ranges. All -// the keys are expected to be in the same table or index. The keys need -// not be sorted in any particular way. -// -// If the same key is specified multiple times in the set (for example -// if two ranges, two keys, or a key and a range overlap), Cloud Spanner -// behaves as if the key were only specified once. -message KeySet { - // A list of specific keys. Entries in `keys` should have exactly as - // many elements as there are columns in the primary or index key - // with which this `KeySet` is used. Individual key values are - // encoded as described [here][google.spanner.v1.TypeCode]. - repeated google.protobuf.ListValue keys = 1; - - // A list of key ranges. See [KeyRange][google.spanner.v1.KeyRange] for more information about - // key range specifications. - repeated KeyRange ranges = 2; - - // For convenience `all` can be set to `true` to indicate that this - // `KeySet` matches all keys in the table or index. Note that any keys - // specified in `keys` or `ranges` are only yielded once. - bool all = 3; -} diff --git a/google/cloud/spanner_v1/proto/mutation.proto b/google/cloud/spanner_v1/proto/mutation.proto deleted file mode 100644 index 8ba51fc9ae..0000000000 --- a/google/cloud/spanner_v1/proto/mutation.proto +++ /dev/null @@ -1,107 +0,0 @@ -// Copyright 2020 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/struct.proto"; -import "google/spanner/v1/keys.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 = "MutationProto"; -option java_package = "com.google.spanner.v1"; -option php_namespace = "Google\\Cloud\\Spanner\\V1"; -option ruby_package = "Google::Cloud::Spanner::V1"; - -// A modification to one or more Cloud Spanner rows. Mutations can be -// applied to a Cloud Spanner database by sending them in a -// [Commit][google.spanner.v1.Spanner.Commit] call. -message Mutation { - // Arguments to [insert][google.spanner.v1.Mutation.insert], [update][google.spanner.v1.Mutation.update], [insert_or_update][google.spanner.v1.Mutation.insert_or_update], and - // [replace][google.spanner.v1.Mutation.replace] operations. - message Write { - // Required. The table whose rows will be written. - string table = 1; - - // The names of the columns in [table][google.spanner.v1.Mutation.Write.table] to be written. - // - // The list of columns must contain enough columns to allow - // Cloud Spanner to derive values for all primary key columns in the - // row(s) to be modified. - repeated string columns = 2; - - // The values to be written. `values` can contain more than one - // list of values. If it does, then multiple rows are written, one - // for each entry in `values`. Each list in `values` must have - // exactly as many entries as there are entries in [columns][google.spanner.v1.Mutation.Write.columns] - // above. Sending multiple lists is equivalent to sending multiple - // `Mutation`s, each containing one `values` entry and repeating - // [table][google.spanner.v1.Mutation.Write.table] and [columns][google.spanner.v1.Mutation.Write.columns]. Individual values in each list are - // encoded as described [here][google.spanner.v1.TypeCode]. - repeated google.protobuf.ListValue values = 3; - } - - // Arguments to [delete][google.spanner.v1.Mutation.delete] operations. - message Delete { - // Required. The table whose rows will be deleted. - string table = 1; - - // Required. The primary keys of the rows within [table][google.spanner.v1.Mutation.Delete.table] to delete. The - // primary keys must be specified in the order in which they appear in the - // `PRIMARY KEY()` clause of the table's equivalent DDL statement (the DDL - // statement used to create the table). - // Delete is idempotent. The transaction will succeed even if some or all - // rows do not exist. - KeySet key_set = 2; - } - - // Required. The operation to perform. - oneof operation { - // Insert new rows in a table. If any of the rows already exist, - // the write or transaction fails with error `ALREADY_EXISTS`. - Write insert = 1; - - // Update existing rows in a table. If any of the rows does not - // already exist, the transaction fails with error `NOT_FOUND`. - Write update = 2; - - // Like [insert][google.spanner.v1.Mutation.insert], except that if the row already exists, then - // its column values are overwritten with the ones provided. Any - // column values not explicitly written are preserved. - // - // When using [insert_or_update][google.spanner.v1.Mutation.insert_or_update], just as when using [insert][google.spanner.v1.Mutation.insert], all `NOT - // NULL` columns in the table must be given a value. This holds true - // even when the row already exists and will therefore actually be updated. - Write insert_or_update = 3; - - // Like [insert][google.spanner.v1.Mutation.insert], except that if the row already exists, it is - // deleted, and the column values provided are inserted - // instead. Unlike [insert_or_update][google.spanner.v1.Mutation.insert_or_update], this means any values not - // explicitly written become `NULL`. - // - // In an interleaved table, if you create the child table with the - // `ON DELETE CASCADE` annotation, then replacing a parent row - // also deletes the child rows. Otherwise, you must delete the - // child rows before you replace the parent row. - Write replace = 4; - - // Delete rows from a table. Succeeds whether or not the named - // rows were present. - Delete delete = 5; - } -} diff --git a/google/cloud/spanner_v1/proto/query_plan.proto b/google/cloud/spanner_v1/proto/query_plan.proto deleted file mode 100644 index 35f8fe21c5..0000000000 --- a/google/cloud/spanner_v1/proto/query_plan.proto +++ /dev/null @@ -1,129 +0,0 @@ -// 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/struct.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 = "QueryPlanProto"; -option java_package = "com.google.spanner.v1"; -option php_namespace = "Google\\Cloud\\Spanner\\V1"; -option ruby_package = "Google::Cloud::Spanner::V1"; - -// Node information for nodes appearing in a [QueryPlan.plan_nodes][google.spanner.v1.QueryPlan.plan_nodes]. -message PlanNode { - // Metadata associated with a parent-child relationship appearing in a - // [PlanNode][google.spanner.v1.PlanNode]. - message ChildLink { - // The node to which the link points. - int32 child_index = 1; - - // The type of the link. For example, in Hash Joins this could be used to - // distinguish between the build child and the probe child, or in the case - // of the child being an output variable, to represent the tag associated - // with the output variable. - string type = 2; - - // Only present if the child node is [SCALAR][google.spanner.v1.PlanNode.Kind.SCALAR] and corresponds - // to an output variable of the parent node. The field carries the name of - // the output variable. - // For example, a `TableScan` operator that reads rows from a table will - // have child links to the `SCALAR` nodes representing the output variables - // created for each column that is read by the operator. The corresponding - // `variable` fields will be set to the variable names assigned to the - // columns. - string variable = 3; - } - - // Condensed representation of a node and its subtree. Only present for - // `SCALAR` [PlanNode(s)][google.spanner.v1.PlanNode]. - message ShortRepresentation { - // A string representation of the expression subtree rooted at this node. - string description = 1; - - // A mapping of (subquery variable name) -> (subquery node id) for cases - // where the `description` string of this node references a `SCALAR` - // subquery contained in the expression subtree rooted at this node. The - // referenced `SCALAR` subquery may not necessarily be a direct child of - // this node. - map subqueries = 2; - } - - // The kind of [PlanNode][google.spanner.v1.PlanNode]. Distinguishes between the two different kinds of - // nodes that can appear in a query plan. - enum Kind { - // Not specified. - KIND_UNSPECIFIED = 0; - - // Denotes a Relational operator node in the expression tree. Relational - // operators represent iterative processing of rows during query execution. - // For example, a `TableScan` operation that reads rows from a table. - RELATIONAL = 1; - - // Denotes a Scalar node in the expression tree. Scalar nodes represent - // non-iterable entities in the query plan. For example, constants or - // arithmetic operators appearing inside predicate expressions or references - // to column names. - SCALAR = 2; - } - - // The `PlanNode`'s index in [node list][google.spanner.v1.QueryPlan.plan_nodes]. - int32 index = 1; - - // Used to determine the type of node. May be needed for visualizing - // different kinds of nodes differently. For example, If the node is a - // [SCALAR][google.spanner.v1.PlanNode.Kind.SCALAR] node, it will have a condensed representation - // which can be used to directly embed a description of the node in its - // parent. - Kind kind = 2; - - // The display name for the node. - string display_name = 3; - - // List of child node `index`es and their relationship to this parent. - repeated ChildLink child_links = 4; - - // Condensed representation for [SCALAR][google.spanner.v1.PlanNode.Kind.SCALAR] nodes. - ShortRepresentation short_representation = 5; - - // Attributes relevant to the node contained in a group of key-value pairs. - // For example, a Parameter Reference node could have the following - // information in its metadata: - // - // { - // "parameter_reference": "param1", - // "parameter_type": "array" - // } - google.protobuf.Struct metadata = 6; - - // The execution statistics associated with the node, contained in a group of - // key-value pairs. Only present if the plan was returned as a result of a - // profile query. For example, number of executions, number of rows/time per - // execution etc. - google.protobuf.Struct execution_stats = 7; -} - -// Contains an ordered list of nodes appearing in the query plan. -message QueryPlan { - // The nodes in the query plan. Plan nodes are returned in pre-order starting - // with the plan root. Each [PlanNode][google.spanner.v1.PlanNode]'s `id` corresponds to its index in - // `plan_nodes`. - repeated PlanNode plan_nodes = 1; -} diff --git a/google/cloud/spanner_v1/proto/result_set.proto b/google/cloud/spanner_v1/proto/result_set.proto deleted file mode 100644 index d6bb9a2831..0000000000 --- a/google/cloud/spanner_v1/proto/result_set.proto +++ /dev/null @@ -1,205 +0,0 @@ -// 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/struct.proto"; -import "google/spanner/v1/query_plan.proto"; -import "google/spanner/v1/transaction.proto"; -import "google/spanner/v1/type.proto"; -import "google/api/annotations.proto"; - -option cc_enable_arenas = true; -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 = "ResultSetProto"; -option java_package = "com.google.spanner.v1"; -option php_namespace = "Google\\Cloud\\Spanner\\V1"; -option ruby_package = "Google::Cloud::Spanner::V1"; - -// Results from [Read][google.spanner.v1.Spanner.Read] or -// [ExecuteSql][google.spanner.v1.Spanner.ExecuteSql]. -message ResultSet { - // Metadata about the result set, such as row type information. - ResultSetMetadata metadata = 1; - - // Each element in `rows` is a row whose format is defined by - // [metadata.row_type][google.spanner.v1.ResultSetMetadata.row_type]. The ith element - // in each row matches the ith field in - // [metadata.row_type][google.spanner.v1.ResultSetMetadata.row_type]. Elements are - // encoded based on type as described - // [here][google.spanner.v1.TypeCode]. - repeated google.protobuf.ListValue rows = 2; - - // Query plan and execution statistics for the SQL statement that - // produced this result set. These can be requested by setting - // [ExecuteSqlRequest.query_mode][google.spanner.v1.ExecuteSqlRequest.query_mode]. - // DML statements always produce stats containing the number of rows - // modified, unless executed using the - // [ExecuteSqlRequest.QueryMode.PLAN][google.spanner.v1.ExecuteSqlRequest.QueryMode.PLAN] [ExecuteSqlRequest.query_mode][google.spanner.v1.ExecuteSqlRequest.query_mode]. - // Other fields may or may not be populated, based on the - // [ExecuteSqlRequest.query_mode][google.spanner.v1.ExecuteSqlRequest.query_mode]. - ResultSetStats stats = 3; -} - -// Partial results from a streaming read or SQL query. Streaming reads and -// SQL queries better tolerate large result sets, large rows, and large -// values, but are a little trickier to consume. -message PartialResultSet { - // Metadata about the result set, such as row type information. - // Only present in the first response. - ResultSetMetadata metadata = 1; - - // A streamed result set consists of a stream of values, which might - // be split into many `PartialResultSet` messages to accommodate - // large rows and/or large values. Every N complete values defines a - // row, where N is equal to the number of entries in - // [metadata.row_type.fields][google.spanner.v1.StructType.fields]. - // - // Most values are encoded based on type as described - // [here][google.spanner.v1.TypeCode]. - // - // It is possible that the last value in values is "chunked", - // meaning that the rest of the value is sent in subsequent - // `PartialResultSet`(s). This is denoted by the [chunked_value][google.spanner.v1.PartialResultSet.chunked_value] - // field. Two or more chunked values can be merged to form a - // complete value as follows: - // - // * `bool/number/null`: cannot be chunked - // * `string`: concatenate the strings - // * `list`: concatenate the lists. If the last element in a list is a - // `string`, `list`, or `object`, merge it with the first element in - // the next list by applying these rules recursively. - // * `object`: concatenate the (field name, field value) pairs. If a - // field name is duplicated, then apply these rules recursively - // to merge the field values. - // - // Some examples of merging: - // - // # Strings are concatenated. - // "foo", "bar" => "foobar" - // - // # Lists of non-strings are concatenated. - // [2, 3], [4] => [2, 3, 4] - // - // # Lists are concatenated, but the last and first elements are merged - // # because they are strings. - // ["a", "b"], ["c", "d"] => ["a", "bc", "d"] - // - // # Lists are concatenated, but the last and first elements are merged - // # because they are lists. Recursively, the last and first elements - // # of the inner lists are merged because they are strings. - // ["a", ["b", "c"]], [["d"], "e"] => ["a", ["b", "cd"], "e"] - // - // # Non-overlapping object fields are combined. - // {"a": "1"}, {"b": "2"} => {"a": "1", "b": 2"} - // - // # Overlapping object fields are merged. - // {"a": "1"}, {"a": "2"} => {"a": "12"} - // - // # Examples of merging objects containing lists of strings. - // {"a": ["1"]}, {"a": ["2"]} => {"a": ["12"]} - // - // For a more complete example, suppose a streaming SQL query is - // yielding a result set whose rows contain a single string - // field. The following `PartialResultSet`s might be yielded: - // - // { - // "metadata": { ... } - // "values": ["Hello", "W"] - // "chunked_value": true - // "resume_token": "Af65..." - // } - // { - // "values": ["orl"] - // "chunked_value": true - // "resume_token": "Bqp2..." - // } - // { - // "values": ["d"] - // "resume_token": "Zx1B..." - // } - // - // This sequence of `PartialResultSet`s encodes two rows, one - // containing the field value `"Hello"`, and a second containing the - // field value `"World" = "W" + "orl" + "d"`. - repeated google.protobuf.Value values = 2; - - // If true, then the final value in [values][google.spanner.v1.PartialResultSet.values] is chunked, and must - // be combined with more values from subsequent `PartialResultSet`s - // to obtain a complete field value. - bool chunked_value = 3; - - // Streaming calls might be interrupted for a variety of reasons, such - // as TCP connection loss. If this occurs, the stream of results can - // be resumed by re-sending the original request and including - // `resume_token`. Note that executing any other transaction in the - // same session invalidates the token. - bytes resume_token = 4; - - // Query plan and execution statistics for the statement that produced this - // streaming result set. These can be requested by setting - // [ExecuteSqlRequest.query_mode][google.spanner.v1.ExecuteSqlRequest.query_mode] and are sent - // only once with the last response in the stream. - // This field will also be present in the last response for DML - // statements. - ResultSetStats stats = 5; -} - -// Metadata about a [ResultSet][google.spanner.v1.ResultSet] or [PartialResultSet][google.spanner.v1.PartialResultSet]. -message ResultSetMetadata { - // Indicates the field names and types for the rows in the result - // set. For example, a SQL query like `"SELECT UserId, UserName FROM - // Users"` could return a `row_type` value like: - // - // "fields": [ - // { "name": "UserId", "type": { "code": "INT64" } }, - // { "name": "UserName", "type": { "code": "STRING" } }, - // ] - StructType row_type = 1; - - // If the read or SQL query began a transaction as a side-effect, the - // information about the new transaction is yielded here. - Transaction transaction = 2; -} - -// Additional statistics about a [ResultSet][google.spanner.v1.ResultSet] or [PartialResultSet][google.spanner.v1.PartialResultSet]. -message ResultSetStats { - // [QueryPlan][google.spanner.v1.QueryPlan] for the query associated with this result. - QueryPlan query_plan = 1; - - // Aggregated statistics from the execution of the query. Only present when - // the query is profiled. For example, a query could return the statistics as - // follows: - // - // { - // "rows_returned": "3", - // "elapsed_time": "1.22 secs", - // "cpu_time": "1.19 secs" - // } - google.protobuf.Struct query_stats = 2; - - // The number of rows modified by the DML statement. - oneof row_count { - // Standard DML returns an exact count of rows that were modified. - int64 row_count_exact = 3; - - // Partitioned DML does not offer exactly-once semantics, so it - // returns a lower bound of the rows modified. - int64 row_count_lower_bound = 4; - } -} diff --git a/google/cloud/spanner_v1/proto/spanner.proto b/google/cloud/spanner_v1/proto/spanner.proto deleted file mode 100644 index c436227221..0000000000 --- a/google/cloud/spanner_v1/proto/spanner.proto +++ /dev/null @@ -1,1044 +0,0 @@ -// 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/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"; -import "google/rpc/status.proto"; -import "google/spanner/v1/keys.proto"; -import "google/spanner/v1/mutation.proto"; -import "google/spanner/v1/result_set.proto"; -import "google/spanner/v1/transaction.proto"; -import "google/spanner/v1/type.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 = "SpannerProto"; -option java_package = "com.google.spanner.v1"; -option php_namespace = "Google\\Cloud\\Spanner\\V1"; -option ruby_package = "Google::Cloud::Spanner::V1"; -option (google.api.resource_definition) = { - type: "spanner.googleapis.com/Database" - pattern: "projects/{project}/instances/{instance}/databases/{database}" -}; - -// Cloud Spanner API -// -// The Cloud Spanner API can be used to manage sessions and execute -// transactions on data stored in Cloud Spanner databases. -service Spanner { - option (google.api.default_host) = "spanner.googleapis.com"; - option (google.api.oauth_scopes) = - "https://www.googleapis.com/auth/cloud-platform," - "https://www.googleapis.com/auth/spanner.data"; - - // Creates a new session. A session can be used to perform - // transactions that read and/or modify data in a Cloud Spanner database. - // Sessions are meant to be reused for many consecutive - // transactions. - // - // Sessions can only execute one transaction at a time. To execute - // multiple concurrent read-write/write-only transactions, create - // multiple sessions. Note that standalone reads and queries use a - // transaction internally, and count toward the one transaction - // limit. - // - // Active sessions use additional server resources, so it is a good idea to - // delete idle and unneeded sessions. - // Aside from explicit deletes, Cloud Spanner may delete sessions for which no - // operations are sent for more than an hour. If a session is deleted, - // requests to it return `NOT_FOUND`. - // - // Idle sessions can be kept alive by sending a trivial SQL query - // periodically, e.g., `"SELECT 1"`. - rpc CreateSession(CreateSessionRequest) returns (Session) { - option (google.api.http) = { - post: "/v1/{database=projects/*/instances/*/databases/*}/sessions" - body: "*" - }; - option (google.api.method_signature) = "database"; - } - - // Creates multiple new sessions. - // - // This API can be used to initialize a session cache on the clients. - // See https://goo.gl/TgSFN2 for best practices on session cache management. - rpc BatchCreateSessions(BatchCreateSessionsRequest) returns (BatchCreateSessionsResponse) { - option (google.api.http) = { - post: "/v1/{database=projects/*/instances/*/databases/*}/sessions:batchCreate" - body: "*" - }; - option (google.api.method_signature) = "database,session_count"; - } - - // Gets a session. Returns `NOT_FOUND` if the session does not exist. - // This is mainly useful for determining whether a session is still - // alive. - rpc GetSession(GetSessionRequest) returns (Session) { - option (google.api.http) = { - get: "/v1/{name=projects/*/instances/*/databases/*/sessions/*}" - }; - option (google.api.method_signature) = "name"; - } - - // Lists all sessions in a given database. - rpc ListSessions(ListSessionsRequest) returns (ListSessionsResponse) { - option (google.api.http) = { - get: "/v1/{database=projects/*/instances/*/databases/*}/sessions" - }; - option (google.api.method_signature) = "database"; - } - - // Ends a session, releasing server resources associated with it. This will - // asynchronously trigger cancellation of any operations that are running with - // this session. - rpc DeleteSession(DeleteSessionRequest) returns (google.protobuf.Empty) { - option (google.api.http) = { - delete: "/v1/{name=projects/*/instances/*/databases/*/sessions/*}" - }; - option (google.api.method_signature) = "name"; - } - - // Executes an SQL statement, returning all results in a single reply. This - // method cannot be used to return a result set larger than 10 MiB; - // if the query yields more data than that, the query fails with - // a `FAILED_PRECONDITION` error. - // - // Operations inside read-write transactions might return `ABORTED`. If - // this occurs, the application should restart the transaction from - // the beginning. See [Transaction][google.spanner.v1.Transaction] for more details. - // - // Larger result sets can be fetched in streaming fashion by calling - // [ExecuteStreamingSql][google.spanner.v1.Spanner.ExecuteStreamingSql] instead. - rpc ExecuteSql(ExecuteSqlRequest) returns (ResultSet) { - option (google.api.http) = { - post: "/v1/{session=projects/*/instances/*/databases/*/sessions/*}:executeSql" - body: "*" - }; - } - - // Like [ExecuteSql][google.spanner.v1.Spanner.ExecuteSql], except returns the result - // set as a stream. Unlike [ExecuteSql][google.spanner.v1.Spanner.ExecuteSql], there - // is no limit on the size of the returned result set. However, no - // individual row in the result set can exceed 100 MiB, and no - // column value can exceed 10 MiB. - rpc ExecuteStreamingSql(ExecuteSqlRequest) returns (stream PartialResultSet) { - option (google.api.http) = { - post: "/v1/{session=projects/*/instances/*/databases/*/sessions/*}:executeStreamingSql" - body: "*" - }; - } - - // Executes a batch of SQL DML statements. This method allows many statements - // to be run with lower latency than submitting them sequentially with - // [ExecuteSql][google.spanner.v1.Spanner.ExecuteSql]. - // - // Statements are executed in sequential order. A request can succeed even if - // a statement fails. The [ExecuteBatchDmlResponse.status][google.spanner.v1.ExecuteBatchDmlResponse.status] field in the - // response provides information about the statement that failed. Clients must - // inspect this field to determine whether an error occurred. - // - // Execution stops after the first failed statement; the remaining statements - // are not executed. - rpc ExecuteBatchDml(ExecuteBatchDmlRequest) returns (ExecuteBatchDmlResponse) { - option (google.api.http) = { - post: "/v1/{session=projects/*/instances/*/databases/*/sessions/*}:executeBatchDml" - body: "*" - }; - } - - // Reads rows from the database using key lookups and scans, as a - // simple key/value style alternative to - // [ExecuteSql][google.spanner.v1.Spanner.ExecuteSql]. This method cannot be used to - // return a result set larger than 10 MiB; if the read matches more - // data than that, the read fails with a `FAILED_PRECONDITION` - // error. - // - // Reads inside read-write transactions might return `ABORTED`. If - // this occurs, the application should restart the transaction from - // the beginning. See [Transaction][google.spanner.v1.Transaction] for more details. - // - // Larger result sets can be yielded in streaming fashion by calling - // [StreamingRead][google.spanner.v1.Spanner.StreamingRead] instead. - rpc Read(ReadRequest) returns (ResultSet) { - option (google.api.http) = { - post: "/v1/{session=projects/*/instances/*/databases/*/sessions/*}:read" - body: "*" - }; - } - - // Like [Read][google.spanner.v1.Spanner.Read], except returns the result set as a - // stream. Unlike [Read][google.spanner.v1.Spanner.Read], there is no limit on the - // size of the returned result set. However, no individual row in - // the result set can exceed 100 MiB, and no column value can exceed - // 10 MiB. - rpc StreamingRead(ReadRequest) returns (stream PartialResultSet) { - option (google.api.http) = { - post: "/v1/{session=projects/*/instances/*/databases/*/sessions/*}:streamingRead" - body: "*" - }; - } - - // Begins a new transaction. This step can often be skipped: - // [Read][google.spanner.v1.Spanner.Read], [ExecuteSql][google.spanner.v1.Spanner.ExecuteSql] and - // [Commit][google.spanner.v1.Spanner.Commit] can begin a new transaction as a - // side-effect. - rpc BeginTransaction(BeginTransactionRequest) returns (Transaction) { - option (google.api.http) = { - post: "/v1/{session=projects/*/instances/*/databases/*/sessions/*}:beginTransaction" - body: "*" - }; - option (google.api.method_signature) = "session,options"; - } - - // Commits a transaction. The request includes the mutations to be - // applied to rows in the database. - // - // `Commit` might return an `ABORTED` error. This can occur at any time; - // commonly, the cause is conflicts with concurrent - // transactions. However, it can also happen for a variety of other - // reasons. If `Commit` returns `ABORTED`, the caller should re-attempt - // the transaction from the beginning, re-using the same session. - // - // On very rare occasions, `Commit` might return `UNKNOWN`. This can happen, - // for example, if the client job experiences a 1+ hour networking failure. - // At that point, Cloud Spanner has lost track of the transaction outcome and - // we recommend that you perform another read from the database to see the - // state of things as they are now. - rpc Commit(CommitRequest) returns (CommitResponse) { - option (google.api.http) = { - post: "/v1/{session=projects/*/instances/*/databases/*/sessions/*}:commit" - body: "*" - }; - option (google.api.method_signature) = "session,transaction_id,mutations"; - option (google.api.method_signature) = "session,single_use_transaction,mutations"; - } - - // Rolls back a transaction, releasing any locks it holds. It is a good - // idea to call this for any transaction that includes one or more - // [Read][google.spanner.v1.Spanner.Read] or [ExecuteSql][google.spanner.v1.Spanner.ExecuteSql] requests and - // ultimately decides not to commit. - // - // `Rollback` returns `OK` if it successfully aborts the transaction, the - // transaction was already aborted, or the transaction is not - // found. `Rollback` never returns `ABORTED`. - rpc Rollback(RollbackRequest) returns (google.protobuf.Empty) { - option (google.api.http) = { - post: "/v1/{session=projects/*/instances/*/databases/*/sessions/*}:rollback" - body: "*" - }; - option (google.api.method_signature) = "session,transaction_id"; - } - - // Creates a set of partition tokens that can be used to execute a query - // operation in parallel. Each of the returned partition tokens can be used - // by [ExecuteStreamingSql][google.spanner.v1.Spanner.ExecuteStreamingSql] to specify a subset - // of the query result to read. The same session and read-only transaction - // must be used by the PartitionQueryRequest used to create the - // partition tokens and the ExecuteSqlRequests that use the partition tokens. - // - // Partition tokens become invalid when the session used to create them - // is deleted, is idle for too long, begins a new transaction, or becomes too - // old. When any of these happen, it is not possible to resume the query, and - // the whole operation must be restarted from the beginning. - rpc PartitionQuery(PartitionQueryRequest) returns (PartitionResponse) { - option (google.api.http) = { - post: "/v1/{session=projects/*/instances/*/databases/*/sessions/*}:partitionQuery" - body: "*" - }; - } - - // Creates a set of partition tokens that can be used to execute a read - // operation in parallel. Each of the returned partition tokens can be used - // by [StreamingRead][google.spanner.v1.Spanner.StreamingRead] to specify a subset of the read - // result to read. The same session and read-only transaction must be used by - // the PartitionReadRequest used to create the partition tokens and the - // ReadRequests that use the partition tokens. There are no ordering - // guarantees on rows returned among the returned partition tokens, or even - // within each individual StreamingRead call issued with a partition_token. - // - // Partition tokens become invalid when the session used to create them - // is deleted, is idle for too long, begins a new transaction, or becomes too - // old. When any of these happen, it is not possible to resume the read, and - // the whole operation must be restarted from the beginning. - rpc PartitionRead(PartitionReadRequest) returns (PartitionResponse) { - option (google.api.http) = { - post: "/v1/{session=projects/*/instances/*/databases/*/sessions/*}:partitionRead" - body: "*" - }; - } -} - -// The request for [CreateSession][google.spanner.v1.Spanner.CreateSession]. -message CreateSessionRequest { - // Required. The database in which the new session is created. - string database = 1 [ - (google.api.field_behavior) = REQUIRED, - (google.api.resource_reference) = { - type: "spanner.googleapis.com/Database" - } - ]; - - // The session to create. - Session session = 2; -} - -// The request for [BatchCreateSessions][google.spanner.v1.Spanner.BatchCreateSessions]. -message BatchCreateSessionsRequest { - // Required. The database in which the new sessions are created. - string database = 1 [ - (google.api.field_behavior) = REQUIRED, - (google.api.resource_reference) = { - type: "spanner.googleapis.com/Database" - } - ]; - - // Parameters to be applied to each created session. - Session session_template = 2; - - // Required. The number of sessions to be created in this batch call. - // The API may return fewer than the requested number of sessions. If a - // specific number of sessions are desired, the client can make additional - // calls to BatchCreateSessions (adjusting - // [session_count][google.spanner.v1.BatchCreateSessionsRequest.session_count] as necessary). - int32 session_count = 3 [(google.api.field_behavior) = REQUIRED]; -} - -// The response for [BatchCreateSessions][google.spanner.v1.Spanner.BatchCreateSessions]. -message BatchCreateSessionsResponse { - // The freshly created sessions. - repeated Session session = 1; -} - -// A session in the Cloud Spanner API. -message Session { - option (google.api.resource) = { - type: "spanner.googleapis.com/Session" - pattern: "projects/{project}/instances/{instance}/databases/{database}/sessions/{session}" - }; - - // Output only. The name of the session. This is always system-assigned. - string name = 1 [(google.api.field_behavior) = OUTPUT_ONLY]; - - // The labels for the session. - // - // * Label keys must be between 1 and 63 characters long and must conform to - // the following regular expression: `[a-z]([-a-z0-9]*[a-z0-9])?`. - // * Label values must be between 0 and 63 characters long and must conform - // to the regular expression `([a-z]([-a-z0-9]*[a-z0-9])?)?`. - // * No more than 64 labels can be associated with a given session. - // - // See https://goo.gl/xmQnxf for more information on and examples of labels. - map labels = 2; - - // Output only. The timestamp when the session is created. - google.protobuf.Timestamp create_time = 3 [(google.api.field_behavior) = OUTPUT_ONLY]; - - // Output only. The approximate timestamp when the session is last used. It is - // typically earlier than the actual last use time. - google.protobuf.Timestamp approximate_last_use_time = 4 [(google.api.field_behavior) = OUTPUT_ONLY]; -} - -// The request for [GetSession][google.spanner.v1.Spanner.GetSession]. -message GetSessionRequest { - // Required. The name of the session to retrieve. - string name = 1 [ - (google.api.field_behavior) = REQUIRED, - (google.api.resource_reference) = { - type: "spanner.googleapis.com/Session" - } - ]; -} - -// The request for [ListSessions][google.spanner.v1.Spanner.ListSessions]. -message ListSessionsRequest { - // Required. The database in which to list sessions. - string database = 1 [ - (google.api.field_behavior) = REQUIRED, - (google.api.resource_reference) = { - type: "spanner.googleapis.com/Database" - } - ]; - - // Number of sessions to be returned in the response. If 0 or less, defaults - // to the server's maximum allowed page size. - int32 page_size = 2; - - // If non-empty, `page_token` should contain a - // [next_page_token][google.spanner.v1.ListSessionsResponse.next_page_token] from a previous - // [ListSessionsResponse][google.spanner.v1.ListSessionsResponse]. - string page_token = 3; - - // An expression for filtering the results of the request. Filter rules are - // case insensitive. The fields eligible for filtering are: - // - // * `labels.key` where key is the name of a label - // - // Some examples of using filters are: - // - // * `labels.env:*` --> The session has the label "env". - // * `labels.env:dev` --> The session has the label "env" and the value of - // the label contains the string "dev". - string filter = 4; -} - -// The response for [ListSessions][google.spanner.v1.Spanner.ListSessions]. -message ListSessionsResponse { - // The list of requested sessions. - repeated Session sessions = 1; - - // `next_page_token` can be sent in a subsequent - // [ListSessions][google.spanner.v1.Spanner.ListSessions] call to fetch more of the matching - // sessions. - string next_page_token = 2; -} - -// The request for [DeleteSession][google.spanner.v1.Spanner.DeleteSession]. -message DeleteSessionRequest { - // Required. The name of the session to delete. - string name = 1 [ - (google.api.field_behavior) = REQUIRED, - (google.api.resource_reference) = { - type: "spanner.googleapis.com/Session" - } - ]; -} - -// Common request options for various APIs. -message RequestOptions { - // The relative priority for requests. Note that priority is not applicable - // for [BeginTransaction][google.spanner.v1.Spanner.BeginTransaction]. - // - // The priority acts as a hint to the Cloud Spanner scheduler and does not - // guarantee priority or order of execution. For example: - // - // * Some parts of a write operation always execute at `PRIORITY_HIGH`, - // regardless of the specified priority. This may cause you to see an - // increase in high priority workload even when executing a low priority - // request. This can also potentially cause a priority inversion where a - // lower priority request will be fulfilled ahead of a higher priority - // request. - // * If a transaction contains multiple operations with different priorities, - // Cloud Spanner does not guarantee to process the higher priority - // operations first. There may be other constraints to satisfy, such as - // order of operations. - enum Priority { - // `PRIORITY_UNSPECIFIED` is equivalent to `PRIORITY_HIGH`. - PRIORITY_UNSPECIFIED = 0; - - // This specifies that the request is low priority. - PRIORITY_LOW = 1; - - // This specifies that the request is medium priority. - PRIORITY_MEDIUM = 2; - - // This specifies that the request is high priority. - PRIORITY_HIGH = 3; - } - - // Priority for the request. - Priority priority = 1; - - // A per-request tag which can be applied to queries or reads, used for - // statistics collection. - // Both request_tag and transaction_tag can be specified for a read or query - // 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 - string request_tag = 2; - - // A tag used for statistics collection about this transaction. - // Both request_tag and transaction_tag can be specified for a read or query - // that belongs to a transaction. - // The value of transaction_tag should be the same for all requests belonging - // 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}` - string transaction_tag = 3; -} - -// The request for [ExecuteSql][google.spanner.v1.Spanner.ExecuteSql] and -// [ExecuteStreamingSql][google.spanner.v1.Spanner.ExecuteStreamingSql]. -message ExecuteSqlRequest { - // Query optimizer configuration. - message QueryOptions { - // An option to control the selection of optimizer version. - // - // This parameter allows individual queries to pick different query - // optimizer versions. - // - // Specifying `latest` as a value instructs Cloud Spanner to use the - // latest supported query optimizer version. If not specified, Cloud Spanner - // uses the optimizer version set at the database level options. Any other - // positive integer (from the list of supported optimizer versions) - // overrides the default optimizer version for query execution. - // - // The list of supported optimizer versions can be queried from - // SPANNER_SYS.SUPPORTED_OPTIMIZER_VERSIONS. - // - // Executing a SQL statement with an invalid optimizer version fails with - // an `INVALID_ARGUMENT` error. - // - // See - // https://cloud.google.com/spanner/docs/query-optimizer/manage-query-optimizer - // for more information on managing the query optimizer. - // - // The `optimizer_version` statement hint has precedence over this setting. - string optimizer_version = 1; - - // An option to control the selection of optimizer statistics package. - // - // This parameter allows individual queries to use a different query - // optimizer statistics package. - // - // Specifying `latest` as a value instructs Cloud Spanner to use the latest - // generated statistics package. If not specified, Cloud Spanner uses - // the statistics package set at the database level options, or the latest - // package if the database option is not set. - // - // The statistics package requested by the query has to be exempt from - // garbage collection. This can be achieved with the following DDL - // statement: - // - // ``` - // ALTER STATISTICS SET OPTIONS (allow_gc=false) - // ``` - // - // The list of available statistics packages can be queried from - // `INFORMATION_SCHEMA.SPANNER_STATISTICS`. - // - // Executing a SQL statement with an invalid optimizer statistics package - // or with a statistics package that allows garbage collection fails with - // an `INVALID_ARGUMENT` error. - string optimizer_statistics_package = 2; - } - - // Mode in which the statement must be processed. - enum QueryMode { - // The default mode. Only the statement results are returned. - NORMAL = 0; - - // This mode returns only the query plan, without any results or - // execution statistics information. - PLAN = 1; - - // This mode returns both the query plan and the execution statistics along - // with the results. - PROFILE = 2; - } - - // Required. The session in which the SQL query should be performed. - string session = 1 [ - (google.api.field_behavior) = REQUIRED, - (google.api.resource_reference) = { - type: "spanner.googleapis.com/Session" - } - ]; - - // The transaction to use. - // - // For queries, if none is provided, the default is a temporary read-only - // transaction with strong concurrency. - // - // Standard DML statements require a read-write transaction. To protect - // against replays, single-use transactions are not supported. The caller - // must either supply an existing transaction ID or begin a new transaction. - // - // Partitioned DML requires an existing Partitioned DML transaction ID. - TransactionSelector transaction = 2; - - // Required. The SQL string. - string sql = 3 [(google.api.field_behavior) = REQUIRED]; - - // Parameter names and values that bind to placeholders in the SQL string. - // - // A parameter placeholder consists of the `@` character followed by the - // parameter name (for example, `@firstName`). Parameter names must conform - // to the naming requirements of identifiers as specified at - // https://cloud.google.com/spanner/docs/lexical#identifiers. - // - // Parameters can appear anywhere that a literal value is expected. The same - // parameter name can be used more than once, for example: - // - // `"WHERE id > @msg_id AND id < @msg_id + 100"` - // - // It is an error to execute a SQL statement with unbound parameters. - google.protobuf.Struct params = 4; - - // It is not always possible for Cloud Spanner to infer the right SQL type - // from a JSON value. For example, values of type `BYTES` and values - // of type `STRING` both appear in [params][google.spanner.v1.ExecuteSqlRequest.params] as JSON strings. - // - // In these cases, `param_types` can be used to specify the exact - // SQL type for some or all of the SQL statement parameters. See the - // definition of [Type][google.spanner.v1.Type] for more information - // about SQL types. - map param_types = 5; - - // If this request is resuming a previously interrupted SQL statement - // execution, `resume_token` should be copied from the last - // [PartialResultSet][google.spanner.v1.PartialResultSet] yielded before the interruption. Doing this - // enables the new SQL statement execution to resume where the last one left - // off. The rest of the request parameters must exactly match the - // request that yielded this token. - bytes resume_token = 6; - - // Used to control the amount of debugging information returned in - // [ResultSetStats][google.spanner.v1.ResultSetStats]. If [partition_token][google.spanner.v1.ExecuteSqlRequest.partition_token] is set, [query_mode][google.spanner.v1.ExecuteSqlRequest.query_mode] can only - // be set to [QueryMode.NORMAL][google.spanner.v1.ExecuteSqlRequest.QueryMode.NORMAL]. - QueryMode query_mode = 7; - - // If present, results will be restricted to the specified partition - // previously created using PartitionQuery(). There must be an exact - // match for the values of fields common to this message and the - // PartitionQueryRequest message used to create this partition_token. - bytes partition_token = 8; - - // A per-transaction sequence number used to identify this request. This field - // makes each request idempotent such that if the request is received multiple - // times, at most one will succeed. - // - // The sequence number must be monotonically increasing within the - // transaction. If a request arrives for the first time with an out-of-order - // sequence number, the transaction may be aborted. Replays of previously - // handled requests will yield the same response as the first execution. - // - // Required for DML statements. Ignored for queries. - int64 seqno = 9; - - // Query optimizer configuration to use for the given query. - QueryOptions query_options = 10; - - // Common options for this request. - RequestOptions request_options = 11; -} - -// The request for [ExecuteBatchDml][google.spanner.v1.Spanner.ExecuteBatchDml]. -message ExecuteBatchDmlRequest { - // A single DML statement. - message Statement { - // Required. The DML string. - string sql = 1; - - // Parameter names and values that bind to placeholders in the DML string. - // - // A parameter placeholder consists of the `@` character followed by the - // parameter name (for example, `@firstName`). Parameter names can contain - // letters, numbers, and underscores. - // - // Parameters can appear anywhere that a literal value is expected. The - // same parameter name can be used more than once, for example: - // - // `"WHERE id > @msg_id AND id < @msg_id + 100"` - // - // It is an error to execute a SQL statement with unbound parameters. - google.protobuf.Struct params = 2; - - // It is not always possible for Cloud Spanner to infer the right SQL type - // from a JSON value. For example, values of type `BYTES` and values - // of type `STRING` both appear in [params][google.spanner.v1.ExecuteBatchDmlRequest.Statement.params] as JSON strings. - // - // In these cases, `param_types` can be used to specify the exact - // SQL type for some or all of the SQL statement parameters. See the - // definition of [Type][google.spanner.v1.Type] for more information - // about SQL types. - map param_types = 3; - } - - // Required. The session in which the DML statements should be performed. - string session = 1 [ - (google.api.field_behavior) = REQUIRED, - (google.api.resource_reference) = { - type: "spanner.googleapis.com/Session" - } - ]; - - // Required. The transaction to use. Must be a read-write transaction. - // - // To protect against replays, single-use transactions are not supported. The - // caller must either supply an existing transaction ID or begin a new - // transaction. - TransactionSelector transaction = 2 [(google.api.field_behavior) = REQUIRED]; - - // Required. The list of statements to execute in this batch. Statements are executed - // serially, such that the effects of statement `i` are visible to statement - // `i+1`. Each statement must be a DML statement. Execution stops at the - // first failed statement; the remaining statements are not executed. - // - // Callers must provide at least one statement. - repeated Statement statements = 3 [(google.api.field_behavior) = REQUIRED]; - - // Required. A per-transaction sequence number used to identify this request. This field - // makes each request idempotent such that if the request is received multiple - // times, at most one will succeed. - // - // The sequence number must be monotonically increasing within the - // transaction. If a request arrives for the first time with an out-of-order - // sequence number, the transaction may be aborted. Replays of previously - // handled requests will yield the same response as the first execution. - int64 seqno = 4 [(google.api.field_behavior) = REQUIRED]; - - // Common options for this request. - RequestOptions request_options = 5; -} - -// The response for [ExecuteBatchDml][google.spanner.v1.Spanner.ExecuteBatchDml]. Contains a list -// of [ResultSet][google.spanner.v1.ResultSet] messages, one for each DML statement that has successfully -// executed, in the same order as the statements in the request. If a statement -// fails, the status in the response body identifies the cause of the failure. -// -// To check for DML statements that failed, use the following approach: -// -// 1. Check the status in the response message. The [google.rpc.Code][google.rpc.Code] enum -// value `OK` indicates that all statements were executed successfully. -// 2. If the status was not `OK`, check the number of result sets in the -// response. If the response contains `N` [ResultSet][google.spanner.v1.ResultSet] messages, then -// statement `N+1` in the request failed. -// -// Example 1: -// -// * Request: 5 DML statements, all executed successfully. -// * Response: 5 [ResultSet][google.spanner.v1.ResultSet] messages, with the status `OK`. -// -// Example 2: -// -// * Request: 5 DML statements. The third statement has a syntax error. -// * Response: 2 [ResultSet][google.spanner.v1.ResultSet] messages, and a syntax error (`INVALID_ARGUMENT`) -// status. The number of [ResultSet][google.spanner.v1.ResultSet] messages indicates that the third -// statement failed, and the fourth and fifth statements were not executed. -message ExecuteBatchDmlResponse { - // One [ResultSet][google.spanner.v1.ResultSet] for each statement in the request that ran successfully, - // in the same order as the statements in the request. Each [ResultSet][google.spanner.v1.ResultSet] does - // not contain any rows. The [ResultSetStats][google.spanner.v1.ResultSetStats] in each [ResultSet][google.spanner.v1.ResultSet] contain - // the number of rows modified by the statement. - // - // Only the first [ResultSet][google.spanner.v1.ResultSet] in the response contains valid - // [ResultSetMetadata][google.spanner.v1.ResultSetMetadata]. - repeated ResultSet result_sets = 1; - - // If all DML statements are executed successfully, the status is `OK`. - // Otherwise, the error status of the first failed statement. - google.rpc.Status status = 2; -} - -// Options for a PartitionQueryRequest and -// PartitionReadRequest. -message PartitionOptions { - // **Note:** This hint is currently ignored by PartitionQuery and - // PartitionRead requests. - // - // The desired data size for each partition generated. The default for this - // option is currently 1 GiB. This is only a hint. The actual size of each - // partition may be smaller or larger than this size request. - int64 partition_size_bytes = 1; - - // **Note:** This hint is currently ignored by PartitionQuery and - // PartitionRead requests. - // - // The desired maximum number of partitions to return. For example, this may - // be set to the number of workers available. The default for this option - // is currently 10,000. The maximum value is currently 200,000. This is only - // a hint. The actual number of partitions returned may be smaller or larger - // than this maximum count request. - int64 max_partitions = 2; -} - -// The request for [PartitionQuery][google.spanner.v1.Spanner.PartitionQuery] -message PartitionQueryRequest { - // Required. The session used to create the partitions. - string session = 1 [ - (google.api.field_behavior) = REQUIRED, - (google.api.resource_reference) = { - type: "spanner.googleapis.com/Session" - } - ]; - - // Read only snapshot transactions are supported, read/write and single use - // transactions are not. - TransactionSelector transaction = 2; - - // Required. The query request to generate partitions for. The request will fail if - // the query is not root partitionable. The query plan of a root - // partitionable query has a single distributed union operator. A distributed - // union operator conceptually divides one or more tables into multiple - // splits, remotely evaluates a subquery independently on each split, and - // then unions all results. - // - // This must not contain DML commands, such as INSERT, UPDATE, or - // DELETE. Use [ExecuteStreamingSql][google.spanner.v1.Spanner.ExecuteStreamingSql] with a - // PartitionedDml transaction for large, partition-friendly DML operations. - string sql = 3 [(google.api.field_behavior) = REQUIRED]; - - // Parameter names and values that bind to placeholders in the SQL string. - // - // A parameter placeholder consists of the `@` character followed by the - // parameter name (for example, `@firstName`). Parameter names can contain - // letters, numbers, and underscores. - // - // Parameters can appear anywhere that a literal value is expected. The same - // parameter name can be used more than once, for example: - // - // `"WHERE id > @msg_id AND id < @msg_id + 100"` - // - // It is an error to execute a SQL statement with unbound parameters. - google.protobuf.Struct params = 4; - - // It is not always possible for Cloud Spanner to infer the right SQL type - // from a JSON value. For example, values of type `BYTES` and values - // of type `STRING` both appear in [params][google.spanner.v1.PartitionQueryRequest.params] as JSON strings. - // - // In these cases, `param_types` can be used to specify the exact - // SQL type for some or all of the SQL query parameters. See the - // definition of [Type][google.spanner.v1.Type] for more information - // about SQL types. - map param_types = 5; - - // Additional options that affect how many partitions are created. - PartitionOptions partition_options = 6; -} - -// The request for [PartitionRead][google.spanner.v1.Spanner.PartitionRead] -message PartitionReadRequest { - // Required. The session used to create the partitions. - string session = 1 [ - (google.api.field_behavior) = REQUIRED, - (google.api.resource_reference) = { - type: "spanner.googleapis.com/Session" - } - ]; - - // Read only snapshot transactions are supported, read/write and single use - // transactions are not. - TransactionSelector transaction = 2; - - // Required. The name of the table in the database to be read. - string table = 3 [(google.api.field_behavior) = REQUIRED]; - - // If non-empty, the name of an index on [table][google.spanner.v1.PartitionReadRequest.table]. This index is - // used instead of the table primary key when interpreting [key_set][google.spanner.v1.PartitionReadRequest.key_set] - // and sorting result rows. See [key_set][google.spanner.v1.PartitionReadRequest.key_set] for further information. - string index = 4; - - // The columns of [table][google.spanner.v1.PartitionReadRequest.table] to be returned for each row matching - // this request. - repeated string columns = 5; - - // Required. `key_set` identifies the rows to be yielded. `key_set` names the - // primary keys of the rows in [table][google.spanner.v1.PartitionReadRequest.table] to be yielded, unless [index][google.spanner.v1.PartitionReadRequest.index] - // is present. If [index][google.spanner.v1.PartitionReadRequest.index] is present, then [key_set][google.spanner.v1.PartitionReadRequest.key_set] instead names - // index keys in [index][google.spanner.v1.PartitionReadRequest.index]. - // - // It is not an error for the `key_set` to name rows that do not - // exist in the database. Read yields nothing for nonexistent rows. - KeySet key_set = 6 [(google.api.field_behavior) = REQUIRED]; - - // Additional options that affect how many partitions are created. - PartitionOptions partition_options = 9; -} - -// Information returned for each partition returned in a -// PartitionResponse. -message Partition { - // This token can be passed to Read, StreamingRead, ExecuteSql, or - // ExecuteStreamingSql requests to restrict the results to those identified by - // this partition token. - bytes partition_token = 1; -} - -// The response for [PartitionQuery][google.spanner.v1.Spanner.PartitionQuery] -// or [PartitionRead][google.spanner.v1.Spanner.PartitionRead] -message PartitionResponse { - // Partitions created by this request. - repeated Partition partitions = 1; - - // Transaction created by this request. - Transaction transaction = 2; -} - -// The request for [Read][google.spanner.v1.Spanner.Read] and -// [StreamingRead][google.spanner.v1.Spanner.StreamingRead]. -message ReadRequest { - // Required. The session in which the read should be performed. - string session = 1 [ - (google.api.field_behavior) = REQUIRED, - (google.api.resource_reference) = { - type: "spanner.googleapis.com/Session" - } - ]; - - // The transaction to use. If none is provided, the default is a - // temporary read-only transaction with strong concurrency. - TransactionSelector transaction = 2; - - // Required. The name of the table in the database to be read. - string table = 3 [(google.api.field_behavior) = REQUIRED]; - - // If non-empty, the name of an index on [table][google.spanner.v1.ReadRequest.table]. This index is - // used instead of the table primary key when interpreting [key_set][google.spanner.v1.ReadRequest.key_set] - // and sorting result rows. See [key_set][google.spanner.v1.ReadRequest.key_set] for further information. - string index = 4; - - // Required. The columns of [table][google.spanner.v1.ReadRequest.table] to be returned for each row matching - // this request. - repeated string columns = 5 [(google.api.field_behavior) = REQUIRED]; - - // Required. `key_set` identifies the rows to be yielded. `key_set` names the - // primary keys of the rows in [table][google.spanner.v1.ReadRequest.table] to be yielded, unless [index][google.spanner.v1.ReadRequest.index] - // is present. If [index][google.spanner.v1.ReadRequest.index] is present, then [key_set][google.spanner.v1.ReadRequest.key_set] instead names - // index keys in [index][google.spanner.v1.ReadRequest.index]. - // - // If the [partition_token][google.spanner.v1.ReadRequest.partition_token] field is empty, rows are yielded - // in table primary key order (if [index][google.spanner.v1.ReadRequest.index] is empty) or index key order - // (if [index][google.spanner.v1.ReadRequest.index] is non-empty). If the [partition_token][google.spanner.v1.ReadRequest.partition_token] field is not - // empty, rows will be yielded in an unspecified order. - // - // It is not an error for the `key_set` to name rows that do not - // exist in the database. Read yields nothing for nonexistent rows. - KeySet key_set = 6 [(google.api.field_behavior) = REQUIRED]; - - // If greater than zero, only the first `limit` rows are yielded. If `limit` - // is zero, the default is no limit. A limit cannot be specified if - // `partition_token` is set. - int64 limit = 8; - - // If this request is resuming a previously interrupted read, - // `resume_token` should be copied from the last - // [PartialResultSet][google.spanner.v1.PartialResultSet] yielded before the interruption. Doing this - // enables the new read to resume where the last read left off. The - // rest of the request parameters must exactly match the request - // that yielded this token. - bytes resume_token = 9; - - // If present, results will be restricted to the specified partition - // previously created using PartitionRead(). There must be an exact - // match for the values of fields common to this message and the - // PartitionReadRequest message used to create this partition_token. - bytes partition_token = 10; - - // Common options for this request. - RequestOptions request_options = 11; -} - -// The request for [BeginTransaction][google.spanner.v1.Spanner.BeginTransaction]. -message BeginTransactionRequest { - // Required. The session in which the transaction runs. - string session = 1 [ - (google.api.field_behavior) = REQUIRED, - (google.api.resource_reference) = { - type: "spanner.googleapis.com/Session" - } - ]; - - // Required. Options for the new transaction. - TransactionOptions options = 2 [(google.api.field_behavior) = REQUIRED]; - - // Common options for this request. - // Priority is ignored for this request. Setting the priority in this - // request_options struct will not do anything. To set the priority for a - // transaction, set it on the reads and writes that are part of this - // transaction instead. - RequestOptions request_options = 3; -} - -// The request for [Commit][google.spanner.v1.Spanner.Commit]. -message CommitRequest { - // Required. The session in which the transaction to be committed is running. - string session = 1 [ - (google.api.field_behavior) = REQUIRED, - (google.api.resource_reference) = { - type: "spanner.googleapis.com/Session" - } - ]; - - // Required. The transaction in which to commit. - oneof transaction { - // Commit a previously-started transaction. - bytes transaction_id = 2; - - // Execute mutations in a temporary transaction. Note that unlike - // commit of a previously-started transaction, commit with a - // temporary transaction is non-idempotent. That is, if the - // `CommitRequest` is sent to Cloud Spanner more than once (for - // instance, due to retries in the application, or in the - // transport library), it is possible that the mutations are - // executed more than once. If this is undesirable, use - // [BeginTransaction][google.spanner.v1.Spanner.BeginTransaction] and - // [Commit][google.spanner.v1.Spanner.Commit] instead. - TransactionOptions single_use_transaction = 3; - } - - // The mutations to be executed when this transaction commits. All - // mutations are applied atomically, in the order they appear in - // this list. - repeated Mutation mutations = 4; - - // If `true`, then statistics related to the transaction will be included in - // the [CommitResponse][google.spanner.v1.CommitResponse.commit_stats]. Default value is - // `false`. - bool return_commit_stats = 5; - - // Common options for this request. - 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. - string session = 1 [ - (google.api.field_behavior) = REQUIRED, - (google.api.resource_reference) = { - type: "spanner.googleapis.com/Session" - } - ]; - - // Required. The transaction to roll back. - bytes transaction_id = 2 [(google.api.field_behavior) = REQUIRED]; -} diff --git a/google/cloud/spanner_v1/proto/transaction.proto b/google/cloud/spanner_v1/proto/transaction.proto deleted file mode 100644 index 7082c56258..0000000000 --- a/google/cloud/spanner_v1/proto/transaction.proto +++ /dev/null @@ -1,182 +0,0 @@ -// 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 = "TransactionProto"; -option java_package = "com.google.spanner.v1"; -option php_namespace = "Google\\Cloud\\Spanner\\V1"; -option ruby_package = "Google::Cloud::Spanner::V1"; - -// TransactionOptions are used to specify different types of transactions. -// -// For more info, see: https://cloud.google.com/spanner/docs/reference/rest/v1/Transaction -message TransactionOptions { - // Message type to initiate a read-write transaction. Currently this - // transaction type has no options. - message ReadWrite { - - } - - // Message type to initiate a Partitioned DML transaction. - message PartitionedDml { - - } - - // Message type to initiate a read-only transaction. - message ReadOnly { - // How to choose the timestamp for the read-only transaction. - oneof timestamp_bound { - // Read at a timestamp where all previously committed transactions - // are visible. - bool strong = 1; - - // Executes all reads at a timestamp >= `min_read_timestamp`. - // - // This is useful for requesting fresher data than some previous - // read, or data that is fresh enough to observe the effects of some - // previously committed transaction whose timestamp is known. - // - // Note that this option can only be used in single-use transactions. - // - // A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds. - // Example: `"2014-10-02T15:01:23.045123456Z"`. - google.protobuf.Timestamp min_read_timestamp = 2; - - // Read data at a timestamp >= `NOW - max_staleness` - // seconds. Guarantees that all writes that have committed more - // than the specified number of seconds ago are visible. Because - // Cloud Spanner chooses the exact timestamp, this mode works even if - // the client's local clock is substantially skewed from Cloud Spanner - // commit timestamps. - // - // Useful for reading the freshest data available at a nearby - // replica, while bounding the possible staleness if the local - // replica has fallen behind. - // - // Note that this option can only be used in single-use - // transactions. - google.protobuf.Duration max_staleness = 3; - - // Executes all reads at the given timestamp. Unlike other modes, - // reads at a specific timestamp are repeatable; the same read at - // the same timestamp always returns the same data. If the - // timestamp is in the future, the read will block until the - // specified timestamp, modulo the read's deadline. - // - // Useful for large scale consistent reads such as mapreduces, or - // for coordinating many reads against a consistent snapshot of the - // data. - // - // A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds. - // Example: `"2014-10-02T15:01:23.045123456Z"`. - google.protobuf.Timestamp read_timestamp = 4; - - // Executes all reads at a timestamp that is `exact_staleness` - // old. The timestamp is chosen soon after the read is started. - // - // Guarantees that all writes that have committed more than the - // specified number of seconds ago are visible. Because Cloud Spanner - // chooses the exact timestamp, this mode works even if the client's - // local clock is substantially skewed from Cloud Spanner commit - // timestamps. - // - // Useful for reading at nearby replicas without the distributed - // timestamp negotiation overhead of `max_staleness`. - google.protobuf.Duration exact_staleness = 5; - } - - // If true, the Cloud Spanner-selected read timestamp is included in - // the [Transaction][google.spanner.v1.Transaction] message that describes the transaction. - bool return_read_timestamp = 6; - } - - // Required. The type of transaction. - oneof mode { - // Transaction may write. - // - // Authorization to begin a read-write transaction requires - // `spanner.databases.beginOrRollbackReadWriteTransaction` permission - // on the `session` resource. - ReadWrite read_write = 1; - - // Partitioned DML transaction. - // - // Authorization to begin a Partitioned DML transaction requires - // `spanner.databases.beginPartitionedDmlTransaction` permission - // on the `session` resource. - PartitionedDml partitioned_dml = 3; - - // Transaction will not write. - // - // Authorization to begin a read-only transaction requires - // `spanner.databases.beginReadOnlyTransaction` permission - // on the `session` resource. - ReadOnly read_only = 2; - } -} - -// A transaction. -message Transaction { - // `id` may be used to identify the transaction in subsequent - // [Read][google.spanner.v1.Spanner.Read], - // [ExecuteSql][google.spanner.v1.Spanner.ExecuteSql], - // [Commit][google.spanner.v1.Spanner.Commit], or - // [Rollback][google.spanner.v1.Spanner.Rollback] calls. - // - // Single-use read-only transactions do not have IDs, because - // single-use transactions do not support multiple requests. - bytes id = 1; - - // For snapshot read-only transactions, the read timestamp chosen - // for the transaction. Not returned by default: see - // [TransactionOptions.ReadOnly.return_read_timestamp][google.spanner.v1.TransactionOptions.ReadOnly.return_read_timestamp]. - // - // A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds. - // Example: `"2014-10-02T15:01:23.045123456Z"`. - google.protobuf.Timestamp read_timestamp = 2; -} - -// This message is used to select the transaction in which a -// [Read][google.spanner.v1.Spanner.Read] or -// [ExecuteSql][google.spanner.v1.Spanner.ExecuteSql] call runs. -// -// See [TransactionOptions][google.spanner.v1.TransactionOptions] for more information about transactions. -message TransactionSelector { - // If no fields are set, the default is a single use transaction - // with strong concurrency. - oneof selector { - // Execute the read or SQL query in a temporary transaction. - // This is the most efficient way to execute a transaction that - // consists of a single SQL query. - TransactionOptions single_use = 1; - - // Execute the read or SQL query in a previously-started transaction. - bytes id = 2; - - // Begin a new transaction and execute this read or SQL query in - // it. The transaction ID of the new transaction is returned in - // [ResultSetMetadata.transaction][google.spanner.v1.ResultSetMetadata.transaction], which is a [Transaction][google.spanner.v1.Transaction]. - TransactionOptions begin = 3; - } -} diff --git a/google/cloud/spanner_v1/proto/type.proto b/google/cloud/spanner_v1/proto/type.proto deleted file mode 100644 index 4a5afd485d..0000000000 --- a/google/cloud/spanner_v1/proto/type.proto +++ /dev/null @@ -1,131 +0,0 @@ -// 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/api/field_behavior.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 = "TypeProto"; -option java_package = "com.google.spanner.v1"; -option php_namespace = "Google\\Cloud\\Spanner\\V1"; -option ruby_package = "Google::Cloud::Spanner::V1"; - -// `Type` indicates the type of a Cloud Spanner value, as might be stored in a -// table cell or returned from an SQL query. -message Type { - // Required. The [TypeCode][google.spanner.v1.TypeCode] for this type. - TypeCode code = 1 [(google.api.field_behavior) = REQUIRED]; - - // If [code][google.spanner.v1.Type.code] == [ARRAY][google.spanner.v1.TypeCode.ARRAY], then `array_element_type` - // is the type of the array elements. - Type array_element_type = 2; - - // If [code][google.spanner.v1.Type.code] == [STRUCT][google.spanner.v1.TypeCode.STRUCT], then `struct_type` - // provides type information for the struct's fields. - StructType struct_type = 3; -} - -// `StructType` defines the fields of a [STRUCT][google.spanner.v1.TypeCode.STRUCT] type. -message StructType { - // Message representing a single field of a struct. - message Field { - // The name of the field. For reads, this is the column name. For - // SQL queries, it is the column alias (e.g., `"Word"` in the - // query `"SELECT 'hello' AS Word"`), or the column name (e.g., - // `"ColName"` in the query `"SELECT ColName FROM Table"`). Some - // columns might have an empty name (e.g., `"SELECT - // UPPER(ColName)"`). Note that a query result can contain - // multiple fields with the same name. - string name = 1; - - // The type of the field. - Type type = 2; - } - - // The list of fields that make up this struct. Order is - // significant, because values of this struct type are represented as - // lists, where the order of field values matches the order of - // fields in the [StructType][google.spanner.v1.StructType]. In turn, the order of fields - // matches the order of columns in a read request, or the order of - // fields in the `SELECT` clause of a query. - repeated Field fields = 1; -} - -// `TypeCode` is used as part of [Type][google.spanner.v1.Type] to -// indicate the type of a Cloud Spanner value. -// -// Each legal value of a type can be encoded to or decoded from a JSON -// value, using the encodings described below. All Cloud Spanner values can -// be `null`, regardless of type; `null`s are always encoded as a JSON -// `null`. -enum TypeCode { - // Not specified. - TYPE_CODE_UNSPECIFIED = 0; - - // Encoded as JSON `true` or `false`. - BOOL = 1; - - // Encoded as `string`, in decimal format. - INT64 = 2; - - // Encoded as `number`, or the strings `"NaN"`, `"Infinity"`, or - // `"-Infinity"`. - FLOAT64 = 3; - - // Encoded as `string` in RFC 3339 timestamp format. The time zone - // must be present, and must be `"Z"`. - // - // If the schema has the column option - // `allow_commit_timestamp=true`, the placeholder string - // `"spanner.commit_timestamp()"` can be used to instruct the system - // to insert the commit timestamp associated with the transaction - // commit. - TIMESTAMP = 4; - - // Encoded as `string` in RFC 3339 date format. - DATE = 5; - - // Encoded as `string`. - STRING = 6; - - // Encoded as a base64-encoded `string`, as described in RFC 4648, - // section 4. - BYTES = 7; - - // Encoded as `list`, where the list elements are represented - // according to - // [array_element_type][google.spanner.v1.Type.array_element_type]. - ARRAY = 8; - - // Encoded as `list`, where list element `i` is represented according - // to [struct_type.fields[i]][google.spanner.v1.StructType.fields]. - STRUCT = 9; - - // Encoded as `string`, in decimal format or scientific notation format. - //
Decimal format: - //
`[+-]Digits[.[Digits]]` or - //
`[+-][Digits].Digits` - // - // Scientific notation: - //
`[+-]Digits[.[Digits]][ExponentIndicator[+-]Digits]` or - //
`[+-][Digits].Digits[ExponentIndicator[+-]Digits]` - //
(ExponentIndicator is `"e"` or `"E"`) - NUMERIC = 10; -}