diff --git a/librarian.yaml b/librarian.yaml
index 1a538d4e020e..9a1051636f65 100644
--- a/librarian.yaml
+++ b/librarian.yaml
@@ -12,7 +12,7 @@
# See the License for the specific language governing permissions and
# limitations under the License.
language: nodejs
-version: v0.24.0
+version: v0.25.0
repo: googleapis/google-cloud-node
sources:
googleapis:
@@ -1527,6 +1527,16 @@ libraries:
copyright_year: "2026"
nodejs:
default_version: v1
+ - name: google-cloud-spanner-api
+ version: 1.0.0
+ apis:
+ - path: google/spanner/v1
+ - path: google/spanner/executor/v1
+ - path: google/spanner/admin/database/v1
+ - path: google/spanner/admin/instance/v1
+ copyright_year: "2026"
+ nodejs:
+ package_name: '@google-cloud/spanner-api'
- name: google-cloud-speech
version: 7.5.0
apis:
diff --git a/packages/google-cloud-spanner-api/.gitignore b/packages/google-cloud-spanner-api/.gitignore
new file mode 100644
index 000000000000..d4f03a0df2e8
--- /dev/null
+++ b/packages/google-cloud-spanner-api/.gitignore
@@ -0,0 +1,14 @@
+**/*.log
+**/node_modules
+/.coverage
+/coverage
+/.nyc_output
+/docs/
+/out/
+/build/
+system-test/secrets.js
+system-test/*key.json
+*.lock
+.DS_Store
+package-lock.json
+__pycache__
diff --git a/packages/google-cloud-spanner-api/.jsdoc.js b/packages/google-cloud-spanner-api/.jsdoc.js
new file mode 100644
index 000000000000..924c3d57eb55
--- /dev/null
+++ b/packages/google-cloud-spanner-api/.jsdoc.js
@@ -0,0 +1,55 @@
+// Copyright 2026 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
+//
+// https://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.
+//
+// ** This file is automatically generated by gapic-generator-typescript. **
+// ** https://github.com/googleapis/gapic-generator-typescript **
+// ** All changes to this file may be overwritten. **
+
+'use strict';
+
+module.exports = {
+ opts: {
+ readme: './README.md',
+ package: './package.json',
+ template: './node_modules/jsdoc-fresh',
+ recurse: true,
+ verbose: true,
+ destination: './docs/'
+ },
+ plugins: [
+ 'plugins/markdown',
+ 'jsdoc-region-tag'
+ ],
+ source: {
+ excludePattern: '(^|\\/|\\\\)[._]',
+ include: [
+ 'build/src',
+ 'protos'
+ ],
+ includePattern: '\\.js$'
+ },
+ templates: {
+ copyright: 'Copyright 2026 Google LLC',
+ includeDate: false,
+ sourceFiles: false,
+ systemName: '@google-cloud/spanner-api',
+ theme: 'lumen',
+ default: {
+ outputSourceFiles: false
+ }
+ },
+ markdown: {
+ idInHeadings: true
+ }
+};
diff --git a/packages/google-cloud-spanner-api/.nycrc b/packages/google-cloud-spanner-api/.nycrc
new file mode 100644
index 000000000000..81a95fc94b00
--- /dev/null
+++ b/packages/google-cloud-spanner-api/.nycrc
@@ -0,0 +1,24 @@
+{
+ "report-dir": "./.coverage",
+ "reporter": ["text", "lcov"],
+ "exclude": [
+ "**/*-test",
+ "**/.coverage",
+ "**/apis",
+ "**/benchmark",
+ "**/conformance",
+ "**/docs",
+ "**/samples",
+ "**/scripts",
+ "**/protos",
+ "**/test",
+ "**/*.d.ts",
+ ".jsdoc.js",
+ "**/.jsdoc.js",
+ "karma.conf.js",
+ "webpack-tests.config.js",
+ "webpack.config.js"
+ ],
+ "exclude-after-remap": false,
+ "all": true
+}
\ No newline at end of file
diff --git a/packages/google-cloud-spanner-api/.repo-metadata.json b/packages/google-cloud-spanner-api/.repo-metadata.json
new file mode 100644
index 000000000000..109b79d6909d
--- /dev/null
+++ b/packages/google-cloud-spanner-api/.repo-metadata.json
@@ -0,0 +1,16 @@
+{
+ "api_description": "Cloud Spanner is a managed, mission-critical, globally consistent and\nscalable relational database service.",
+ "api_id": "spanner.googleapis.com",
+ "api_shortname": "spanner",
+ "client_documentation": "https://cloud.google.com/nodejs/docs/reference/spanner-api/latest",
+ "default_version": "v1",
+ "distribution_name": "@google-cloud/spanner-api",
+ "issue_tracker": "https://issuetracker.google.com/issues/new?component=190851&template=0",
+ "language": "nodejs",
+ "library_type": "GAPIC_AUTO",
+ "name": "spanner",
+ "name_pretty": "Cloud Spanner",
+ "product_documentation": "https://cloud.google.com/spanner/docs",
+ "release_level": "stable",
+ "repo": "googleapis/google-cloud-node"
+}
\ No newline at end of file
diff --git a/packages/google-cloud-spanner-api/README.md b/packages/google-cloud-spanner-api/README.md
new file mode 100644
index 000000000000..e8f4d56e781e
--- /dev/null
+++ b/packages/google-cloud-spanner-api/README.md
@@ -0,0 +1,108 @@
+[//]: # "This README.md file is auto-generated, all changes to this file will be lost."
+[//]: # "The comments you see below are used to generate those parts of the template in later states."
+
+
+# [Cloud Spanner API: Nodejs Client][homepage]
+
+[//]: # "releaseLevel"
+
+[](https://www.npmjs.org/package/@google-cloud/spanner-api)
+
+Cloud Spanner API client for Node.js
+
+[//]: # "partials.introduction"
+
+A comprehensive list of changes in each version may be found in
+[the CHANGELOG][homepage_changelog].
+
+* [Cloud Spanner API Nodejs Client API Reference](https://cloud.google.com/nodejs/docs/reference/instance/latest)
+* [Cloud Spanner API Documentation](https://cloud.google.com/spanner/)
+
+Read more about the client libraries for Cloud APIs, including the older
+Google APIs Client Libraries, in [Client Libraries Explained][explained].
+
+[explained]: https://cloud.google.com/apis/docs/client-libraries-explained
+
+**Table of contents:**
+
+* [Quickstart](#quickstart)
+ * [Before you begin](#before-you-begin)
+ * [Installing the client library](#installing-the-client-library)
+
+* [Versioning](#versioning)
+* [Contributing](#contributing)
+* [License](#license)
+
+## Quickstart
+### Before you begin
+
+1. [Select or create a Cloud Platform project][projects].
+1. [Enable billing for your project][billing].
+1. [Enable the Cloud Spanner API API][enable_api].
+1. [Set up authentication][auth] so you can access the
+ API from your local workstation.
+### Installing the client library
+
+```bash
+npm install @google-cloud/spanner-api
+```
+
+[//]: # "partials.body"
+
+## Samples
+
+Samples are in the [`samples/`][homepage_samples] directory. Each sample's `README.md` has instructions for running its sample.
+
+[//]: # "samples"
+
+## Supported Node.js Versions
+
+Our client libraries follow the [Node.js release schedule](https://github.com/nodejs/release#release-schedule).
+Libraries are compatible with all current _active_ and _maintenance_ versions of
+Node.js.
+If you are using an end-of-life version of Node.js, we recommend that you update
+as soon as possible to an actively supported LTS version.
+
+Google's client libraries support legacy versions of Node.js runtimes on a
+best-efforts basis with the following warnings:
+
+* Legacy versions are not tested in continuous integration.
+* Some security patches and features cannot be backported.
+* Dependencies cannot be kept up-to-date.
+
+Client libraries targeting some end-of-life versions of Node.js are available, and
+can be installed through npm [dist-tags](https://docs.npmjs.com/cli/dist-tag).
+The dist-tags follow the naming convention `legacy-(version)`.
+For example, `npm install @google-cloud/spanner-api@legacy-8` installs client libraries
+for versions compatible with Node.js 8.
+
+## Versioning
+
+This library follows [Semantic Versioning](http://semver.org/).
+
+More Information: [Google Cloud Platform Launch Stages][launch_stages]
+
+[launch_stages]: https://cloud.google.com/terms/launch-stages
+
+## Contributing
+
+Contributions welcome! See the [Contributing Guide](https://github.com/googleapis/google-cloud-node/blob/main/CONTRIBUTING.md).
+
+Please note that this `README.md`
+and a variety of configuration files in this repository (including `.nycrc` and `tsconfig.json`)
+are generated from a central template.
+
+## License
+
+Apache Version 2.0
+
+See [LICENSE](https://github.com/googleapis/google-cloud-node/blob/main/LICENSE)
+
+[shell_img]: https://gstatic.com/cloudssh/images/open-btn.png
+[projects]: https://console.cloud.google.com/project
+[billing]: https://support.google.com/cloud/answer/6293499#enable-billing
+[enable_api]: https://console.cloud.google.com/flows/enableapi?apiid=spanner.googleapis.com
+[auth]: https://cloud.google.com/docs/authentication/external/set-up-adc-local
+[homepage_samples]: https://github.com/googleapis/google-cloud-node/blob/main/packages/google-spanner-admin-instance/samples
+[homepage_changelog]: https://github.com/googleapis/google-cloud-node/blob/main/packages/google-spanner-admin-instance/CHANGELOG.md
+[homepage]: https://github.com/googleapis/google-cloud-node/blob/main/packages/google-spanner-admin-instance
diff --git a/packages/google-cloud-spanner-api/package.json b/packages/google-cloud-spanner-api/package.json
new file mode 100644
index 000000000000..fdb036b90061
--- /dev/null
+++ b/packages/google-cloud-spanner-api/package.json
@@ -0,0 +1,62 @@
+{
+ "name": "@google-cloud/spanner-api",
+ "version": "0.1.0",
+ "description": "Instance client for Node.js",
+ "repository": {
+ "type": "git",
+ "directory": "packages/google-cloud-spanner-api",
+ "url": "https://github.com/googleapis/google-cloud-node.git"
+ },
+ "license": "Apache-2.0",
+ "author": "Google LLC",
+ "main": "build/src/index.js",
+ "files": [
+ "build/src",
+ "build/protos"
+ ],
+ "keywords": [
+ "google apis client",
+ "google api client",
+ "google apis",
+ "google api",
+ "google",
+ "google cloud platform",
+ "google cloud",
+ "cloud",
+ "google instance",
+ "instance",
+ "instance admin"
+ ],
+ "scripts": {
+ "clean": "gts clean",
+ "compile": "tsc -p . && cp -r protos build/ && minifyProtoJson",
+ "compile-protos": "compileProtos src",
+ "docs": "jsdoc -c .jsdoc.js",
+ "fix": "gts fix",
+ "lint": "gts check",
+ "prepare": "npm run compile-protos && npm run compile",
+ "system-test": "c8 mocha --config ../../.mocharc.cjs --no-parallel build/system-test",
+ "test": "c8 mocha --config ../../.mocharc.cjs build/test"
+ },
+ "dependencies": {
+ "google-gax": "^5.1.1-rc.1"
+ },
+ "devDependencies": {
+ "@types/mocha": "^10.0.10",
+ "@types/node": "^22.18.12",
+ "@types/sinon": "^20.0.0",
+ "c8": "^10.1.3",
+ "gapic-tools": "^1.0.3",
+ "gts": "^6.0.2",
+ "jsdoc": "^4.0.5",
+ "jsdoc-fresh": "^5.0.2",
+ "jsdoc-region-tag": "^4.0.1",
+ "mocha": "^11.7.4",
+ "pack-n-play": "^4.2.1",
+ "typescript": "5.8.3",
+ "sinon": "^20.0.0"
+ },
+ "engines": {
+ "node": ">=18"
+ }
+}
diff --git a/packages/google-cloud-spanner-api/protos/google/spanner/admin/database/v1/backup.proto b/packages/google-cloud-spanner-api/protos/google/spanner/admin/database/v1/backup.proto
new file mode 100644
index 000000000000..6898814c4217
--- /dev/null
+++ b/packages/google-cloud-spanner-api/protos/google/spanner/admin/database/v1/backup.proto
@@ -0,0 +1,773 @@
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+syntax = "proto3";
+
+package google.spanner.admin.database.v1;
+
+import "google/api/field_behavior.proto";
+import "google/api/resource.proto";
+import "google/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 = "cloud.google.com/go/spanner/admin/database/apiv1/databasepb;databasepb";
+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 number of bytes that will be freed by deleting this
+ // backup. This value will be zero if, for example, this backup is part of an
+ // incremental backup chain and younger backups in the chain require that we
+ // keep its data. For backups not in an incremental backup chain, this is
+ // always the size of the backup. This value may change if backups on the same
+ // chain get created, deleted or expired.
+ int64 freeable_size_bytes = 15 [(google.api.field_behavior) = OUTPUT_ONLY];
+
+ // Output only. For a backup in an incremental backup chain, this is the
+ // storage space needed to keep the data that has changed since the previous
+ // backup. For all other backups, this is always the size of the backup. This
+ // value may change if backups on the same chain get deleted or expired.
+ //
+ // This field can be used to calculate the total storage space used by a set
+ // of backups. For example, the total space used by all backups of a database
+ // can be computed by summing up this field.
+ int64 exclusive_size_bytes = 16 [(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];
+
+ // Output only. The encryption information for the backup, whether it is
+ // protected by one or more KMS keys. The information includes all Cloud
+ // KMS key versions used to encrypt the backup. The `encryption_status' field
+ // inside of each `EncryptionInfo` is not populated. At least one of the key
+ // versions must be available for the backup to be restored. If a key version
+ // is revoked in the middle of a restore, the restore behavior is undefined.
+ repeated EncryptionInfo encryption_information = 13
+ [(google.api.field_behavior) = OUTPUT_ONLY];
+
+ // Output only. The database dialect information for the backup.
+ DatabaseDialect database_dialect = 10
+ [(google.api.field_behavior) = OUTPUT_ONLY];
+
+ // Output only. The names of the destination backups being created by copying
+ // this source backup. The backup names are of the form
+ // `projects//instances//backups/`.
+ // Referencing backups may exist in different instances. The existence of
+ // any referencing backup prevents the backup from being deleted. When the
+ // copy operation is done (either successfully completed or cancelled or the
+ // destination backup is deleted), the reference to the backup is removed.
+ repeated string referencing_backups = 11 [
+ (google.api.field_behavior) = OUTPUT_ONLY,
+ (google.api.resource_reference) = { type: "spanner.googleapis.com/Backup" }
+ ];
+
+ // Output only. The max allowed expiration time of the backup, with
+ // microseconds granularity. A backup's expiration time can be configured in
+ // multiple APIs: CreateBackup, UpdateBackup, CopyBackup. When updating or
+ // copying an existing backup, the expiration time specified must be
+ // less than `Backup.max_expire_time`.
+ google.protobuf.Timestamp max_expire_time = 12
+ [(google.api.field_behavior) = OUTPUT_ONLY];
+
+ // Output only. List of backup schedule URIs that are associated with
+ // creating this backup. This is only applicable for scheduled backups, and
+ // is empty for on-demand backups.
+ //
+ // To optimize for storage, whenever possible, multiple schedules are
+ // collapsed together to create one backup. In such cases, this field captures
+ // the list of all backup schedule URIs that are associated with creating
+ // this backup. If collapsing is not done, then this field captures the
+ // single backup schedule URI associated with creating this backup.
+ repeated string backup_schedules = 14 [
+ (google.api.field_behavior) = OUTPUT_ONLY,
+ (google.api.resource_reference) = {
+ type: "spanner.googleapis.com/BackupSchedule"
+ }
+ ];
+
+ // Output only. Populated only for backups in an incremental backup chain.
+ // Backups share the same chain id if and only if they belong to the same
+ // incremental backup chain. Use this field to determine which backups are
+ // part of the same incremental backup chain. The ordering of backups in the
+ // chain can be determined by ordering the backup `version_time`.
+ string incremental_backup_chain_id = 17
+ [(google.api.field_behavior) = OUTPUT_ONLY];
+
+ // Output only. Data deleted at a time older than this is guaranteed not to be
+ // retained in order to support this backup. For a backup in an incremental
+ // backup chain, this is the version time of the oldest backup that exists or
+ // ever existed in the chain. For all other backups, this is the version time
+ // of the backup. This field can be used to understand what data is being
+ // retained by the backup system.
+ google.protobuf.Timestamp oldest_version_time = 18
+ [(google.api.field_behavior) = OUTPUT_ONLY];
+
+ // Output only. The instance partition(s) storing the backup.
+ //
+ // This is the same as the list of the instance partition(s) that the database
+ // had footprint in at the backup's `version_time`.
+ repeated BackupInstancePartition instance_partitions = 19
+ [(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
+// [CopyBackup][google.spanner.admin.database.v1.DatabaseAdmin.CopyBackup].
+message CopyBackupRequest {
+ // Required. The name of the destination instance that will contain the backup
+ // copy. 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 copy.
+ // The `backup_id` appended to `parent` forms the full backup_uri of the form
+ // `projects//instances//backups/`.
+ string backup_id = 2 [(google.api.field_behavior) = REQUIRED];
+
+ // Required. The source backup to be copied.
+ // The source backup needs to be in READY state for it to be copied.
+ // Once CopyBackup is in progress, the source backup cannot be deleted or
+ // cleaned up on expiration until CopyBackup is finished.
+ // Values are of the form:
+ // `projects//instances//backups/`.
+ string source_backup = 3 [
+ (google.api.field_behavior) = REQUIRED,
+ (google.api.resource_reference) = { type: "spanner.googleapis.com/Backup" }
+ ];
+
+ // Required. The expiration time of the backup in microsecond granularity.
+ // The expiration time must be at least 6 hours and at most 366 days
+ // from the `create_time` of the source backup. 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 = 4
+ [(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 source backup by default, namely
+ // [encryption_type][google.spanner.admin.database.v1.CopyBackupEncryptionConfig.encryption_type]
+ // = `USE_CONFIG_DEFAULT_OR_BACKUP_ENCRYPTION`.
+ CopyBackupEncryptionConfig encryption_config = 5
+ [(google.api.field_behavior) = OPTIONAL];
+}
+
+// Metadata type for the operation returned by
+// [CopyBackup][google.spanner.admin.database.v1.DatabaseAdmin.CopyBackup].
+message CopyBackupMetadata {
+ // The name of the backup being created through the copy operation.
+ // Values are of the form
+ // `projects//instances//backups/`.
+ string name = 1 [
+ (google.api.resource_reference) = { type: "spanner.googleapis.com/Backup" }
+ ];
+
+ // The name of the source backup that is being copied.
+ // Values are of the form
+ // `projects//instances//backups/`.
+ string source_backup = 2 [
+ (google.api.resource_reference) = { type: "spanner.googleapis.com/Backup" }
+ ];
+
+ // The progress of the
+ // [CopyBackup][google.spanner.admin.database.v1.DatabaseAdmin.CopyBackup]
+ // operation.
+ OperationProgress progress = 3;
+
+ // The time at which cancellation of CopyBackup 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`
+ // * `backup_schedules`
+ //
+ // 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
+ // * `backup_schedules:daily`
+ // - The backup is created from a schedule with "daily" in its name.
+ 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.
+ // `metadata.@type` must be specified first if filtering on metadata
+ // fields.
+ // * `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.@type=type.googleapis.com/google.spanner.admin.database.v1.CreateBackupMetadata) AND` \
+ // `metadata.database:prod` - Returns operations where:
+ // * The operation's metadata type is
+ // [CreateBackupMetadata][google.spanner.admin.database.v1.CreateBackupMetadata].
+ // * The source database name of backup contains 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.
+ // * `(metadata.@type=type.googleapis.com/google.spanner.admin.database.v1.CopyBackupMetadata) AND` \
+ // `(metadata.source_backup:test) AND` \
+ // `(metadata.progress.start_time < \"2022-01-18T14:50:00Z\") AND` \
+ // `(error:*)` - Returns operations where:
+ // * The operation's metadata type is
+ // [CopyBackupMetadata][google.spanner.admin.database.v1.CopyBackupMetadata].
+ // * The source backup name contains the string "test".
+ // * The operation started before 2022-01-18T14:50:00Z.
+ // * The operation resulted in an error.
+ // * `((metadata.@type=type.googleapis.com/google.spanner.admin.database.v1.CreateBackupMetadata) AND` \
+ // `(metadata.database:test_db)) OR` \
+ // `((metadata.@type=type.googleapis.com/google.spanner.admin.database.v1.CopyBackupMetadata)
+ // AND` \
+ // `(metadata.source_backup:test_bkp)) AND` \
+ // `(error:*)` - Returns operations where:
+ // * The operation's metadata matches either of criteria:
+ // * The operation's metadata type is
+ // [CreateBackupMetadata][google.spanner.admin.database.v1.CreateBackupMetadata]
+ // AND the source database name of the backup contains the string
+ // "test_db"
+ // * The operation's metadata type is
+ // [CopyBackupMetadata][google.spanner.admin.database.v1.CopyBackupMetadata]
+ // AND the source backup name contains the string "test_bkp"
+ // * 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. The operation's
+ // [metadata][google.longrunning.Operation.metadata] field type
+ // `metadata.type_url` describes the type of the metadata. 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"
+ }
+ ];
+
+ // Optional. Specifies the KMS configuration for the one or more keys used to
+ // protect the backup. Values are of the form
+ // `projects//locations//keyRings//cryptoKeys/`.
+ //
+ // The keys referenced by kms_key_names must fully cover all
+ // regions of the backup's instance configuration. Some examples:
+ // * For single region instance configs, specify a single regional
+ // location KMS key.
+ // * For multi-regional instance configs of type GOOGLE_MANAGED,
+ // either specify a multi-regional location KMS key or multiple regional
+ // location KMS keys that cover all regions in the instance config.
+ // * For an instance config of type USER_MANAGED, please specify only
+ // regional location KMS keys to cover each region in the instance config.
+ // Multi-regional location KMS keys are not supported for USER_MANAGED
+ // instance configs.
+ repeated string kms_key_names = 3 [
+ (google.api.field_behavior) = OPTIONAL,
+ (google.api.resource_reference) = {
+ type: "cloudkms.googleapis.com/CryptoKey"
+ }
+ ];
+}
+
+// Encryption configuration for the copied backup.
+message CopyBackupEncryptionConfig {
+ // Encryption types for the backup.
+ enum EncryptionType {
+ // Unspecified. Do not use.
+ ENCRYPTION_TYPE_UNSPECIFIED = 0;
+
+ // This is the default option for
+ // [CopyBackup][google.spanner.admin.database.v1.DatabaseAdmin.CopyBackup]
+ // when
+ // [encryption_config][google.spanner.admin.database.v1.CopyBackupEncryptionConfig]
+ // is not specified. For example, if the source backup is using
+ // `Customer_Managed_Encryption`, the backup will be using the same Cloud
+ // KMS key as the source backup.
+ USE_CONFIG_DEFAULT_OR_BACKUP_ENCRYPTION = 1;
+
+ // Use Google default encryption.
+ GOOGLE_DEFAULT_ENCRYPTION = 2;
+
+ // Use customer managed encryption. If specified, either `kms_key_name` or
+ // `kms_key_names` must contain valid Cloud KMS key(s).
+ 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.CopyBackupEncryptionConfig.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"
+ }
+ ];
+
+ // Optional. Specifies the KMS configuration for the one or more keys used to
+ // protect the backup. Values are of the form
+ // `projects//locations//keyRings//cryptoKeys/`.
+ // Kms keys specified can be in any order.
+ //
+ // The keys referenced by kms_key_names must fully cover all
+ // regions of the backup's instance configuration. Some examples:
+ // * For single region instance configs, specify a single regional
+ // location KMS key.
+ // * For multi-regional instance configs of type GOOGLE_MANAGED,
+ // either specify a multi-regional location KMS key or multiple regional
+ // location KMS keys that cover all regions in the instance config.
+ // * For an instance config of type USER_MANAGED, please specify only
+ // regional location KMS keys to cover each region in the instance config.
+ // Multi-regional location KMS keys are not supported for USER_MANAGED
+ // instance configs.
+ repeated string kms_key_names = 3 [
+ (google.api.field_behavior) = OPTIONAL,
+ (google.api.resource_reference) = {
+ type: "cloudkms.googleapis.com/CryptoKey"
+ }
+ ];
+}
+
+// The specification for full backups.
+// A full backup stores the entire contents of the database at a given
+// version time.
+message FullBackupSpec {}
+
+// The specification for incremental backup chains.
+// An incremental backup stores the delta of changes between a previous
+// backup and the database contents at a given version time. An
+// incremental backup chain consists of a full backup and zero or more
+// successive incremental backups. The first backup created for an
+// incremental backup chain is always a full backup.
+message IncrementalBackupSpec {}
+
+// Instance partition information for the backup.
+message BackupInstancePartition {
+ // A unique identifier for the instance partition. Values are of the form
+ // `projects//instances//instancePartitions/`
+ string instance_partition = 1 [(google.api.resource_reference) = {
+ type: "spanner.googleapis.com/InstancePartition"
+ }];
+}
diff --git a/packages/google-cloud-spanner-api/protos/google/spanner/admin/database/v1/backup_schedule.proto b/packages/google-cloud-spanner-api/protos/google/spanner/admin/database/v1/backup_schedule.proto
new file mode 100644
index 000000000000..c273516ae093
--- /dev/null
+++ b/packages/google-cloud-spanner-api/protos/google/spanner/admin/database/v1/backup_schedule.proto
@@ -0,0 +1,230 @@
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+syntax = "proto3";
+
+package google.spanner.admin.database.v1;
+
+import "google/api/field_behavior.proto";
+import "google/api/resource.proto";
+import "google/protobuf/duration.proto";
+import "google/protobuf/field_mask.proto";
+import "google/protobuf/timestamp.proto";
+import "google/spanner/admin/database/v1/backup.proto";
+
+option csharp_namespace = "Google.Cloud.Spanner.Admin.Database.V1";
+option go_package = "cloud.google.com/go/spanner/admin/database/apiv1/databasepb;databasepb";
+option java_multiple_files = true;
+option java_outer_classname = "BackupScheduleProto";
+option java_package = "com.google.spanner.admin.database.v1";
+option php_namespace = "Google\\Cloud\\Spanner\\Admin\\Database\\V1";
+option ruby_package = "Google::Cloud::Spanner::Admin::Database::V1";
+
+// Defines specifications of the backup schedule.
+message BackupScheduleSpec {
+ // Required.
+ oneof schedule_spec {
+ // Cron style schedule specification.
+ CrontabSpec cron_spec = 1;
+ }
+}
+
+// BackupSchedule expresses the automated backup creation specification for a
+// Spanner database.
+// Next ID: 10
+message BackupSchedule {
+ option (google.api.resource) = {
+ type: "spanner.googleapis.com/BackupSchedule"
+ pattern: "projects/{project}/instances/{instance}/databases/{database}/backupSchedules/{schedule}"
+ plural: "backupSchedules"
+ singular: "backupSchedule"
+ };
+
+ // Identifier. Output only for the
+ // [CreateBackupSchedule][DatabaseAdmin.CreateBackupSchededule] operation.
+ // Required for the
+ // [UpdateBackupSchedule][google.spanner.admin.database.v1.DatabaseAdmin.UpdateBackupSchedule]
+ // operation. A globally unique identifier for the backup schedule which
+ // cannot be changed. Values are of the form
+ // `projects//instances//databases//backupSchedules/[a-z][a-z0-9_\-]*[a-z0-9]`
+ // The final segment of the name must be between 2 and 60 characters in
+ // length.
+ string name = 1 [(google.api.field_behavior) = IDENTIFIER];
+
+ // Optional. The schedule specification based on which the backup creations
+ // are triggered.
+ BackupScheduleSpec spec = 6 [(google.api.field_behavior) = OPTIONAL];
+
+ // Optional. The retention duration of a backup that must be at least 6 hours
+ // and at most 366 days. The backup is eligible to be automatically deleted
+ // once the retention period has elapsed.
+ google.protobuf.Duration retention_duration = 3
+ [(google.api.field_behavior) = OPTIONAL];
+
+ // Optional. The encryption configuration that will be used to encrypt the
+ // backup. If this field is not specified, the backup will use the same
+ // encryption configuration as the database.
+ CreateBackupEncryptionConfig encryption_config = 4
+ [(google.api.field_behavior) = OPTIONAL];
+
+ // Required. Backup type spec determines the type of backup that is created by
+ // the backup schedule. Currently, only full backups are supported.
+ oneof backup_type_spec {
+ // The schedule creates only full backups.
+ FullBackupSpec full_backup_spec = 7;
+
+ // The schedule creates incremental backup chains.
+ IncrementalBackupSpec incremental_backup_spec = 8;
+ }
+
+ // Output only. The timestamp at which the schedule was last updated.
+ // If the schedule has never been updated, this field contains the timestamp
+ // when the schedule was first created.
+ google.protobuf.Timestamp update_time = 9
+ [(google.api.field_behavior) = OUTPUT_ONLY];
+}
+
+// CrontabSpec can be used to specify the version time and frequency at
+// which the backup should be created.
+message CrontabSpec {
+ // Required. Textual representation of the crontab. User can customize the
+ // backup frequency and the backup version time using the cron
+ // expression. The version time must be in UTC timezone.
+ //
+ // The backup will contain an externally consistent copy of the
+ // database at the version time. Allowed frequencies are 12 hour, 1 day,
+ // 1 week and 1 month. Examples of valid cron specifications:
+ // * `0 2/12 * * * ` : every 12 hours at (2, 14) hours past midnight in UTC.
+ // * `0 2,14 * * * ` : every 12 hours at (2,14) hours past midnight in UTC.
+ // * `0 2 * * * ` : once a day at 2 past midnight in UTC.
+ // * `0 2 * * 0 ` : once a week every Sunday at 2 past midnight in UTC.
+ // * `0 2 8 * * ` : once a month on 8th day at 2 past midnight in UTC.
+ string text = 1 [(google.api.field_behavior) = REQUIRED];
+
+ // Output only. The time zone of the times in `CrontabSpec.text`. Currently
+ // only UTC is supported.
+ string time_zone = 2 [(google.api.field_behavior) = OUTPUT_ONLY];
+
+ // Output only. Schedule backups will contain an externally consistent copy
+ // of the database at the version time specified in
+ // `schedule_spec.cron_spec`. However, Spanner may not initiate the creation
+ // of the scheduled backups at that version time. Spanner will initiate
+ // the creation of scheduled backups within the time window bounded by the
+ // version_time specified in `schedule_spec.cron_spec` and version_time +
+ // `creation_window`.
+ google.protobuf.Duration creation_window = 3
+ [(google.api.field_behavior) = OUTPUT_ONLY];
+}
+
+// The request for
+// [CreateBackupSchedule][google.spanner.admin.database.v1.DatabaseAdmin.CreateBackupSchedule].
+message CreateBackupScheduleRequest {
+ // Required. The name of the database that this backup schedule applies to.
+ string parent = 1 [
+ (google.api.field_behavior) = REQUIRED,
+ (google.api.resource_reference) = {
+ type: "spanner.googleapis.com/Database"
+ }
+ ];
+
+ // Required. The Id to use for the backup schedule. The `backup_schedule_id`
+ // appended to `parent` forms the full backup schedule name of the form
+ // `projects//instances//databases//backupSchedules/`.
+ string backup_schedule_id = 2 [(google.api.field_behavior) = REQUIRED];
+
+ // Required. The backup schedule to create.
+ BackupSchedule backup_schedule = 3 [(google.api.field_behavior) = REQUIRED];
+}
+
+// The request for
+// [GetBackupSchedule][google.spanner.admin.database.v1.DatabaseAdmin.GetBackupSchedule].
+message GetBackupScheduleRequest {
+ // Required. The name of the schedule to retrieve.
+ // Values are of the form
+ // `projects//instances//databases//backupSchedules/`.
+ string name = 1 [
+ (google.api.field_behavior) = REQUIRED,
+ (google.api.resource_reference) = {
+ type: "spanner.googleapis.com/BackupSchedule"
+ }
+ ];
+}
+
+// The request for
+// [DeleteBackupSchedule][google.spanner.admin.database.v1.DatabaseAdmin.DeleteBackupSchedule].
+message DeleteBackupScheduleRequest {
+ // Required. The name of the schedule to delete.
+ // Values are of the form
+ // `projects//instances//databases//backupSchedules/`.
+ string name = 1 [
+ (google.api.field_behavior) = REQUIRED,
+ (google.api.resource_reference) = {
+ type: "spanner.googleapis.com/BackupSchedule"
+ }
+ ];
+}
+
+// The request for
+// [ListBackupSchedules][google.spanner.admin.database.v1.DatabaseAdmin.ListBackupSchedules].
+message ListBackupSchedulesRequest {
+ // Required. Database is the parent resource whose backup schedules should be
+ // listed. Values are of the form
+ // projects//instances//databases/
+ string parent = 1 [
+ (google.api.field_behavior) = REQUIRED,
+ (google.api.resource_reference) = {
+ type: "spanner.googleapis.com/Database"
+ }
+ ];
+
+ // Optional. Number of backup schedules to be returned in the response. If 0
+ // or less, defaults to the server's maximum allowed page size.
+ int32 page_size = 2 [(google.api.field_behavior) = OPTIONAL];
+
+ // Optional. If non-empty, `page_token` should contain a
+ // [next_page_token][google.spanner.admin.database.v1.ListBackupSchedulesResponse.next_page_token]
+ // from a previous
+ // [ListBackupSchedulesResponse][google.spanner.admin.database.v1.ListBackupSchedulesResponse]
+ // to the same `parent`.
+ string page_token = 4 [(google.api.field_behavior) = OPTIONAL];
+}
+
+// The response for
+// [ListBackupSchedules][google.spanner.admin.database.v1.DatabaseAdmin.ListBackupSchedules].
+message ListBackupSchedulesResponse {
+ // The list of backup schedules for a database.
+ repeated BackupSchedule backup_schedules = 1;
+
+ // `next_page_token` can be sent in a subsequent
+ // [ListBackupSchedules][google.spanner.admin.database.v1.DatabaseAdmin.ListBackupSchedules]
+ // call to fetch more of the schedules.
+ string next_page_token = 2;
+}
+
+// The request for
+// [UpdateBackupScheduleRequest][google.spanner.admin.database.v1.DatabaseAdmin.UpdateBackupSchedule].
+message UpdateBackupScheduleRequest {
+ // Required. The backup schedule to update. `backup_schedule.name`, and the
+ // fields to be updated as specified by `update_mask` are required. Other
+ // fields are ignored.
+ BackupSchedule backup_schedule = 1 [(google.api.field_behavior) = REQUIRED];
+
+ // Required. A mask specifying which fields in the BackupSchedule resource
+ // should be updated. This mask is relative to the BackupSchedule resource,
+ // not to the request message. The field mask must always be
+ // specified; this prevents any future fields from being erased
+ // accidentally.
+ google.protobuf.FieldMask update_mask = 2
+ [(google.api.field_behavior) = REQUIRED];
+}
diff --git a/packages/google-cloud-spanner-api/protos/google/spanner/admin/database/v1/common.proto b/packages/google-cloud-spanner-api/protos/google/spanner/admin/database/v1/common.proto
new file mode 100644
index 000000000000..c494b8cf7808
--- /dev/null
+++ b/packages/google-cloud-spanner-api/protos/google/spanner/admin/database/v1/common.proto
@@ -0,0 +1,132 @@
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+syntax = "proto3";
+
+package google.spanner.admin.database.v1;
+
+import "google/api/field_behavior.proto";
+import "google/api/resource.proto";
+import "google/protobuf/timestamp.proto";
+import "google/rpc/status.proto";
+
+option csharp_namespace = "Google.Cloud.Spanner.Admin.Database.V1";
+option go_package = "cloud.google.com/go/spanner/admin/database/apiv1/databasepb;databasepb";
+option java_multiple_files = true;
+option java_outer_classname = "CommonProto";
+option java_package = "com.google.spanner.admin.database.v1";
+option php_namespace = "Google\\Cloud\\Spanner\\Admin\\Database\\V1";
+option ruby_package = "Google::Cloud::Spanner::Admin::Database::V1";
+option (google.api.resource_definition) = {
+ type: "cloudkms.googleapis.com/CryptoKey"
+ pattern: "projects/{project}/locations/{location}/keyRings/{key_ring}/cryptoKeys/{crypto_key}"
+};
+option (google.api.resource_definition) = {
+ type: "cloudkms.googleapis.com/CryptoKeyVersion"
+ pattern: "projects/{project}/locations/{location}/keyRings/{key_ring}/cryptoKeys/{crypto_key}/cryptoKeyVersions/{crypto_key_version}"
+};
+
+// Encapsulates progress related information for a Cloud Spanner long
+// running operation.
+message OperationProgress {
+ // Percent completion of the operation.
+ // Values are between 0 and 100 inclusive.
+ int32 progress_percent = 1;
+
+ // Time the request was received.
+ google.protobuf.Timestamp start_time = 2;
+
+ // If set, the time at which this operation failed or was completed
+ // successfully.
+ google.protobuf.Timestamp end_time = 3;
+}
+
+// Encryption configuration for a Cloud Spanner database.
+message EncryptionConfig {
+ // The Cloud KMS key to be used for encrypting and decrypting
+ // the database. Values are of the form
+ // `projects//locations//keyRings//cryptoKeys/`.
+ string kms_key_name = 2 [(google.api.resource_reference) = {
+ type: "cloudkms.googleapis.com/CryptoKey"
+ }];
+
+ // Specifies the KMS configuration for the one or more keys used to encrypt
+ // the database. Values are of the form
+ // `projects//locations//keyRings//cryptoKeys/`.
+ //
+ // The keys referenced by kms_key_names must fully cover all
+ // regions of the database instance configuration. Some examples:
+ // * For single region database instance configs, specify a single regional
+ // location KMS key.
+ // * For multi-regional database instance configs of type GOOGLE_MANAGED,
+ // either specify a multi-regional location KMS key or multiple regional
+ // location KMS keys that cover all regions in the instance config.
+ // * For a database instance config of type USER_MANAGED, please specify only
+ // regional location KMS keys to cover each region in the instance config.
+ // Multi-regional location KMS keys are not supported for USER_MANAGED
+ // instance configs.
+ repeated string kms_key_names = 3 [(google.api.resource_reference) = {
+ type: "cloudkms.googleapis.com/CryptoKey"
+ }];
+}
+
+// Encryption information for a Cloud Spanner database or backup.
+message EncryptionInfo {
+ // Possible encryption types.
+ enum Type {
+ // Encryption type was not specified, though data at rest remains encrypted.
+ TYPE_UNSPECIFIED = 0;
+
+ // The data is encrypted at rest with a key that is
+ // fully managed by Google. No key version or status will be populated.
+ // This is the default state.
+ GOOGLE_DEFAULT_ENCRYPTION = 1;
+
+ // The data is encrypted at rest with a key that is
+ // managed by the customer. The active version of the key. `kms_key_version`
+ // will be populated, and `encryption_status` may be populated.
+ CUSTOMER_MANAGED_ENCRYPTION = 2;
+ }
+
+ // Output only. The type of encryption.
+ Type encryption_type = 3 [(google.api.field_behavior) = OUTPUT_ONLY];
+
+ // Output only. If present, the status of a recent encrypt/decrypt call on
+ // underlying data for this database or backup. Regardless of status, data is
+ // always encrypted at rest.
+ google.rpc.Status encryption_status = 4
+ [(google.api.field_behavior) = OUTPUT_ONLY];
+
+ // Output only. A Cloud KMS key version that is being used to protect the
+ // database or backup.
+ string kms_key_version = 2 [
+ (google.api.field_behavior) = OUTPUT_ONLY,
+ (google.api.resource_reference) = {
+ type: "cloudkms.googleapis.com/CryptoKeyVersion"
+ }
+ ];
+}
+
+// Indicates the dialect type of a database.
+enum DatabaseDialect {
+ // Default value. This value will create a database with the
+ // GOOGLE_STANDARD_SQL dialect.
+ DATABASE_DIALECT_UNSPECIFIED = 0;
+
+ // GoogleSQL supported SQL.
+ GOOGLE_STANDARD_SQL = 1;
+
+ // PostgreSQL supported SQL.
+ POSTGRESQL = 2;
+}
diff --git a/packages/google-cloud-spanner-api/protos/google/spanner/admin/database/v1/spanner_database_admin.proto b/packages/google-cloud-spanner-api/protos/google/spanner/admin/database/v1/spanner_database_admin.proto
new file mode 100644
index 000000000000..d41a4114c205
--- /dev/null
+++ b/packages/google-cloud-spanner-api/protos/google/spanner/admin/database/v1/spanner_database_admin.proto
@@ -0,0 +1,1314 @@
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+syntax = "proto3";
+
+package google.spanner.admin.database.v1;
+
+import "google/api/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/struct.proto";
+import "google/protobuf/timestamp.proto";
+import "google/rpc/status.proto";
+import "google/spanner/admin/database/v1/backup.proto";
+import "google/spanner/admin/database/v1/backup_schedule.proto";
+import "google/spanner/admin/database/v1/common.proto";
+
+option csharp_namespace = "Google.Cloud.Spanner.Admin.Database.V1";
+option go_package = "cloud.google.com/go/spanner/admin/database/apiv1/databasepb;databasepb";
+option java_multiple_files = true;
+option java_outer_classname = "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}"
+};
+option (google.api.resource_definition) = {
+ type: "spanner.googleapis.com/InstancePartition"
+ pattern: "projects/{project}/instances/{instance}/instancePartitions/{instance_partition}"
+};
+
+// Cloud Spanner Database Admin API
+//
+// The Cloud Spanner Database Admin API can be used to:
+// * create, drop, and list databases
+// * update the schema of pre-existing databases
+// * create, delete, copy and list backups for a database
+// * restore a database 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 a Cloud Spanner database. The returned
+ // [long-running operation][google.longrunning.Operation] can be used to track
+ // the progress of updating the database. If the named database does not
+ // exist, returns `NOT_FOUND`.
+ //
+ // While the operation is pending:
+ //
+ // * The database's
+ // [reconciling][google.spanner.admin.database.v1.Database.reconciling]
+ // field is set to true.
+ // * Cancelling the operation is best-effort. If the cancellation succeeds,
+ // the operation metadata's
+ // [cancel_time][google.spanner.admin.database.v1.UpdateDatabaseMetadata.cancel_time]
+ // is set, the updates are reverted, and the operation terminates with a
+ // `CANCELLED` status.
+ // * New UpdateDatabase requests will return a `FAILED_PRECONDITION` error
+ // until the pending operation is done (returns successfully or with
+ // error).
+ // * Reading the database via the API continues to give the pre-request
+ // values.
+ //
+ // Upon completion of the returned operation:
+ //
+ // * The new values are in effect and readable via the API.
+ // * The database's
+ // [reconciling][google.spanner.admin.database.v1.Database.reconciling]
+ // field becomes false.
+ //
+ // The returned [long-running operation][google.longrunning.Operation] will
+ // have a name of the format
+ // `projects//instances//databases//operations/`
+ // and can be used to track the database modification. The
+ // [metadata][google.longrunning.Operation.metadata] field type is
+ // [UpdateDatabaseMetadata][google.spanner.admin.database.v1.UpdateDatabaseMetadata].
+ // The [response][google.longrunning.Operation.response] field type is
+ // [Database][google.spanner.admin.database.v1.Database], if successful.
+ rpc UpdateDatabase(UpdateDatabaseRequest)
+ returns (google.longrunning.Operation) {
+ option (google.api.http) = {
+ patch: "/v1/{database.name=projects/*/instances/*/databases/*}"
+ body: "database"
+ };
+ option (google.api.method_signature) = "database,update_mask";
+ option (google.longrunning.operation_info) = {
+ response_type: "Database"
+ metadata_type: "UpdateDatabaseMetadata"
+ };
+ }
+
+ // 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`.
+ // Note: Cloud Spanner might continue to accept requests for a few seconds
+ // after the database has been deleted.
+ 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: "*"
+ }
+ additional_bindings {
+ post: "/v1/{resource=projects/*/instances/*/databases/*/backupSchedules/*}: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: "*"
+ }
+ additional_bindings {
+ post: "/v1/{resource=projects/*/instances/*/databases/*/backupSchedules/*}: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: "*"
+ }
+ additional_bindings {
+ post: "/v1/{resource=projects/*/instances/*/databases/*/backupSchedules/*}:testIamPermissions"
+ body: "*"
+ }
+ additional_bindings {
+ post: "/v1/{resource=projects/*/instances/*/databases/*/databaseRoles/*}: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"
+ };
+ }
+
+ // Starts copying a 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 copying of the backup. The operation is associated
+ // with the destination backup.
+ // The [metadata][google.longrunning.Operation.metadata] field type is
+ // [CopyBackupMetadata][google.spanner.admin.database.v1.CopyBackupMetadata].
+ // 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 copying and delete the
+ // destination backup. Concurrent CopyBackup requests can run on the same
+ // source backup.
+ rpc CopyBackup(CopyBackupRequest) returns (google.longrunning.Operation) {
+ option (google.api.http) = {
+ post: "/v1/{parent=projects/*/instances/*}/backups:copy"
+ body: "*"
+ };
+ option (google.api.method_signature) =
+ "parent,backup_id,source_backup,expire_time";
+ option (google.longrunning.operation_info) = {
+ response_type: "google.spanner.admin.database.v1.Backup"
+ metadata_type: "google.spanner.admin.database.v1.CopyBackupMetadata"
+ };
+ }
+
+ // 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";
+ }
+
+ // Lists Cloud Spanner database roles.
+ rpc ListDatabaseRoles(ListDatabaseRolesRequest)
+ returns (ListDatabaseRolesResponse) {
+ option (google.api.http) = {
+ get: "/v1/{parent=projects/*/instances/*/databases/*}/databaseRoles"
+ };
+ option (google.api.method_signature) = "parent";
+ }
+
+ // Adds split points to specified tables, indexes of a database.
+ rpc AddSplitPoints(AddSplitPointsRequest) returns (AddSplitPointsResponse) {
+ option (google.api.http) = {
+ post: "/v1/{database=projects/*/instances/*/databases/*}:addSplitPoints"
+ body: "*"
+ };
+ option (google.api.method_signature) = "database,split_points";
+ }
+
+ // Creates a new backup schedule.
+ rpc CreateBackupSchedule(CreateBackupScheduleRequest)
+ returns (BackupSchedule) {
+ option (google.api.http) = {
+ post: "/v1/{parent=projects/*/instances/*/databases/*}/backupSchedules"
+ body: "backup_schedule"
+ };
+ option (google.api.method_signature) =
+ "parent,backup_schedule,backup_schedule_id";
+ }
+
+ // Gets backup schedule for the input schedule name.
+ rpc GetBackupSchedule(GetBackupScheduleRequest) returns (BackupSchedule) {
+ option (google.api.http) = {
+ get: "/v1/{name=projects/*/instances/*/databases/*/backupSchedules/*}"
+ };
+ option (google.api.method_signature) = "name";
+ }
+
+ // Updates a backup schedule.
+ rpc UpdateBackupSchedule(UpdateBackupScheduleRequest)
+ returns (BackupSchedule) {
+ option (google.api.http) = {
+ patch: "/v1/{backup_schedule.name=projects/*/instances/*/databases/*/backupSchedules/*}"
+ body: "backup_schedule"
+ };
+ option (google.api.method_signature) = "backup_schedule,update_mask";
+ }
+
+ // Deletes a backup schedule.
+ rpc DeleteBackupSchedule(DeleteBackupScheduleRequest)
+ returns (google.protobuf.Empty) {
+ option (google.api.http) = {
+ delete: "/v1/{name=projects/*/instances/*/databases/*/backupSchedules/*}"
+ };
+ option (google.api.method_signature) = "name";
+ }
+
+ // Lists all the backup schedules for the database.
+ rpc ListBackupSchedules(ListBackupSchedulesRequest)
+ returns (ListBackupSchedulesResponse) {
+ option (google.api.http) = {
+ get: "/v1/{parent=projects/*/instances/*/databases/*}/backupSchedules"
+ };
+ option (google.api.method_signature) = "parent";
+ }
+
+ // This is an internal API called by Spanner Graph jobs. You should never need
+ // to call this API directly.
+ rpc InternalUpdateGraphOperation(InternalUpdateGraphOperationRequest)
+ returns (InternalUpdateGraphOperationResponse) {
+ option (google.api.method_signature) = "database,operation_id";
+ }
+}
+
+// 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
+ // all Cloud KMS key versions that are in use. The `encryption_status' field
+ // inside of each `EncryptionInfo` is not populated.
+ //
+ // 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];
+
+ // Output only. The read-write region which contains the database's leader
+ // replicas.
+ //
+ // This is the same as the value of default_leader
+ // database option set using DatabaseAdmin.CreateDatabase or
+ // DatabaseAdmin.UpdateDatabaseDdl. If not explicitly set, this is empty.
+ string default_leader = 9 [(google.api.field_behavior) = OUTPUT_ONLY];
+
+ // Output only. The dialect of the Cloud Spanner Database.
+ DatabaseDialect database_dialect = 10
+ [(google.api.field_behavior) = OUTPUT_ONLY];
+
+ // Whether drop protection is enabled for this database. Defaults to false,
+ // if not set. For more details, please see how to [prevent accidental
+ // database
+ // deletion](https://cloud.google.com/spanner/docs/prevent-database-deletion).
+ bool enable_drop_protection = 11;
+
+ // Output only. If true, the database is being updated. If false, there are no
+ // ongoing update operations for the database.
+ bool reconciling = 12 [(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];
+
+ // Optional. The dialect of the Cloud Spanner Database.
+ DatabaseDialect database_dialect = 5 [(google.api.field_behavior) = OPTIONAL];
+
+ // Optional. Proto descriptors used by CREATE/ALTER PROTO BUNDLE statements in
+ // 'extra_statements' above.
+ // Contains a protobuf-serialized
+ // [google.protobuf.FileDescriptorSet](https://github.com/protocolbuffers/protobuf/blob/main/src/google/protobuf/descriptor.proto).
+ // To generate it, [install](https://grpc.io/docs/protoc-installation/) and
+ // run `protoc` with --include_imports and --descriptor_set_out. For example,
+ // to generate for moon/shot/app.proto, run
+ // ```
+ // $protoc --proto_path=/app_path --proto_path=/lib_path \
+ // --include_imports \
+ // --descriptor_set_out=descriptors.data \
+ // moon/shot/app.proto
+ // ```
+ // For more details, see protobuffer [self
+ // description](https://developers.google.com/protocol-buffers/docs/techniques#self-description).
+ bytes proto_descriptors = 6 [(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"
+ }
+ ];
+}
+
+// The request for
+// [UpdateDatabase][google.spanner.admin.database.v1.DatabaseAdmin.UpdateDatabase].
+message UpdateDatabaseRequest {
+ // Required. The database to update.
+ // The `name` field of the database is of the form
+ // `projects//instances//databases/`.
+ Database database = 1 [(google.api.field_behavior) = REQUIRED];
+
+ // Required. The list of fields to update. Currently, only
+ // `enable_drop_protection` field can be updated.
+ google.protobuf.FieldMask update_mask = 2
+ [(google.api.field_behavior) = REQUIRED];
+}
+
+// Metadata type for the operation returned by
+// [UpdateDatabase][google.spanner.admin.database.v1.DatabaseAdmin.UpdateDatabase].
+message UpdateDatabaseMetadata {
+ // The request for
+ // [UpdateDatabase][google.spanner.admin.database.v1.DatabaseAdmin.UpdateDatabase].
+ UpdateDatabaseRequest request = 1;
+
+ // The progress of the
+ // [UpdateDatabase][google.spanner.admin.database.v1.DatabaseAdmin.UpdateDatabase]
+ // operation.
+ OperationProgress progress = 2;
+
+ // The time at which this operation was cancelled. If set, this operation is
+ // in the process of undoing itself (which is best-effort).
+ google.protobuf.Timestamp cancel_time = 3;
+}
+
+// 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;
+
+ // Optional. Proto descriptors used by CREATE/ALTER PROTO BUNDLE statements.
+ // Contains a protobuf-serialized
+ // [google.protobuf.FileDescriptorSet](https://github.com/protocolbuffers/protobuf/blob/main/src/google/protobuf/descriptor.proto).
+ // To generate it, [install](https://grpc.io/docs/protoc-installation/) and
+ // run `protoc` with --include_imports and --descriptor_set_out. For example,
+ // to generate for moon/shot/app.proto, run
+ // ```
+ // $protoc --proto_path=/app_path --proto_path=/lib_path \
+ // --include_imports \
+ // --descriptor_set_out=descriptors.data \
+ // moon/shot/app.proto
+ // ```
+ // For more details, see protobuffer [self
+ // description](https://developers.google.com/protocol-buffers/docs/techniques#self-description).
+ bytes proto_descriptors = 4 [(google.api.field_behavior) = OPTIONAL];
+
+ // Optional. This field is exposed to be used by the Spanner Migration Tool.
+ // For more details, see
+ // [SMT](https://github.com/GoogleCloudPlatform/spanner-migration-tool).
+ bool throughput_mode = 5 [(google.api.field_behavior) = OPTIONAL];
+}
+
+// Action information extracted from a DDL statement. This proto is used to
+// display the brief info of the DDL statement for the operation
+// [UpdateDatabaseDdl][google.spanner.admin.database.v1.DatabaseAdmin.UpdateDatabaseDdl].
+message DdlStatementActionInfo {
+ // The action for the DDL statement, e.g. CREATE, ALTER, DROP, GRANT, etc.
+ // This field is a non-empty string.
+ string action = 1;
+
+ // The entity type for the DDL statement, e.g. TABLE, INDEX, VIEW, etc.
+ // This field can be empty string for some DDL statement,
+ // e.g. for statement "ANALYZE", `entity_type` = "".
+ string entity_type = 2;
+
+ // The entity name(s) being operated on the DDL statement.
+ // E.g.
+ // 1. For statement "CREATE TABLE t1(...)", `entity_names` = ["t1"].
+ // 2. For statement "GRANT ROLE r1, r2 ...", `entity_names` = ["r1", "r2"].
+ // 3. For statement "ANALYZE", `entity_names` = [].
+ repeated string entity_names = 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 progress of the
+ // [UpdateDatabaseDdl][google.spanner.admin.database.v1.DatabaseAdmin.UpdateDatabaseDdl]
+ // operations. All DDL statements will have continuously updating progress,
+ // and `progress[i]` is the operation progress for `statements[i]`. Also,
+ // `progress[i]` will have start time and end time populated with commit
+ // timestamp of operation, as well as a progress of 100% once the operation
+ // has completed.
+ repeated OperationProgress progress = 5;
+
+ // The brief action info for the DDL statements.
+ // `actions[i]` is the brief info for `statements[i]`.
+ repeated DdlStatementActionInfo actions = 6;
+}
+
+// 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;
+
+ // Proto descriptors stored in the database.
+ // Contains a protobuf-serialized
+ // [google.protobuf.FileDescriptorSet](https://github.com/protocolbuffers/protobuf/blob/main/src/google/protobuf/descriptor.proto).
+ // For more details, see protobuffer [self
+ // description](https://developers.google.com/protocol-buffers/docs/techniques#self-description).
+ bytes proto_descriptors = 2;
+}
+
+// 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.
+ // `metadata.@type` must be specified first, if filtering on metadata
+ // fields.
+ // * `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"
+ }
+ ];
+
+ // Optional. Specifies the KMS configuration for the one or more keys used to
+ // encrypt the database. Values are of the form
+ // `projects//locations//keyRings//cryptoKeys/`.
+ //
+ // The keys referenced by kms_key_names must fully cover all
+ // regions of the database instance configuration. Some examples:
+ // * For single region database instance configs, specify a single regional
+ // location KMS key.
+ // * For multi-regional database instance configs of type GOOGLE_MANAGED,
+ // either specify a multi-regional location KMS key or multiple regional
+ // location KMS keys that cover all regions in the instance config.
+ // * For a database instance config of type USER_MANAGED, please specify only
+ // regional location KMS keys to cover each region in the instance config.
+ // Multi-regional location KMS keys are not supported for USER_MANAGED
+ // instance configs.
+ repeated string kms_key_names = 3 [
+ (google.api.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;
+}
+
+// A Cloud Spanner database role.
+message DatabaseRole {
+ option (google.api.resource) = {
+ type: "spanner.googleapis.com/DatabaseRole"
+ pattern: "projects/{project}/instances/{instance}/databases/{database}/databaseRoles/{role}"
+ };
+
+ // Required. The name of the database role. Values are of the form
+ // `projects//instances//databases//databaseRoles/`
+ // where `` is as specified in the `CREATE ROLE` DDL statement.
+ string name = 1 [(google.api.field_behavior) = REQUIRED];
+}
+
+// The request for
+// [ListDatabaseRoles][google.spanner.admin.database.v1.DatabaseAdmin.ListDatabaseRoles].
+message ListDatabaseRolesRequest {
+ // Required. The database whose roles should be listed.
+ // Values are of the form
+ // `projects//instances//databases/`.
+ string parent = 1 [
+ (google.api.field_behavior) = REQUIRED,
+ (google.api.resource_reference) = {
+ type: "spanner.googleapis.com/Database"
+ }
+ ];
+
+ // Number of database roles 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.database.v1.ListDatabaseRolesResponse.next_page_token]
+ // from a previous
+ // [ListDatabaseRolesResponse][google.spanner.admin.database.v1.ListDatabaseRolesResponse].
+ string page_token = 3;
+}
+
+// The response for
+// [ListDatabaseRoles][google.spanner.admin.database.v1.DatabaseAdmin.ListDatabaseRoles].
+message ListDatabaseRolesResponse {
+ // Database roles that matched the request.
+ repeated DatabaseRole database_roles = 1;
+
+ // `next_page_token` can be sent in a subsequent
+ // [ListDatabaseRoles][google.spanner.admin.database.v1.DatabaseAdmin.ListDatabaseRoles]
+ // call to fetch more of the matching roles.
+ string next_page_token = 2;
+}
+
+// The request for
+// [AddSplitPoints][google.spanner.admin.database.v1.DatabaseAdmin.AddSplitPoints].
+message AddSplitPointsRequest {
+ // Required. The database on whose tables/indexes split points are to be
+ // added. 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"
+ }
+ ];
+
+ // Required. The split points to add.
+ repeated SplitPoints split_points = 2
+ [(google.api.field_behavior) = REQUIRED];
+
+ // Optional. A user-supplied tag associated with the split points.
+ // For example, "intital_data_load", "special_event_1".
+ // Defaults to "CloudAddSplitPointsAPI" if not specified.
+ // The length of the tag must not exceed 50 characters,else will be trimmed.
+ // Only valid UTF8 characters are allowed.
+ string initiator = 3 [(google.api.field_behavior) = OPTIONAL];
+}
+
+// The response for
+// [AddSplitPoints][google.spanner.admin.database.v1.DatabaseAdmin.AddSplitPoints].
+message AddSplitPointsResponse {}
+
+// The split points of a table/index.
+message SplitPoints {
+ // A split key.
+ message Key {
+ // Required. The column values making up the split key.
+ google.protobuf.ListValue key_parts = 1
+ [(google.api.field_behavior) = REQUIRED];
+ }
+
+ // The table to split.
+ string table = 1;
+
+ // The index to split.
+ // If specified, the `table` field must refer to the index's base table.
+ string index = 2;
+
+ // Required. The list of split keys, i.e., the split boundaries.
+ repeated Key keys = 3 [(google.api.field_behavior) = REQUIRED];
+
+ // Optional. The expiration timestamp of the split points.
+ // A timestamp in the past means immediate expiration.
+ // The maximum value can be 30 days in the future.
+ // Defaults to 10 days in the future if not specified.
+ google.protobuf.Timestamp expire_time = 5
+ [(google.api.field_behavior) = OPTIONAL];
+}
+
+// Internal request proto, do not use directly.
+message InternalUpdateGraphOperationRequest {
+ // Internal field, do not use directly.
+ string database = 1 [
+ (google.api.field_behavior) = REQUIRED,
+ (google.api.resource_reference) = {
+ type: "spanner.googleapis.com/Database"
+ }
+ ];
+ // Internal field, do not use directly.
+ string operation_id = 2 [(google.api.field_behavior) = REQUIRED];
+ // Internal field, do not use directly.
+ string vm_identity_token = 5 [(google.api.field_behavior) = REQUIRED];
+ // Internal field, do not use directly.
+ double progress = 3 [(google.api.field_behavior) = OPTIONAL];
+ // Internal field, do not use directly.
+ google.rpc.Status status = 6 [(google.api.field_behavior) = OPTIONAL];
+}
+
+// Internal response proto, do not use directly.
+message InternalUpdateGraphOperationResponse {}
diff --git a/packages/google-cloud-spanner-api/protos/google/spanner/admin/instance/v1/common.proto b/packages/google-cloud-spanner-api/protos/google/spanner/admin/instance/v1/common.proto
new file mode 100644
index 000000000000..0b5282c7d874
--- /dev/null
+++ b/packages/google-cloud-spanner-api/protos/google/spanner/admin/instance/v1/common.proto
@@ -0,0 +1,64 @@
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+syntax = "proto3";
+
+package google.spanner.admin.instance.v1;
+
+import "google/api/field_behavior.proto";
+import "google/api/resource.proto";
+import "google/protobuf/timestamp.proto";
+
+option csharp_namespace = "Google.Cloud.Spanner.Admin.Instance.V1";
+option go_package = "cloud.google.com/go/spanner/admin/instance/apiv1/instancepb;instancepb";
+option java_multiple_files = true;
+option java_outer_classname = "CommonProto";
+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";
+
+// Encapsulates progress related information for a Cloud Spanner long
+// running instance operations.
+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;
+}
+
+// Indicates the expected fulfillment period of an operation.
+enum FulfillmentPeriod {
+ // Not specified.
+ FULFILLMENT_PERIOD_UNSPECIFIED = 0;
+
+ // Normal fulfillment period. The operation is expected to complete within
+ // minutes.
+ FULFILLMENT_PERIOD_NORMAL = 1;
+
+ // Extended fulfillment period. It can take up to an hour for the operation
+ // to complete.
+ FULFILLMENT_PERIOD_EXTENDED = 2;
+}
+
+// ReplicaSelection identifies replicas with common properties.
+message ReplicaSelection {
+ // Required. Name of the location of the replicas (e.g., "us-central1").
+ string location = 1 [(google.api.field_behavior) = REQUIRED];
+}
diff --git a/packages/google-cloud-spanner-api/protos/google/spanner/admin/instance/v1/spanner_instance_admin.proto b/packages/google-cloud-spanner-api/protos/google/spanner/admin/instance/v1/spanner_instance_admin.proto
new file mode 100644
index 000000000000..d16ab2ca5835
--- /dev/null
+++ b/packages/google-cloud-spanner-api/protos/google/spanner/admin/instance/v1/spanner_instance_admin.proto
@@ -0,0 +1,2184 @@
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+syntax = "proto3";
+
+package google.spanner.admin.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";
+import "google/spanner/admin/instance/v1/common.proto";
+
+option csharp_namespace = "Google.Cloud.Spanner.Admin.Instance.V1";
+option go_package = "cloud.google.com/go/spanner/admin/instance/apiv1/instancepb;instancepb";
+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.
+ //
+ // Returns both Google-managed configurations and user-managed
+ // configurations.
+ 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";
+ }
+
+ // Creates an instance configuration and begins preparing it to be used. The
+ // returned long-running operation
+ // can be used to track the progress of preparing the new
+ // instance configuration. The instance configuration name is assigned by the
+ // caller. If the named instance configuration already exists,
+ // `CreateInstanceConfig` returns `ALREADY_EXISTS`.
+ //
+ // Immediately after the request returns:
+ //
+ // * The instance configuration is readable via the API, with all requested
+ // attributes. The instance configuration's
+ // [reconciling][google.spanner.admin.instance.v1.InstanceConfig.reconciling]
+ // field is set to true. Its state is `CREATING`.
+ //
+ // While the operation is pending:
+ //
+ // * Cancelling the operation renders the instance configuration immediately
+ // unreadable via the API.
+ // * Except for deleting the creating resource, all other attempts to modify
+ // the instance configuration are rejected.
+ //
+ // Upon completion of the returned operation:
+ //
+ // * Instances can be created using the instance configuration.
+ // * The instance configuration's
+ // [reconciling][google.spanner.admin.instance.v1.InstanceConfig.reconciling]
+ // field becomes false. Its state becomes `READY`.
+ //
+ // The returned long-running operation will
+ // have a name of the format
+ // `/operations/` and can be used to track
+ // creation of the instance configuration. The
+ // metadata field type is
+ // [CreateInstanceConfigMetadata][google.spanner.admin.instance.v1.CreateInstanceConfigMetadata].
+ // The response field type is
+ // [InstanceConfig][google.spanner.admin.instance.v1.InstanceConfig], if
+ // successful.
+ //
+ // Authorization requires `spanner.instanceConfigs.create` permission on
+ // the resource
+ // [parent][google.spanner.admin.instance.v1.CreateInstanceConfigRequest.parent].
+ rpc CreateInstanceConfig(CreateInstanceConfigRequest)
+ returns (google.longrunning.Operation) {
+ option (google.api.http) = {
+ post: "/v1/{parent=projects/*}/instanceConfigs"
+ body: "*"
+ };
+ option (google.api.method_signature) =
+ "parent,instance_config,instance_config_id";
+ option (google.longrunning.operation_info) = {
+ response_type: "google.spanner.admin.instance.v1.InstanceConfig"
+ metadata_type: "google.spanner.admin.instance.v1.CreateInstanceConfigMetadata"
+ };
+ }
+
+ // Updates an instance configuration. The returned
+ // long-running operation can be used to track
+ // the progress of updating the instance. If the named instance configuration
+ // does not exist, returns `NOT_FOUND`.
+ //
+ // Only user-managed configurations can be updated.
+ //
+ // Immediately after the request returns:
+ //
+ // * The instance configuration's
+ // [reconciling][google.spanner.admin.instance.v1.InstanceConfig.reconciling]
+ // field is set to true.
+ //
+ // While the operation is pending:
+ //
+ // * Cancelling the operation sets its metadata's
+ // [cancel_time][google.spanner.admin.instance.v1.UpdateInstanceConfigMetadata.cancel_time].
+ // The operation is guaranteed to succeed at undoing all changes, after
+ // which point it terminates with a `CANCELLED` status.
+ // * All other attempts to modify the instance configuration are rejected.
+ // * Reading the instance configuration via the API continues to give the
+ // pre-request values.
+ //
+ // Upon completion of the returned operation:
+ //
+ // * Creating instances using the instance configuration uses the new
+ // values.
+ // * The new values of the instance configuration are readable via the API.
+ // * The instance configuration's
+ // [reconciling][google.spanner.admin.instance.v1.InstanceConfig.reconciling]
+ // field becomes false.
+ //
+ // The returned long-running operation will
+ // have a name of the format
+ // `/operations/` and can be used to track
+ // the instance configuration modification. The
+ // metadata field type is
+ // [UpdateInstanceConfigMetadata][google.spanner.admin.instance.v1.UpdateInstanceConfigMetadata].
+ // The response field type is
+ // [InstanceConfig][google.spanner.admin.instance.v1.InstanceConfig], if
+ // successful.
+ //
+ // Authorization requires `spanner.instanceConfigs.update` permission on
+ // the resource [name][google.spanner.admin.instance.v1.InstanceConfig.name].
+ rpc UpdateInstanceConfig(UpdateInstanceConfigRequest)
+ returns (google.longrunning.Operation) {
+ option (google.api.http) = {
+ patch: "/v1/{instance_config.name=projects/*/instanceConfigs/*}"
+ body: "*"
+ };
+ option (google.api.method_signature) = "instance_config,update_mask";
+ option (google.longrunning.operation_info) = {
+ response_type: "google.spanner.admin.instance.v1.InstanceConfig"
+ metadata_type: "google.spanner.admin.instance.v1.UpdateInstanceConfigMetadata"
+ };
+ }
+
+ // Deletes the instance configuration. Deletion is only allowed when no
+ // instances are using the configuration. If any instances are using
+ // the configuration, returns `FAILED_PRECONDITION`.
+ //
+ // Only user-managed configurations can be deleted.
+ //
+ // Authorization requires `spanner.instanceConfigs.delete` permission on
+ // the resource [name][google.spanner.admin.instance.v1.InstanceConfig.name].
+ rpc DeleteInstanceConfig(DeleteInstanceConfigRequest)
+ returns (google.protobuf.Empty) {
+ option (google.api.http) = {
+ delete: "/v1/{name=projects/*/instanceConfigs/*}"
+ };
+ option (google.api.method_signature) = "name";
+ }
+
+ // Lists the user-managed instance configuration long-running
+ // operations in the given project. An instance
+ // configuration operation has a name of the form
+ // `projects//instanceConfigs//operations/`.
+ // The long-running 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.start_time` in descending order starting
+ // from the most recently started operation.
+ rpc ListInstanceConfigOperations(ListInstanceConfigOperationsRequest)
+ returns (ListInstanceConfigOperationsResponse) {
+ option (google.api.http) = {
+ get: "/v1/{parent=projects/*}/instanceConfigOperations"
+ };
+ option (google.api.method_signature) = "parent";
+ }
+
+ // 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";
+ }
+
+ // Lists all instance partitions for the given instance.
+ rpc ListInstancePartitions(ListInstancePartitionsRequest)
+ returns (ListInstancePartitionsResponse) {
+ option (google.api.http) = {
+ get: "/v1/{parent=projects/*/instances/*}/instancePartitions"
+ };
+ 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
+ // 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 will
+ // have a name of the format `/operations/` and
+ // can be used to track creation of the instance. The
+ // metadata field type is
+ // [CreateInstanceMetadata][google.spanner.admin.instance.v1.CreateInstanceMetadata].
+ // The 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 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 will
+ // have a name of the format `/operations/` and
+ // can be used to track the instance modification. The
+ // metadata field type is
+ // [UpdateInstanceMetadata][google.spanner.admin.instance.v1.UpdateInstanceMetadata].
+ // The response field type is
+ // [Instance][google.spanner.admin.instance.v1.Instance], if successful.
+ //
+ // Authorization requires `spanner.instances.update` permission on
+ // the 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";
+ }
+
+ // Gets information about a particular instance partition.
+ rpc GetInstancePartition(GetInstancePartitionRequest)
+ returns (InstancePartition) {
+ option (google.api.http) = {
+ get: "/v1/{name=projects/*/instances/*/instancePartitions/*}"
+ };
+ option (google.api.method_signature) = "name";
+ }
+
+ // Creates an instance partition and begins preparing it to be used. The
+ // returned long-running operation
+ // can be used to track the progress of preparing the new instance partition.
+ // The instance partition name is assigned by the caller. If the named
+ // instance partition already exists, `CreateInstancePartition` returns
+ // `ALREADY_EXISTS`.
+ //
+ // Immediately upon completion of this request:
+ //
+ // * The instance partition 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 partition immediately
+ // unreadable via the API.
+ // * The instance partition can be deleted.
+ // * All other attempts to modify the instance partition 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 start using this instance partition.
+ // * The instance partition's allocated resource levels are readable via the
+ // API.
+ // * The instance partition's state becomes `READY`.
+ //
+ // The returned long-running operation will
+ // have a name of the format
+ // `/operations/` and can be used to
+ // track creation of the instance partition. The
+ // metadata field type is
+ // [CreateInstancePartitionMetadata][google.spanner.admin.instance.v1.CreateInstancePartitionMetadata].
+ // The response field type is
+ // [InstancePartition][google.spanner.admin.instance.v1.InstancePartition], if
+ // successful.
+ rpc CreateInstancePartition(CreateInstancePartitionRequest)
+ returns (google.longrunning.Operation) {
+ option (google.api.http) = {
+ post: "/v1/{parent=projects/*/instances/*}/instancePartitions"
+ body: "*"
+ };
+ option (google.api.method_signature) =
+ "parent,instance_partition,instance_partition_id";
+ option (google.longrunning.operation_info) = {
+ response_type: "google.spanner.admin.instance.v1.InstancePartition"
+ metadata_type: "google.spanner.admin.instance.v1.CreateInstancePartitionMetadata"
+ };
+ }
+
+ // Deletes an existing instance partition. Requires that the
+ // instance partition is not used by any database or backup and is not the
+ // default instance partition of an instance.
+ //
+ // Authorization requires `spanner.instancePartitions.delete` permission on
+ // the resource
+ // [name][google.spanner.admin.instance.v1.InstancePartition.name].
+ rpc DeleteInstancePartition(DeleteInstancePartitionRequest)
+ returns (google.protobuf.Empty) {
+ option (google.api.http) = {
+ delete: "/v1/{name=projects/*/instances/*/instancePartitions/*}"
+ };
+ option (google.api.method_signature) = "name";
+ }
+
+ // Updates an instance partition, and begins allocating or releasing resources
+ // as requested. The returned long-running operation can be used to track the
+ // progress of updating the instance partition. If the named instance
+ // partition does not exist, returns `NOT_FOUND`.
+ //
+ // Immediately upon completion of this request:
+ //
+ // * For resource types for which a decrease in the instance partition'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.UpdateInstancePartitionMetadata.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 partition are rejected.
+ // * Reading the instance partition 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
+ // partition's tables.
+ // * The instance partition's new resource levels are readable via the API.
+ //
+ // The returned long-running operation will
+ // have a name of the format
+ // `/operations/` and can be used to
+ // track the instance partition modification. The
+ // metadata field type is
+ // [UpdateInstancePartitionMetadata][google.spanner.admin.instance.v1.UpdateInstancePartitionMetadata].
+ // The response field type is
+ // [InstancePartition][google.spanner.admin.instance.v1.InstancePartition], if
+ // successful.
+ //
+ // Authorization requires `spanner.instancePartitions.update` permission on
+ // the resource
+ // [name][google.spanner.admin.instance.v1.InstancePartition.name].
+ rpc UpdateInstancePartition(UpdateInstancePartitionRequest)
+ returns (google.longrunning.Operation) {
+ option (google.api.http) = {
+ patch: "/v1/{instance_partition.name=projects/*/instances/*/instancePartitions/*}"
+ body: "*"
+ };
+ option (google.api.method_signature) = "instance_partition,field_mask";
+ option (google.longrunning.operation_info) = {
+ response_type: "google.spanner.admin.instance.v1.InstancePartition"
+ metadata_type: "google.spanner.admin.instance.v1.UpdateInstancePartitionMetadata"
+ };
+ }
+
+ // Lists instance partition long-running operations in the given instance.
+ // An instance partition operation has a name of the form
+ // `projects//instances//instancePartitions//operations/`.
+ // The long-running 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.start_time` in descending order starting from the
+ // most recently started operation.
+ //
+ // Authorization requires `spanner.instancePartitionOperations.list`
+ // permission on the resource
+ // [parent][google.spanner.admin.instance.v1.ListInstancePartitionOperationsRequest.parent].
+ rpc ListInstancePartitionOperations(ListInstancePartitionOperationsRequest)
+ returns (ListInstancePartitionOperationsResponse) {
+ option (google.api.http) = {
+ get: "/v1/{parent=projects/*/instances/*}/instancePartitionOperations"
+ };
+ option (google.api.method_signature) = "parent";
+ }
+
+ // Moves an instance to the target instance configuration. You can use the
+ // returned long-running operation to track
+ // the progress of moving the instance.
+ //
+ // `MoveInstance` returns `FAILED_PRECONDITION` if the instance meets any of
+ // the following criteria:
+ //
+ // * Is undergoing a move to a different instance configuration
+ // * Has backups
+ // * Has an ongoing update
+ // * Contains any CMEK-enabled databases
+ // * Is a free trial instance
+ //
+ // While the operation is pending:
+ //
+ // * All other attempts to modify the instance, including changes to its
+ // compute capacity, are rejected.
+ // * The following database and backup admin operations are rejected:
+ //
+ // * `DatabaseAdmin.CreateDatabase`
+ // * `DatabaseAdmin.UpdateDatabaseDdl` (disabled if default_leader is
+ // specified in the request.)
+ // * `DatabaseAdmin.RestoreDatabase`
+ // * `DatabaseAdmin.CreateBackup`
+ // * `DatabaseAdmin.CopyBackup`
+ //
+ // * Both the source and target instance configurations are subject to
+ // hourly compute and storage charges.
+ // * The instance might experience higher read-write latencies and a higher
+ // transaction abort rate. However, moving an instance doesn't cause any
+ // downtime.
+ //
+ // The returned long-running operation has
+ // a name of the format
+ // `/operations/` and can be used to track
+ // the move instance operation. The
+ // metadata field type is
+ // [MoveInstanceMetadata][google.spanner.admin.instance.v1.MoveInstanceMetadata].
+ // The response field type is
+ // [Instance][google.spanner.admin.instance.v1.Instance],
+ // if successful.
+ // Cancelling the operation sets its metadata's
+ // [cancel_time][google.spanner.admin.instance.v1.MoveInstanceMetadata.cancel_time].
+ // Cancellation is not immediate because it involves moving any data
+ // previously moved to the target instance configuration back to the original
+ // instance configuration. You can use this operation to track the progress of
+ // the cancellation. Upon successful completion of the cancellation, the
+ // operation terminates with `CANCELLED` status.
+ //
+ // If not cancelled, upon completion of the returned operation:
+ //
+ // * The instance successfully moves to the target instance
+ // configuration.
+ // * You are billed for compute and storage in target instance
+ // configuration.
+ //
+ // Authorization requires the `spanner.instances.update` permission on
+ // the resource [instance][google.spanner.admin.instance.v1.Instance].
+ //
+ // For more details, see
+ // [Move an instance](https://cloud.google.com/spanner/docs/move-instance).
+ rpc MoveInstance(MoveInstanceRequest) returns (google.longrunning.Operation) {
+ option (google.api.http) = {
+ post: "/v1/{name=projects/*/instances/*}:move"
+ body: "*"
+ };
+ option (google.longrunning.operation_info) = {
+ response_type: "google.spanner.admin.instance.v1.MoveInstanceResponse"
+ metadata_type: "google.spanner.admin.instance.v1.MoveInstanceMetadata"
+ };
+ }
+}
+
+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}"
+ plural: "instanceConfigs"
+ singular: "instanceConfig"
+ };
+
+ // The type of this configuration.
+ enum Type {
+ // Unspecified.
+ TYPE_UNSPECIFIED = 0;
+
+ // Google-managed configuration.
+ GOOGLE_MANAGED = 1;
+
+ // User-managed configuration.
+ USER_MANAGED = 2;
+ }
+
+ // Indicates the current state of the instance configuration.
+ enum State {
+ // Not specified.
+ STATE_UNSPECIFIED = 0;
+
+ // The instance configuration is still being created.
+ CREATING = 1;
+
+ // The instance configuration is fully created and ready to be used to
+ // create instances.
+ READY = 2;
+ }
+
+ // Describes the availability for free instances to be created in an instance
+ // configuration.
+ enum FreeInstanceAvailability {
+ // Not specified.
+ FREE_INSTANCE_AVAILABILITY_UNSPECIFIED = 0;
+
+ // Indicates that free instances are available to be created in this
+ // instance configuration.
+ AVAILABLE = 1;
+
+ // Indicates that free instances are not supported in this instance
+ // configuration.
+ UNSUPPORTED = 2;
+
+ // Indicates that free instances are currently not available to be created
+ // in this instance configuration.
+ DISABLED = 3;
+
+ // Indicates that additional free instances cannot be created in this
+ // instance configuration because the project has reached its limit of free
+ // instances.
+ QUOTA_EXCEEDED = 4;
+ }
+
+ // Indicates the quorum type of this instance configuration.
+ enum QuorumType {
+ // Quorum type not specified.
+ QUORUM_TYPE_UNSPECIFIED = 0;
+
+ // An instance configuration tagged with `REGION` quorum type forms a write
+ // quorum in a single region.
+ REGION = 1;
+
+ // An instance configuration tagged with the `DUAL_REGION` quorum type forms
+ // a write quorum with exactly two read-write regions in a multi-region
+ // configuration.
+ //
+ // This instance configuration requires failover in the event of
+ // regional failures.
+ DUAL_REGION = 2;
+
+ // An instance configuration tagged with the `MULTI_REGION` quorum type
+ // forms a write quorum from replicas that are spread across more than one
+ // region in a multi-region configuration.
+ MULTI_REGION = 3;
+ }
+
+ // A unique identifier for the instance configuration. Values
+ // are of the form
+ // `projects//instanceConfigs/[a-z][-a-z0-9]*`.
+ //
+ // User instance configuration must start with `custom-`.
+ string name = 1;
+
+ // The name of this instance configuration as it appears in UIs.
+ string display_name = 2;
+
+ // Output only. Whether this instance configuration is a Google-managed or
+ // user-managed configuration.
+ Type config_type = 5 [(google.api.field_behavior) = OUTPUT_ONLY];
+
+ // The geographic placement of nodes in this instance configuration and their
+ // replication properties.
+ //
+ // To create user-managed configurations, input
+ // `replicas` must include all replicas in `replicas` of the `base_config`
+ // and include one or more replicas in the `optional_replicas` of the
+ // `base_config`.
+ repeated ReplicaInfo replicas = 3;
+
+ // Output only. The available optional replicas to choose from for
+ // user-managed configurations. Populated for Google-managed configurations.
+ repeated ReplicaInfo optional_replicas = 6
+ [(google.api.field_behavior) = OUTPUT_ONLY];
+
+ // Base configuration name, e.g. projects//instanceConfigs/nam3,
+ // based on which this configuration is created. Only set for user-managed
+ // configurations. `base_config` must refer to a configuration of type
+ // `GOOGLE_MANAGED` in the same project as this configuration.
+ string base_config = 7 [(google.api.resource_reference) = {
+ type: "spanner.googleapis.com/InstanceConfig"
+ }];
+
+ // 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_-]{0,62}`.
+ // * Label values must be between 0 and 63 characters long and must conform
+ // to the regular expression `[a-z0-9_-]{0,63}`.
+ // * 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. Therefore, 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 = 8;
+
+ // etag is used for optimistic concurrency control as a way
+ // to help prevent simultaneous updates of a instance configuration from
+ // overwriting each other. It is strongly suggested that systems make use of
+ // the etag in the read-modify-write cycle to perform instance configuration
+ // updates in order to avoid race conditions: An etag is returned in the
+ // response which contains instance configurations, and systems are expected
+ // to put that etag in the request to update instance configuration to ensure
+ // that their change is applied to the same version of the instance
+ // configuration. If no etag is provided in the call to update the instance
+ // configuration, then the existing instance configuration is overwritten
+ // blindly.
+ string etag = 9;
+
+ // Allowed values of the "default_leader" schema option for databases in
+ // instances that use this instance configuration.
+ repeated string leader_options = 4;
+
+ // Output only. If true, the instance configuration is being created or
+ // updated. If false, there are no ongoing operations for the instance
+ // configuration.
+ bool reconciling = 10 [(google.api.field_behavior) = OUTPUT_ONLY];
+
+ // Output only. The current instance configuration state. Applicable only for
+ // `USER_MANAGED` configurations.
+ State state = 11 [(google.api.field_behavior) = OUTPUT_ONLY];
+
+ // Output only. Describes whether free instances are available to be created
+ // in this instance configuration.
+ FreeInstanceAvailability free_instance_availability = 12
+ [(google.api.field_behavior) = OUTPUT_ONLY];
+
+ // Output only. The `QuorumType` of the instance configuration.
+ QuorumType quorum_type = 18 [(google.api.field_behavior) = OUTPUT_ONLY];
+
+ // Output only. The storage limit in bytes per processing unit.
+ int64 storage_limit_per_processing_unit = 19
+ [(google.api.field_behavior) = OUTPUT_ONLY];
+}
+
+// ReplicaComputeCapacity describes the amount of server resources that are
+// allocated to each replica identified by the replica selection.
+message ReplicaComputeCapacity {
+ // Required. Identifies replicas by specified properties.
+ // All replicas in the selection have the same amount of compute capacity.
+ ReplicaSelection replica_selection = 1
+ [(google.api.field_behavior) = REQUIRED];
+
+ // Compute capacity allocated to each replica identified by the specified
+ // selection.
+ // The unit is selected based on the unit used to specify the instance size
+ // for non-autoscaling instances, or the unit used in autoscaling limit for
+ // autoscaling instances.
+ oneof compute_capacity {
+ // The number of nodes allocated to each replica.
+ //
+ // This may be zero in API responses for instances that are not yet in
+ // state `READY`.
+ int32 node_count = 2;
+
+ // The number of processing units allocated to each replica.
+ //
+ // This may be zero in API responses for instances that are not yet in
+ // state `READY`.
+ int32 processing_units = 3;
+ }
+}
+
+// Autoscaling configuration for an instance.
+message AutoscalingConfig {
+ // The autoscaling limits for the instance. Users can define the minimum and
+ // maximum compute capacity allocated to the instance, and the autoscaler will
+ // only scale within that range. Users can either use nodes or processing
+ // units to specify the limits, but should use the same unit to set both the
+ // min_limit and max_limit.
+ message AutoscalingLimits {
+ // The minimum compute capacity for the instance.
+ oneof min_limit {
+ // Minimum number of nodes allocated to the instance. If set, this number
+ // should be greater than or equal to 1.
+ int32 min_nodes = 1;
+
+ // Minimum number of processing units allocated to the instance. If set,
+ // this number should be multiples of 1000.
+ int32 min_processing_units = 2;
+ }
+
+ // The maximum compute capacity for the instance. The maximum compute
+ // capacity should be less than or equal to 10X the minimum compute
+ // capacity.
+ oneof max_limit {
+ // Maximum number of nodes allocated to the instance. If set, this number
+ // should be greater than or equal to min_nodes.
+ int32 max_nodes = 3;
+
+ // Maximum number of processing units allocated to the instance. If set,
+ // this number should be multiples of 1000 and be greater than or equal to
+ // min_processing_units.
+ int32 max_processing_units = 4;
+ }
+ }
+
+ // The autoscaling targets for an instance.
+ message AutoscalingTargets {
+ // Optional. The target high priority cpu utilization percentage that the
+ // autoscaler should be trying to achieve for the instance. This number is
+ // on a scale from 0 (no utilization) to 100 (full utilization). The valid
+ // range is [10, 90] inclusive. If not specified or set to 0, the autoscaler
+ // skips scaling based on high priority CPU utilization.
+ int32 high_priority_cpu_utilization_percent = 1
+ [(google.api.field_behavior) = OPTIONAL];
+
+ // Optional. The target total CPU utilization percentage that the autoscaler
+ // should be trying to achieve for the instance. This number is on a scale
+ // from 0 (no utilization) to 100 (full utilization). The valid range is
+ // [10, 90] inclusive. If not specified or set to 0, the autoscaler skips
+ // scaling based on total CPU utilization. If both
+ // `high_priority_cpu_utilization_percent` and
+ // `total_cpu_utilization_percent` are specified, the autoscaler provisions
+ // the larger of the two required compute capacities to satisfy both
+ // targets.
+ int32 total_cpu_utilization_percent = 4
+ [(google.api.field_behavior) = OPTIONAL];
+
+ // Required. The target storage utilization percentage that the autoscaler
+ // should be trying to achieve for the instance. This number is on a scale
+ // from 0 (no utilization) to 100 (full utilization). The valid range is
+ // [10, 99] inclusive.
+ int32 storage_utilization_percent = 2
+ [(google.api.field_behavior) = REQUIRED];
+ }
+
+ // AsymmetricAutoscalingOption specifies the scaling of replicas identified by
+ // the given selection.
+ message AsymmetricAutoscalingOption {
+ // Overrides the top-level autoscaling configuration for the replicas
+ // identified by `replica_selection`. All fields in this message are
+ // optional. Any unspecified fields will use the corresponding values from
+ // the top-level autoscaling configuration.
+ message AutoscalingConfigOverrides {
+ // Optional. If specified, overrides the min/max limit in the top-level
+ // autoscaling configuration for the selected replicas.
+ AutoscalingLimits autoscaling_limits = 1
+ [(google.api.field_behavior) = OPTIONAL];
+
+ // Optional. If specified, overrides the autoscaling target
+ // high_priority_cpu_utilization_percent in the top-level autoscaling
+ // configuration for the selected replicas.
+ int32 autoscaling_target_high_priority_cpu_utilization_percent = 2
+ [(google.api.field_behavior) = OPTIONAL];
+
+ // Optional. If specified, overrides the
+ // autoscaling target `total_cpu_utilization_percent`
+ // in the top-level autoscaling configuration for the selected replicas.
+ int32 autoscaling_target_total_cpu_utilization_percent = 4
+ [(google.api.field_behavior) = OPTIONAL];
+
+ // Optional. If true, disables high priority CPU autoscaling for the
+ // selected replicas and ignores
+ // [high_priority_cpu_utilization_percent][google.spanner.admin.instance.v1.AutoscalingConfig.AutoscalingTargets.high_priority_cpu_utilization_percent]
+ // in the top-level autoscaling configuration.
+ //
+ // When setting this field to true, setting
+ // [autoscaling_target_high_priority_cpu_utilization_percent][google.spanner.admin.instance.v1.AutoscalingConfig.AsymmetricAutoscalingOption.AutoscalingConfigOverrides.autoscaling_target_high_priority_cpu_utilization_percent]
+ // field to a non-zero value for the same replica is not supported.
+ //
+ // If false, the
+ // [autoscaling_target_high_priority_cpu_utilization_percent][google.spanner.admin.instance.v1.AutoscalingConfig.AsymmetricAutoscalingOption.AutoscalingConfigOverrides.autoscaling_target_high_priority_cpu_utilization_percent]
+ // field in the replica will be used if set to a non-zero value.
+ // Otherwise, the
+ // [high_priority_cpu_utilization_percent][google.spanner.admin.instance.v1.AutoscalingConfig.AutoscalingTargets.high_priority_cpu_utilization_percent]
+ // field in the top-level autoscaling configuration will be used.
+ //
+ // Setting both
+ // [disable_high_priority_cpu_autoscaling][google.spanner.admin.instance.v1.AutoscalingConfig.AsymmetricAutoscalingOption.AutoscalingConfigOverrides.disable_high_priority_cpu_autoscaling]
+ // and
+ // [disable_total_cpu_autoscaling][google.spanner.admin.instance.v1.AutoscalingConfig.AsymmetricAutoscalingOption.AutoscalingConfigOverrides.disable_total_cpu_autoscaling]
+ // to true for the same replica is not supported.
+ bool disable_high_priority_cpu_autoscaling = 5
+ [(google.api.field_behavior) = OPTIONAL];
+
+ // Optional. If true, disables total CPU autoscaling for the selected
+ // replicas and ignores
+ // [total_cpu_utilization_percent][google.spanner.admin.instance.v1.AutoscalingConfig.AutoscalingTargets.total_cpu_utilization_percent]
+ // in the top-level autoscaling configuration.
+ //
+ // When setting this field to true, setting
+ // [autoscaling_target_total_cpu_utilization_percent][google.spanner.admin.instance.v1.AutoscalingConfig.AsymmetricAutoscalingOption.AutoscalingConfigOverrides.autoscaling_target_total_cpu_utilization_percent]
+ // field to a non-zero value for the same replica is not supported.
+ //
+ // If false, the
+ // [autoscaling_target_total_cpu_utilization_percent][google.spanner.admin.instance.v1.AutoscalingConfig.AsymmetricAutoscalingOption.AutoscalingConfigOverrides.autoscaling_target_total_cpu_utilization_percent]
+ // field in the replica will be used if set to a non-zero value.
+ // Otherwise, the
+ // [total_cpu_utilization_percent][google.spanner.admin.instance.v1.AutoscalingConfig.AutoscalingTargets.total_cpu_utilization_percent]
+ // field in the top-level autoscaling configuration will be used.
+ //
+ // Setting both
+ // [disable_high_priority_cpu_autoscaling][google.spanner.admin.instance.v1.AutoscalingConfig.AsymmetricAutoscalingOption.AutoscalingConfigOverrides.disable_high_priority_cpu_autoscaling]
+ // and
+ // [disable_total_cpu_autoscaling][google.spanner.admin.instance.v1.AutoscalingConfig.AsymmetricAutoscalingOption.AutoscalingConfigOverrides.disable_total_cpu_autoscaling]
+ // to true for the same replica is not supported.
+ bool disable_total_cpu_autoscaling = 6
+ [(google.api.field_behavior) = OPTIONAL];
+ }
+
+ // Required. Selects the replicas to which this AsymmetricAutoscalingOption
+ // applies. Only read-only replicas are supported.
+ ReplicaSelection replica_selection = 1
+ [(google.api.field_behavior) = REQUIRED];
+
+ // Optional. Overrides applied to the top-level autoscaling configuration
+ // for the selected replicas.
+ AutoscalingConfigOverrides overrides = 2
+ [(google.api.field_behavior) = OPTIONAL];
+ }
+
+ // Required. Autoscaling limits for an instance.
+ AutoscalingLimits autoscaling_limits = 1
+ [(google.api.field_behavior) = REQUIRED];
+
+ // Required. The autoscaling targets for an instance.
+ AutoscalingTargets autoscaling_targets = 2
+ [(google.api.field_behavior) = REQUIRED];
+
+ // Optional. Optional asymmetric autoscaling options.
+ // Replicas matching the replica selection criteria will be autoscaled
+ // independently from other replicas. The autoscaler will scale the replicas
+ // based on the utilization of replicas identified by the replica selection.
+ // Replica selections should not overlap with each other.
+ //
+ // Other replicas (those do not match any replica selection) will be
+ // autoscaled together and will have the same compute capacity allocated to
+ // them.
+ repeated AsymmetricAutoscalingOption asymmetric_autoscaling_options = 3
+ [(google.api.field_behavior) = OPTIONAL];
+}
+
+// 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}"
+ plural: "instances"
+ singular: "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;
+ }
+
+ // The type of this instance. The type can be used to distinguish product
+ // variants, that can affect aspects like: usage restrictions, quotas and
+ // billing. Currently this is used to distinguish FREE_INSTANCE vs PROVISIONED
+ // instances.
+ enum InstanceType {
+ // Not specified.
+ INSTANCE_TYPE_UNSPECIFIED = 0;
+
+ // Provisioned instances have dedicated resources, standard usage limits and
+ // support.
+ PROVISIONED = 1;
+
+ // Free instances provide no guarantee for dedicated resources,
+ // [node_count, processing_units] should be 0. They come
+ // with stricter usage limits and limited support.
+ FREE_INSTANCE = 2;
+ }
+
+ // The edition selected for this instance. Different editions provide
+ // different capabilities at different price points.
+ enum Edition {
+ // Edition not specified.
+ EDITION_UNSPECIFIED = 0;
+
+ // Standard edition.
+ STANDARD = 1;
+
+ // Enterprise edition.
+ ENTERPRISE = 2;
+
+ // Enterprise Plus edition.
+ ENTERPRISE_PLUS = 3;
+ }
+
+ // Indicates the
+ // [default backup
+ // schedule](https://cloud.google.com/spanner/docs/backup#default-backup-schedules)
+ // behavior for new databases within the instance.
+ enum DefaultBackupScheduleType {
+ // Not specified.
+ DEFAULT_BACKUP_SCHEDULE_TYPE_UNSPECIFIED = 0;
+
+ // A default backup schedule isn't created automatically when a new database
+ // is created in the instance.
+ NONE = 1;
+
+ // A default backup schedule is created automatically when a new database
+ // is created in the instance. The default backup schedule creates a full
+ // backup every 24 hours. These full backups are retained for 7 days.
+ // You can edit or delete the default backup schedule once it's created.
+ AUTOMATIC = 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 [(google.api.field_behavior) = REQUIRED];
+
+ // 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.field_behavior) = REQUIRED,
+ (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 [(google.api.field_behavior) = REQUIRED];
+
+ // The number of nodes allocated to this instance. At most, one of either
+ // `node_count` or `processing_units` should be present in the message.
+ //
+ // Users can set the `node_count` field to specify the target number of nodes
+ // allocated to the instance.
+ //
+ // If autoscaling is enabled, `node_count` is treated as an `OUTPUT_ONLY`
+ // field and reflects the current number of nodes allocated to the instance.
+ //
+ // This might be zero in API responses for instances that are not yet in the
+ // `READY` state.
+ //
+ //
+ // For more information, see
+ // [Compute capacity, nodes, and processing
+ // units](https://cloud.google.com/spanner/docs/compute-capacity).
+ int32 node_count = 5;
+
+ // The number of processing units allocated to this instance. At most, one of
+ // either `processing_units` or `node_count` should be present in the message.
+ //
+ // Users can set the `processing_units` field to specify the target number of
+ // processing units allocated to the instance.
+ //
+ // If autoscaling is enabled, `processing_units` is treated as an
+ // `OUTPUT_ONLY` field and reflects the current number of processing units
+ // allocated to the instance.
+ //
+ // This might be zero in API responses for instances that are not yet in the
+ // `READY` state.
+ //
+ //
+ // For more information, see
+ // [Compute capacity, nodes and processing
+ // units](https://cloud.google.com/spanner/docs/compute-capacity).
+ int32 processing_units = 9;
+
+ // Output only. Lists the compute capacity per ReplicaSelection. A replica
+ // selection identifies a set of replicas with common properties. Replicas
+ // identified by a ReplicaSelection are scaled with the same compute capacity.
+ repeated ReplicaComputeCapacity replica_compute_capacity = 19
+ [(google.api.field_behavior) = OUTPUT_ONLY];
+
+ // Optional. The autoscaling configuration. Autoscaling is enabled if this
+ // field is set. When autoscaling is enabled, node_count and processing_units
+ // are treated as OUTPUT_ONLY fields and reflect the current compute capacity
+ // allocated to the instance.
+ AutoscalingConfig autoscaling_config = 17
+ [(google.api.field_behavior) = OPTIONAL];
+
+ // 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_-]{0,62}`.
+ // * Label values must be between 0 and 63 characters long and must conform
+ // to the regular expression `[a-z0-9_-]{0,63}`.
+ // * 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;
+
+ // The `InstanceType` of the current instance.
+ InstanceType instance_type = 10;
+
+ // Deprecated. This field is not populated.
+ repeated string endpoint_uris = 8;
+
+ // Output only. The time at which the instance was created.
+ google.protobuf.Timestamp create_time = 11
+ [(google.api.field_behavior) = OUTPUT_ONLY];
+
+ // Output only. The time at which the instance was most recently updated.
+ google.protobuf.Timestamp update_time = 12
+ [(google.api.field_behavior) = OUTPUT_ONLY];
+
+ // Free instance metadata. Only populated for free instances.
+ FreeInstanceMetadata free_instance_metadata = 13;
+
+ // Optional. The `Edition` of the current instance.
+ Edition edition = 20 [(google.api.field_behavior) = OPTIONAL];
+
+ // Optional. Controls the default backup schedule behavior for new databases
+ // within the instance. By default, a backup schedule is created automatically
+ // when a new database is created in a new instance.
+ //
+ // Note that the `AUTOMATIC` value isn't permitted for free instances,
+ // as backups and backup schedules aren't supported for free instances.
+ //
+ // In the `GetInstance` or `ListInstances` response, if the value of
+ // `default_backup_schedule_type` isn't set, or set to `NONE`, Spanner doesn't
+ // create a default backup schedule for new databases in the instance.
+ DefaultBackupScheduleType default_backup_schedule_type = 23
+ [(google.api.field_behavior) = OPTIONAL];
+}
+
+// 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
+// [CreateInstanceConfig][google.spanner.admin.instance.v1.InstanceAdmin.CreateInstanceConfig].
+message CreateInstanceConfigRequest {
+ // Required. The name of the project in which to create the instance
+ // configuration. 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 configuration to create. Valid identifiers
+ // are of the form `custom-[-a-z0-9]*[a-z0-9]` and must be between 2 and 64
+ // characters in length. The `custom-` prefix is required to avoid name
+ // conflicts with Google-managed configurations.
+ string instance_config_id = 2 [(google.api.field_behavior) = REQUIRED];
+
+ // Required. The `InstanceConfig` proto of the configuration to create.
+ // `instance_config.name` must be
+ // `/instanceConfigs/`.
+ // `instance_config.base_config` must be a Google-managed configuration name,
+ // e.g. /instanceConfigs/us-east1, /instanceConfigs/nam3.
+ InstanceConfig instance_config = 3 [(google.api.field_behavior) = REQUIRED];
+
+ // An option to validate, but not actually execute, a request,
+ // and provide the same response.
+ bool validate_only = 4;
+}
+
+// The request for
+// [UpdateInstanceConfig][google.spanner.admin.instance.v1.InstanceAdmin.UpdateInstanceConfig].
+message UpdateInstanceConfigRequest {
+ // Required. The user instance configuration to update, which must always
+ // include the instance configuration name. Otherwise, only fields mentioned
+ // in
+ // [update_mask][google.spanner.admin.instance.v1.UpdateInstanceConfigRequest.update_mask]
+ // need be included. To prevent conflicts of concurrent updates,
+ // [etag][google.spanner.admin.instance.v1.InstanceConfig.reconciling] can
+ // be used.
+ InstanceConfig instance_config = 1 [(google.api.field_behavior) = REQUIRED];
+
+ // Required. A mask specifying which fields in
+ // [InstanceConfig][google.spanner.admin.instance.v1.InstanceConfig] should be
+ // updated. The field mask must always be specified; this prevents any future
+ // fields in [InstanceConfig][google.spanner.admin.instance.v1.InstanceConfig]
+ // from being erased accidentally by clients that do not know about them. Only
+ // display_name and labels can be updated.
+ google.protobuf.FieldMask update_mask = 2
+ [(google.api.field_behavior) = REQUIRED];
+
+ // An option to validate, but not actually execute, a request,
+ // and provide the same response.
+ bool validate_only = 3;
+}
+
+// The request for
+// [DeleteInstanceConfig][google.spanner.admin.instance.v1.InstanceAdmin.DeleteInstanceConfig].
+message DeleteInstanceConfigRequest {
+ // Required. The name of the instance configuration to be deleted.
+ // Values are of the form
+ // `projects//instanceConfigs/`
+ string name = 1 [
+ (google.api.field_behavior) = REQUIRED,
+ (google.api.resource_reference) = {
+ type: "spanner.googleapis.com/InstanceConfig"
+ }
+ ];
+
+ // Used for optimistic concurrency control as a way to help prevent
+ // simultaneous deletes of an instance configuration from overwriting each
+ // other. If not empty, the API
+ // only deletes the instance configuration when the etag provided matches the
+ // current status of the requested instance configuration. Otherwise, deletes
+ // the instance configuration without checking the current status of the
+ // requested instance configuration.
+ string etag = 2;
+
+ // An option to validate, but not actually execute, a request,
+ // and provide the same response.
+ bool validate_only = 3;
+}
+
+// The request for
+// [ListInstanceConfigOperations][google.spanner.admin.instance.v1.InstanceAdmin.ListInstanceConfigOperations].
+message ListInstanceConfigOperationsRequest {
+ // Required. The project of the instance configuration operations.
+ // Values are of the form `projects/`.
+ string parent = 1 [
+ (google.api.field_behavior) = REQUIRED,
+ (google.api.resource_reference) = {
+ type: "cloudresourcemanager.googleapis.com/Project"
+ }
+ ];
+
+ // 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 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
+ // [CreateInstanceConfigMetadata][google.spanner.admin.instance.v1.CreateInstanceConfigMetadata]
+ // is
+ // `type.googleapis.com/google.spanner.admin.instance.v1.CreateInstanceConfigMetadata`.
+ // * `metadata.` - any field in metadata.value.
+ // `metadata.@type` must be specified first, if filtering on metadata
+ // fields.
+ // * `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.instance.v1.CreateInstanceConfigMetadata)
+ // AND` \
+ // `(metadata.instance_config.name:custom-config) AND` \
+ // `(metadata.progress.start_time < \"2021-03-28T14:50:00Z\") AND` \
+ // `(error:*)` - Return operations where:
+ // * The operation's metadata type is
+ // [CreateInstanceConfigMetadata][google.spanner.admin.instance.v1.CreateInstanceConfigMetadata].
+ // * The instance configuration name contains "custom-config".
+ // * The operation started before 2021-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.instance.v1.ListInstanceConfigOperationsResponse.next_page_token]
+ // from a previous
+ // [ListInstanceConfigOperationsResponse][google.spanner.admin.instance.v1.ListInstanceConfigOperationsResponse]
+ // to the same `parent` and with the same `filter`.
+ string page_token = 4;
+}
+
+// The response for
+// [ListInstanceConfigOperations][google.spanner.admin.instance.v1.InstanceAdmin.ListInstanceConfigOperations].
+message ListInstanceConfigOperationsResponse {
+ // The list of matching instance configuration long-running operations. Each
+ // operation's name will be
+ // prefixed by the name of the instance configuration. The operation's
+ // 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
+ // [ListInstanceConfigOperations][google.spanner.admin.instance.v1.InstanceAdmin.ListInstanceConfigOperations]
+ // call to fetch more of the matching metadata.
+ string next_page_token = 2;
+}
+
+// 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;
+
+ // Deadline used while retrieving metadata for instances.
+ // Instances whose metadata cannot be retrieved within this deadline will be
+ // added to
+ // [unreachable][google.spanner.admin.instance.v1.ListInstancesResponse.unreachable]
+ // in
+ // [ListInstancesResponse][google.spanner.admin.instance.v1.ListInstancesResponse].
+ google.protobuf.Timestamp instance_deadline = 5;
+}
+
+// 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 list of unreachable instances.
+ // It includes the names of instances whose metadata could not be retrieved
+ // within
+ // [instance_deadline][google.spanner.admin.instance.v1.ListInstancesRequest.instance_deadline].
+ repeated string unreachable = 3;
+}
+
+// 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;
+
+ // The expected fulfillment period of this create operation.
+ FulfillmentPeriod expected_fulfillment_period = 5;
+}
+
+// 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;
+
+ // The expected fulfillment period of this update operation.
+ FulfillmentPeriod expected_fulfillment_period = 5;
+}
+
+// Free instance specific metadata that is kept even after an instance has been
+// upgraded for tracking purposes.
+message FreeInstanceMetadata {
+ // Allows users to change behavior when a free instance expires.
+ enum ExpireBehavior {
+ // Not specified.
+ EXPIRE_BEHAVIOR_UNSPECIFIED = 0;
+
+ // When the free instance expires, upgrade the instance to a provisioned
+ // instance.
+ FREE_TO_PROVISIONED = 1;
+
+ // When the free instance expires, disable the instance, and delete it
+ // after the grace period passes if it has not been upgraded.
+ REMOVE_AFTER_GRACE_PERIOD = 2;
+ }
+
+ // Output only. Timestamp after which the instance will either be upgraded or
+ // scheduled for deletion after a grace period. ExpireBehavior is used to
+ // choose between upgrading or scheduling the free instance for deletion. This
+ // timestamp is set during the creation of a free instance.
+ google.protobuf.Timestamp expire_time = 1
+ [(google.api.field_behavior) = OUTPUT_ONLY];
+
+ // Output only. If present, the timestamp at which the free instance was
+ // upgraded to a provisioned instance.
+ google.protobuf.Timestamp upgrade_time = 2
+ [(google.api.field_behavior) = OUTPUT_ONLY];
+
+ // Specifies the expiration behavior of a free instance. The default of
+ // ExpireBehavior is `REMOVE_AFTER_GRACE_PERIOD`. This can be modified during
+ // or after creation, and before expiration.
+ ExpireBehavior expire_behavior = 3;
+}
+
+// Metadata type for the operation returned by
+// [CreateInstanceConfig][google.spanner.admin.instance.v1.InstanceAdmin.CreateInstanceConfig].
+message CreateInstanceConfigMetadata {
+ // The target instance configuration end state.
+ InstanceConfig instance_config = 1;
+
+ // The progress of the
+ // [CreateInstanceConfig][google.spanner.admin.instance.v1.InstanceAdmin.CreateInstanceConfig]
+ // operation.
+ OperationProgress progress = 2;
+
+ // The time at which this operation was cancelled.
+ google.protobuf.Timestamp cancel_time = 3;
+}
+
+// Metadata type for the operation returned by
+// [UpdateInstanceConfig][google.spanner.admin.instance.v1.InstanceAdmin.UpdateInstanceConfig].
+message UpdateInstanceConfigMetadata {
+ // The desired instance configuration after updating.
+ InstanceConfig instance_config = 1;
+
+ // The progress of the
+ // [UpdateInstanceConfig][google.spanner.admin.instance.v1.InstanceAdmin.UpdateInstanceConfig]
+ // operation.
+ OperationProgress progress = 2;
+
+ // The time at which this operation was cancelled.
+ google.protobuf.Timestamp cancel_time = 3;
+}
+
+// An isolated set of Cloud Spanner resources that databases can define
+// placements on.
+message InstancePartition {
+ option (google.api.resource) = {
+ type: "spanner.googleapis.com/InstancePartition"
+ pattern: "projects/{project}/instances/{instance}/instancePartitions/{instance_partition}"
+ plural: "instancePartitions"
+ singular: "instancePartition"
+ };
+
+ // Indicates the current state of the instance partition.
+ enum State {
+ // Not specified.
+ STATE_UNSPECIFIED = 0;
+
+ // The instance partition is still being created. Resources may not be
+ // available yet, and operations such as creating placements using this
+ // instance partition may not work.
+ CREATING = 1;
+
+ // The instance partition is fully created and ready to do work such as
+ // creating placements and using in databases.
+ READY = 2;
+ }
+
+ // Required. A unique identifier for the instance partition. Values are of the
+ // form
+ // `projects//instances//instancePartitions/[a-z][-a-z0-9]*[a-z0-9]`.
+ // The final segment of the name must be between 2 and 64 characters in
+ // length. An instance partition's name cannot be changed after the instance
+ // partition is created.
+ string name = 1 [(google.api.field_behavior) = REQUIRED];
+
+ // Required. The name of the instance partition'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.field_behavior) = REQUIRED,
+ (google.api.resource_reference) = {
+ type: "spanner.googleapis.com/InstanceConfig"
+ }
+ ];
+
+ // Required. The descriptive name for this instance partition as it appears in
+ // UIs. Must be unique per project and between 4 and 30 characters in length.
+ string display_name = 3 [(google.api.field_behavior) = REQUIRED];
+
+ // Compute capacity defines amount of server and storage resources that are
+ // available to the databases in an instance partition. At most, one of either
+ // `node_count` or` processing_units` should be present in the message. For
+ // more information, see
+ // [Compute capacity, nodes, and processing
+ // units](https://cloud.google.com/spanner/docs/compute-capacity).
+ oneof compute_capacity {
+ // The number of nodes allocated to this instance partition.
+ //
+ // Users can set the `node_count` field to specify the target number of
+ // nodes allocated to the instance partition.
+ //
+ // This may be zero in API responses for instance partitions that are not
+ // yet in state `READY`.
+ int32 node_count = 5;
+
+ // The number of processing units allocated to this instance partition.
+ //
+ // Users can set the `processing_units` field to specify the target number
+ // of processing units allocated to the instance partition.
+ //
+ // This might be zero in API responses for instance partitions that are not
+ // yet in the `READY` state.
+ int32 processing_units = 6;
+ }
+
+ // Optional. The autoscaling configuration. Autoscaling is enabled if this
+ // field is set. When autoscaling is enabled, fields in compute_capacity are
+ // treated as OUTPUT_ONLY fields and reflect the current compute capacity
+ // allocated to the instance partition.
+ AutoscalingConfig autoscaling_config = 13
+ [(google.api.field_behavior) = OPTIONAL];
+
+ // Output only. The current instance partition state.
+ State state = 7 [(google.api.field_behavior) = OUTPUT_ONLY];
+
+ // Output only. The time at which the instance partition was created.
+ google.protobuf.Timestamp create_time = 8
+ [(google.api.field_behavior) = OUTPUT_ONLY];
+
+ // Output only. The time at which the instance partition was most recently
+ // updated.
+ google.protobuf.Timestamp update_time = 9
+ [(google.api.field_behavior) = OUTPUT_ONLY];
+
+ // Output only. The names of the databases that reference this
+ // instance partition. Referencing databases should share the parent instance.
+ // The existence of any referencing database prevents the instance partition
+ // from being deleted.
+ repeated string referencing_databases = 10
+ [(google.api.field_behavior) = OUTPUT_ONLY];
+
+ // Output only. Deprecated: This field is not populated.
+ // Output only. The names of the backups that reference this instance
+ // partition. Referencing backups should share the parent instance. The
+ // existence of any referencing backup prevents the instance partition from
+ // being deleted.
+ repeated string referencing_backups = 11
+ [deprecated = true, (google.api.field_behavior) = OUTPUT_ONLY];
+
+ // Used for optimistic concurrency control as a way
+ // to help prevent simultaneous updates of a instance partition from
+ // overwriting each other. It is strongly suggested that systems make use of
+ // the etag in the read-modify-write cycle to perform instance partition
+ // updates in order to avoid race conditions: An etag is returned in the
+ // response which contains instance partitions, and systems are expected to
+ // put that etag in the request to update instance partitions to ensure that
+ // their change will be applied to the same version of the instance partition.
+ // If no etag is provided in the call to update instance partition, then the
+ // existing instance partition is overwritten blindly.
+ string etag = 12;
+}
+
+// Metadata type for the operation returned by
+// [CreateInstancePartition][google.spanner.admin.instance.v1.InstanceAdmin.CreateInstancePartition].
+message CreateInstancePartitionMetadata {
+ // The instance partition being created.
+ InstancePartition instance_partition = 1;
+
+ // The time at which the
+ // [CreateInstancePartition][google.spanner.admin.instance.v1.InstanceAdmin.CreateInstancePartition]
+ // 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;
+}
+
+// The request for
+// [CreateInstancePartition][google.spanner.admin.instance.v1.InstanceAdmin.CreateInstancePartition].
+message CreateInstancePartitionRequest {
+ // Required. The name of the instance in which to create the instance
+ // partition. 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 instance partition 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_partition_id = 2 [(google.api.field_behavior) = REQUIRED];
+
+ // Required. The instance partition to create. The instance_partition.name may
+ // be omitted, but if specified must be
+ // `/instancePartitions/`.
+ InstancePartition instance_partition = 3
+ [(google.api.field_behavior) = REQUIRED];
+}
+
+// The request for
+// [DeleteInstancePartition][google.spanner.admin.instance.v1.InstanceAdmin.DeleteInstancePartition].
+message DeleteInstancePartitionRequest {
+ // Required. The name of the instance partition to be deleted.
+ // Values are of the form
+ // `projects/{project}/instances/{instance}/instancePartitions/{instance_partition}`
+ string name = 1 [
+ (google.api.field_behavior) = REQUIRED,
+ (google.api.resource_reference) = {
+ type: "spanner.googleapis.com/InstancePartition"
+ }
+ ];
+
+ // Optional. If not empty, the API only deletes the instance partition when
+ // the etag provided matches the current status of the requested instance
+ // partition. Otherwise, deletes the instance partition without checking the
+ // current status of the requested instance partition.
+ string etag = 2;
+}
+
+// The request for
+// [GetInstancePartition][google.spanner.admin.instance.v1.InstanceAdmin.GetInstancePartition].
+message GetInstancePartitionRequest {
+ // Required. The name of the requested instance partition. Values are of
+ // the form
+ // `projects/{project}/instances/{instance}/instancePartitions/{instance_partition}`.
+ string name = 1 [
+ (google.api.field_behavior) = REQUIRED,
+ (google.api.resource_reference) = {
+ type: "spanner.googleapis.com/InstancePartition"
+ }
+ ];
+}
+
+// The request for
+// [UpdateInstancePartition][google.spanner.admin.instance.v1.InstanceAdmin.UpdateInstancePartition].
+message UpdateInstancePartitionRequest {
+ // Required. The instance partition to update, which must always include the
+ // instance partition name. Otherwise, only fields mentioned in
+ // [field_mask][google.spanner.admin.instance.v1.UpdateInstancePartitionRequest.field_mask]
+ // need be included.
+ InstancePartition instance_partition = 1
+ [(google.api.field_behavior) = REQUIRED];
+
+ // Required. A mask specifying which fields in
+ // [InstancePartition][google.spanner.admin.instance.v1.InstancePartition]
+ // should be updated. The field mask must always be specified; this prevents
+ // any future fields in
+ // [InstancePartition][google.spanner.admin.instance.v1.InstancePartition]
+ // from being erased accidentally by clients that do not know about them.
+ google.protobuf.FieldMask field_mask = 2
+ [(google.api.field_behavior) = REQUIRED];
+}
+
+// Metadata type for the operation returned by
+// [UpdateInstancePartition][google.spanner.admin.instance.v1.InstanceAdmin.UpdateInstancePartition].
+message UpdateInstancePartitionMetadata {
+ // The desired end state of the update.
+ InstancePartition instance_partition = 1;
+
+ // The time at which
+ // [UpdateInstancePartition][google.spanner.admin.instance.v1.InstanceAdmin.UpdateInstancePartition]
+ // 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;
+}
+
+// The request for
+// [ListInstancePartitions][google.spanner.admin.instance.v1.InstanceAdmin.ListInstancePartitions].
+message ListInstancePartitionsRequest {
+ // Required. The instance whose instance partitions should be listed. Values
+ // are of the form `projects//instances/`. Use `{instance}
+ // = '-'` to list instance partitions for all Instances in a project, e.g.,
+ // `projects/myproject/instances/-`.
+ string parent = 1 [
+ (google.api.field_behavior) = REQUIRED,
+ (google.api.resource_reference) = {
+ type: "spanner.googleapis.com/Instance"
+ }
+ ];
+
+ // Number of instance partitions 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.ListInstancePartitionsResponse.next_page_token]
+ // from a previous
+ // [ListInstancePartitionsResponse][google.spanner.admin.instance.v1.ListInstancePartitionsResponse].
+ string page_token = 3;
+
+ // Optional. Deadline used while retrieving metadata for instance partitions.
+ // Instance partitions whose metadata cannot be retrieved within this deadline
+ // will be added to
+ // [unreachable][google.spanner.admin.instance.v1.ListInstancePartitionsResponse.unreachable]
+ // in
+ // [ListInstancePartitionsResponse][google.spanner.admin.instance.v1.ListInstancePartitionsResponse].
+ google.protobuf.Timestamp instance_partition_deadline = 4
+ [(google.api.field_behavior) = OPTIONAL];
+}
+
+// The response for
+// [ListInstancePartitions][google.spanner.admin.instance.v1.InstanceAdmin.ListInstancePartitions].
+message ListInstancePartitionsResponse {
+ // The list of requested instancePartitions.
+ repeated InstancePartition instance_partitions = 1;
+
+ // `next_page_token` can be sent in a subsequent
+ // [ListInstancePartitions][google.spanner.admin.instance.v1.InstanceAdmin.ListInstancePartitions]
+ // call to fetch more of the matching instance partitions.
+ string next_page_token = 2;
+
+ // The list of unreachable instances or instance partitions.
+ // It includes the names of instances or instance partitions whose metadata
+ // could not be retrieved within
+ // [instance_partition_deadline][google.spanner.admin.instance.v1.ListInstancePartitionsRequest.instance_partition_deadline].
+ repeated string unreachable = 3;
+}
+
+// The request for
+// [ListInstancePartitionOperations][google.spanner.admin.instance.v1.InstanceAdmin.ListInstancePartitionOperations].
+message ListInstancePartitionOperationsRequest {
+ // Required. The parent instance of the instance partition 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"
+ }
+ ];
+
+ // Optional. 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 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
+ // [CreateInstancePartitionMetadata][google.spanner.admin.instance.v1.CreateInstancePartitionMetadata]
+ // is
+ // `type.googleapis.com/google.spanner.admin.instance.v1.CreateInstancePartitionMetadata`.
+ // * `metadata.` - any field in metadata.value.
+ // `metadata.@type` must be specified first, if filtering on metadata
+ // fields.
+ // * `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.instance.v1.CreateInstancePartitionMetadata)
+ // AND` \
+ // `(metadata.instance_partition.name:custom-instance-partition) AND` \
+ // `(metadata.start_time < \"2021-03-28T14:50:00Z\") AND` \
+ // `(error:*)` - Return operations where:
+ // * The operation's metadata type is
+ // [CreateInstancePartitionMetadata][google.spanner.admin.instance.v1.CreateInstancePartitionMetadata].
+ // * The instance partition name contains "custom-instance-partition".
+ // * The operation started before 2021-03-28T14:50:00Z.
+ // * The operation resulted in an error.
+ string filter = 2 [(google.api.field_behavior) = OPTIONAL];
+
+ // Optional. 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 [(google.api.field_behavior) = OPTIONAL];
+
+ // Optional. If non-empty, `page_token` should contain a
+ // [next_page_token][google.spanner.admin.instance.v1.ListInstancePartitionOperationsResponse.next_page_token]
+ // from a previous
+ // [ListInstancePartitionOperationsResponse][google.spanner.admin.instance.v1.ListInstancePartitionOperationsResponse]
+ // to the same `parent` and with the same `filter`.
+ string page_token = 4 [(google.api.field_behavior) = OPTIONAL];
+
+ // Optional. Deadline used while retrieving metadata for instance partition
+ // operations. Instance partitions whose operation metadata cannot be
+ // retrieved within this deadline will be added to
+ // [unreachable_instance_partitions][google.spanner.admin.instance.v1.ListInstancePartitionOperationsResponse.unreachable_instance_partitions]
+ // in
+ // [ListInstancePartitionOperationsResponse][google.spanner.admin.instance.v1.ListInstancePartitionOperationsResponse].
+ google.protobuf.Timestamp instance_partition_deadline = 5
+ [(google.api.field_behavior) = OPTIONAL];
+}
+
+// The response for
+// [ListInstancePartitionOperations][google.spanner.admin.instance.v1.InstanceAdmin.ListInstancePartitionOperations].
+message ListInstancePartitionOperationsResponse {
+ // The list of matching instance partition long-running operations. Each
+ // operation's name will be
+ // prefixed by the instance partition's name. The operation's
+ // 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
+ // [ListInstancePartitionOperations][google.spanner.admin.instance.v1.InstanceAdmin.ListInstancePartitionOperations]
+ // call to fetch more of the matching metadata.
+ string next_page_token = 2;
+
+ // The list of unreachable instance partitions.
+ // It includes the names of instance partitions whose operation metadata could
+ // not be retrieved within
+ // [instance_partition_deadline][google.spanner.admin.instance.v1.ListInstancePartitionOperationsRequest.instance_partition_deadline].
+ repeated string unreachable_instance_partitions = 3;
+}
+
+// The request for
+// [MoveInstance][google.spanner.admin.instance.v1.InstanceAdmin.MoveInstance].
+message MoveInstanceRequest {
+ // Required. The instance to move.
+ // Values are of the form `projects//instances/`.
+ string name = 1 [
+ (google.api.field_behavior) = REQUIRED,
+ (google.api.resource_reference) = {
+ type: "spanner.googleapis.com/Instance"
+ }
+ ];
+
+ // Required. The target instance configuration where to move the instance.
+ // Values are of the form `projects//instanceConfigs/`.
+ string target_config = 2 [
+ (google.api.field_behavior) = REQUIRED,
+ (google.api.resource_reference) = {
+ type: "spanner.googleapis.com/InstanceConfig"
+ }
+ ];
+}
+
+// The response for
+// [MoveInstance][google.spanner.admin.instance.v1.InstanceAdmin.MoveInstance].
+message MoveInstanceResponse {}
+
+// Metadata type for the operation returned by
+// [MoveInstance][google.spanner.admin.instance.v1.InstanceAdmin.MoveInstance].
+message MoveInstanceMetadata {
+ // The target instance configuration where to move the instance.
+ // Values are of the form `projects//instanceConfigs/`.
+ string target_config = 1;
+
+ // The progress of the
+ // [MoveInstance][google.spanner.admin.instance.v1.InstanceAdmin.MoveInstance]
+ // operation.
+ // [progress_percent][google.spanner.admin.instance.v1.OperationProgress.progress_percent]
+ // is reset when cancellation is requested.
+ OperationProgress progress = 2;
+
+ // The time at which this operation was cancelled.
+ google.protobuf.Timestamp cancel_time = 3;
+}
diff --git a/packages/google-cloud-spanner-api/protos/google/spanner/executor/v1/cloud_executor.proto b/packages/google-cloud-spanner-api/protos/google/spanner/executor/v1/cloud_executor.proto
new file mode 100644
index 000000000000..5ca3b25ac2a2
--- /dev/null
+++ b/packages/google-cloud-spanner-api/protos/google/spanner/executor/v1/cloud_executor.proto
@@ -0,0 +1,1604 @@
+// Copyright 2026 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.executor.v1;
+
+import "google/api/client.proto";
+import "google/api/field_behavior.proto";
+import "google/longrunning/operations.proto";
+import "google/protobuf/timestamp.proto";
+import "google/rpc/status.proto";
+import "google/spanner/admin/database/v1/backup.proto";
+import "google/spanner/admin/database/v1/common.proto";
+import "google/spanner/admin/database/v1/spanner_database_admin.proto";
+import "google/spanner/admin/instance/v1/spanner_instance_admin.proto";
+import "google/spanner/v1/spanner.proto";
+import "google/spanner/v1/type.proto";
+
+option go_package = "cloud.google.com/go/spanner/executor/apiv1/executorpb;executorpb";
+option java_multiple_files = true;
+option java_outer_classname = "CloudExecutorProto";
+option java_package = "com.google.spanner.executor.v1";
+
+// Service that executes SpannerActions asynchronously.
+service SpannerExecutorProxy {
+ option (google.api.default_host) = "spanner-cloud-executor.googleapis.com";
+
+ // ExecuteActionAsync is a streaming call that starts executing a new Spanner
+ // action.
+ //
+ // For each request, the server will reply with one or more responses, but
+ // only the last response will contain status in the outcome.
+ //
+ // Responses can be matched to requests by action_id. It is allowed to have
+ // multiple actions in flight--in that case, actions are be executed in
+ // parallel.
+ rpc ExecuteActionAsync(stream SpannerAsyncActionRequest)
+ returns (stream SpannerAsyncActionResponse) {}
+}
+
+// Request to executor service that start a new Spanner action.
+message SpannerAsyncActionRequest {
+ // Action id to uniquely identify this action request.
+ int32 action_id = 1;
+
+ // The actual SpannerAction to perform.
+ SpannerAction action = 2;
+}
+
+// Response from executor service.
+message SpannerAsyncActionResponse {
+ // Action id corresponds to the request.
+ int32 action_id = 1;
+
+ // If action results are split into multiple responses, only the last response
+ // can and should contain status.
+ SpannerActionOutcome outcome = 2;
+}
+
+// SpannerAction defines a primitive action that can be performed against
+// Spanner, such as begin or commit a transaction, or perform a read or
+// mutation.
+message SpannerAction {
+ // Database against which to perform action.
+ // In a context where a series of actions take place, an action may omit
+ // database path if it applies to the same database as the previous action.
+ string database_path = 1;
+
+ // Configuration options for Spanner backend
+ SpannerOptions spanner_options = 2;
+
+ // Action represents a spanner action kind, there will only be one action kind
+ // per SpannerAction.
+ oneof action {
+ // Action to start a transaction.
+ StartTransactionAction start = 10;
+
+ // Action to finish a transaction.
+ FinishTransactionAction finish = 11;
+
+ // Action to do a normal read.
+ ReadAction read = 20;
+
+ // Action to do a query.
+ QueryAction query = 21;
+
+ // Action to buffer a mutation.
+ MutationAction mutation = 22;
+
+ // Action to a DML.
+ DmlAction dml = 23;
+
+ // Action to a batch DML.
+ BatchDmlAction batch_dml = 24;
+
+ // Action to write a mutation.
+ WriteMutationsAction write = 25;
+
+ // Action to a partitioned update.
+ PartitionedUpdateAction partitioned_update = 27;
+
+ // Action that contains any administrative operation, like database,
+ // instance manipulation.
+ AdminAction admin = 30;
+
+ // Action to start a batch transaction.
+ StartBatchTransactionAction start_batch_txn = 40;
+
+ // Action to close a batch transaction.
+ CloseBatchTransactionAction close_batch_txn = 41;
+
+ // Action to generate database partitions for batch read.
+ GenerateDbPartitionsForReadAction generate_db_partitions_read = 42;
+
+ // Action to generate database partitions for batch query.
+ GenerateDbPartitionsForQueryAction generate_db_partitions_query = 43;
+
+ // Action to execute batch actions on generated partitions.
+ ExecutePartitionAction execute_partition = 44;
+
+ // Action to execute change stream query.
+ ExecuteChangeStreamQuery execute_change_stream_query = 50;
+
+ // Query cancellation action for testing the cancellation of a query.
+ QueryCancellationAction query_cancellation = 51;
+
+ // Action to adapt a message.
+ AdaptMessageAction adapt_message = 52;
+ }
+}
+
+// A single read request.
+message ReadAction {
+ // The table to read at.
+ string table = 1;
+
+ // The index to read at if it's an index read.
+ optional string index = 2;
+
+ // List of columns must begin with the key columns used for the read.
+ repeated string column = 3;
+
+ // Keys for performing this read.
+ KeySet keys = 4;
+
+ // Limit on number of rows to read. If set, must be positive.
+ int32 limit = 5;
+}
+
+// A SQL query request.
+message QueryAction {
+ // Parameter that bind to placeholders in the SQL string
+ message Parameter {
+ // Name of the parameter (with no leading @).
+ string name = 1;
+
+ // Type of the parameter.
+ google.spanner.v1.Type type = 2;
+
+ // Value of the parameter.
+ Value value = 3;
+ }
+
+ // The SQL string.
+ string sql = 1;
+
+ // Parameters for the SQL string.
+ repeated Parameter params = 2;
+}
+
+// A single DML statement.
+message DmlAction {
+ // DML statement.
+ QueryAction update = 1;
+
+ // Whether to autocommit the transaction after executing the DML statement,
+ // if the Executor supports autocommit.
+ optional bool autocommit_if_supported = 2;
+
+ // Whether to set this DML statement as the last statement in the
+ // transaction. The transaction should be committed after processing this DML
+ // statement.
+ optional bool last_statement = 3;
+}
+
+// Batch of DML statements invoked using batched execution.
+message BatchDmlAction {
+ // DML statements.
+ repeated QueryAction updates = 1;
+
+ // Whether to set this request with the last statement option in the
+ // transaction. The transaction should be committed after processing this
+ // request.
+ optional bool last_statements = 2;
+}
+
+// Value represents a single value that can be read or written to/from
+// Spanner.
+message Value {
+ // Exactly one of the following fields will be present.
+ oneof value_type {
+ // If is_null is set, then this value is null.
+ bool is_null = 1;
+
+ // Int type value. It's used for all integer number types, like int32 and
+ // int64.
+ int64 int_value = 2;
+
+ // Bool type value.
+ bool bool_value = 3;
+
+ // Double type value. It's used for all float point types, like float and
+ // double.
+ double double_value = 4;
+
+ // Bytes type value, stored in CORD. It's also used for PROTO type value.
+ bytes bytes_value = 5;
+
+ // String type value, stored in CORD.
+ string string_value = 6;
+
+ // Struct type value. It contains a ValueList representing the values in
+ // this struct.
+ ValueList struct_value = 7;
+
+ // Timestamp type value.
+ google.protobuf.Timestamp timestamp_value = 8;
+
+ // Date type value. Date is specified as a number of days since Unix epoch.
+ int32 date_days_value = 9;
+
+ // If set, holds the sentinel value for the transaction CommitTimestamp.
+ bool is_commit_timestamp = 10;
+
+ // Array type value. The underlying Valuelist should have values that have
+ // the same type.
+ ValueList array_value = 11;
+ }
+
+ // Type of array element. Only set if value is an array.
+ optional google.spanner.v1.Type array_type = 12;
+}
+
+// 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 "ValueList", where the ith value in the list
+// corresponds to the ith component of the table or index primary key.
+message KeyRange {
+ // Type controls whether "start" and "limit" are open or closed. By default,
+ // "start" is closed, and "limit" is open.
+ enum Type {
+ // "TYPE_UNSPECIFIED" is equivalent to "CLOSED_OPEN".
+ TYPE_UNSPECIFIED = 0;
+
+ // [start,limit]
+ CLOSED_CLOSED = 1;
+
+ // [start,limit)
+ CLOSED_OPEN = 2;
+
+ // (start,limit]
+ OPEN_CLOSED = 3;
+
+ // (start,limit)
+ OPEN_OPEN = 4;
+ }
+
+ // "start" and "limit" must have the same number of key parts,
+ // though they may name only a prefix of the table or index key.
+ // The start key of this KeyRange.
+ ValueList start = 1;
+
+ // The end key of this KeyRange.
+ ValueList limit = 2;
+
+ // "start" and "limit" type for this KeyRange.
+ optional Type type = 3;
+}
+
+// KeySet defines a collection of Spanner keys and/or key ranges. All
+// the keys are expected to be in the same table. The keys need not be
+// sorted in any particular way.
+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.
+ repeated ValueList point = 1;
+
+ // A list of key ranges.
+ repeated KeyRange range = 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;
+}
+
+// List of values.
+message ValueList {
+ // Values contained in this ValueList.
+ repeated Value value = 1;
+}
+
+// A single mutation request.
+message MutationAction {
+ // Arguments to Insert, InsertOrUpdate, and Replace operations.
+ message InsertArgs {
+ // The names of the columns to be written.
+ repeated string column = 1;
+
+ // Type information for the "values" entries below.
+ repeated google.spanner.v1.Type type = 2;
+
+ // The values to be written.
+ repeated ValueList values = 3;
+ }
+
+ // Arguments to Update.
+ message UpdateArgs {
+ // The columns to be updated. Identical to InsertArgs.column.
+ repeated string column = 1;
+
+ // Type information for "values". Identical to InsertArgs.type.
+ repeated google.spanner.v1.Type type = 2;
+
+ // The values to be updated. Identical to InsertArgs.values.
+ repeated ValueList values = 3;
+ }
+
+ // Mod represents the write action that will be perform to a table. Each mod
+ // will specify exactly one action, from insert, update, insert_or_update,
+ // replace and delete.
+ message Mod {
+ // The table to write.
+ string table = 1;
+
+ // Exactly one of the remaining elements may be present.
+ // Insert new rows into "table".
+ InsertArgs insert = 2;
+
+ // Update columns stored in existing rows of "table".
+ UpdateArgs update = 3;
+
+ // Insert or update existing rows of "table".
+ InsertArgs insert_or_update = 4;
+
+ // Replace existing rows of "table".
+ InsertArgs replace = 5;
+
+ // Delete rows from "table".
+ KeySet delete_keys = 6;
+ }
+
+ // Mods that contained in this mutation.
+ repeated Mod mod = 1;
+}
+
+// WriteMutationAction defines an action of flushing the mutation so they
+// are visible to subsequent operations in the transaction.
+message WriteMutationsAction {
+ // The mutation to write.
+ MutationAction mutation = 1;
+}
+
+// PartitionedUpdateAction defines an action to execute a partitioned DML
+// which runs different partitions in parallel.
+message PartitionedUpdateAction {
+ message ExecutePartitionedUpdateOptions {
+ // RPC Priority
+ optional google.spanner.v1.RequestOptions.Priority rpc_priority = 1;
+
+ // Transaction tag
+ optional string tag = 2;
+ }
+
+ // Options for partitioned update.
+ optional ExecutePartitionedUpdateOptions options = 1;
+
+ // Partitioned dml query.
+ QueryAction update = 2;
+}
+
+// StartTransactionAction defines an action of initializing a transaction.
+message StartTransactionAction {
+ // Concurrency is for read-only transactions and must be omitted for
+ // read-write transactions.
+ optional Concurrency concurrency = 1;
+
+ // Metadata about tables and columns that will be involved in this
+ // transaction. It is to convert values of key parts correctly.
+ repeated TableMetadata table = 2;
+
+ // Transaction_seed contains workid and op pair for this transaction, used for
+ // testing.
+ string transaction_seed = 3;
+
+ // Execution options (e.g., whether transaction is opaque, optimistic,
+ // excluded from change streams).
+ optional TransactionExecutionOptions execution_options = 4;
+}
+
+// Concurrency for read-only transactions.
+message Concurrency {
+ // Concurrency mode set for read-only transactions, exactly one mode below
+ // should be set.
+ oneof concurrency_mode {
+ // Indicates a read at a consistent timestamp that is specified relative to
+ // now. That is, if the caller has specified an exact staleness of s
+ // seconds, we will read at now - s.
+ double staleness_seconds = 1;
+
+ // Indicates a boundedly stale read that reads at a timestamp >= T.
+ int64 min_read_timestamp_micros = 2;
+
+ // Indicates a boundedly stale read that is at most N seconds stale.
+ double max_staleness_seconds = 3;
+
+ // Indicates a read at a consistent timestamp.
+ int64 exact_timestamp_micros = 4;
+
+ // Indicates a strong read, must only be set to true, or unset.
+ bool strong = 5;
+
+ // Indicates a batch read, must only be set to true, or unset.
+ bool batch = 6;
+ }
+
+ // True if exact_timestamp_micros is set, and the chosen timestamp is that of
+ // a snapshot epoch.
+ bool snapshot_epoch_read = 7;
+
+ // If set, this is a snapshot epoch read constrained to read only the
+ // specified log scope root table, and its children. Will not be set for full
+ // database epochs.
+ string snapshot_epoch_root_table = 8;
+
+ // Set only when batch is true.
+ int64 batch_read_timestamp_micros = 9;
+}
+
+// TableMetadata contains metadata of a single table.
+message TableMetadata {
+ // Table name.
+ string name = 1;
+
+ // Columns, in the same order as in the schema.
+ repeated ColumnMetadata column = 2;
+
+ // Keys, in order. Column name is currently not populated.
+ repeated ColumnMetadata key_column = 3;
+}
+
+// ColumnMetadata represents metadata of a single column.
+message ColumnMetadata {
+ // Column name.
+ string name = 1;
+
+ // Column type.
+ google.spanner.v1.Type type = 2;
+}
+
+message TransactionExecutionOptions {
+ // Whether optimistic concurrency should be used to execute this transaction.
+ bool optimistic = 1;
+
+ // Whether traffic from this transaction will be excluded from tracking change
+ // streams with allow_txn_exclusion=true.
+ bool exclude_from_change_streams = 2;
+
+ // Whether serializable isolation with optimistic mode concurrency should be
+ // used to execute this transaction.
+ bool serializable_optimistic = 3;
+
+ // Whether snapshot isolation with optimistic mode concurrency should be used
+ // to execute this transaction.
+ bool snapshot_isolation_optimistic = 4;
+
+ // Whether snapshot isolation with pessimistic mode concurrency should be used
+ // to execute this transaction.
+ bool snapshot_isolation_pessimistic = 5;
+
+ // Whether to exclude mutations of this transaction from the allowed tracking
+ // change streams.
+ bool exclude_txn_from_change_streams = 6;
+}
+
+// FinishTransactionAction defines an action of finishing a transaction.
+message FinishTransactionAction {
+ // Mode indicates how the transaction should be finished.
+ enum Mode {
+ // "MODE_UNSPECIFIED" is equivalent to "COMMIT".
+ MODE_UNSPECIFIED = 0;
+
+ // Commit the transaction.
+ COMMIT = 1;
+
+ // Drop the transaction without committing it.
+ ABANDON = 2;
+ }
+
+ // Defines how exactly the transaction should be completed, e.g. with
+ // commit or abortion.
+ Mode mode = 1;
+}
+
+// AdminAction defines all the cloud spanner admin actions, including
+// instance/database admin ops, backup ops and operation actions.
+message AdminAction {
+ // Exactly one of the actions below will be performed in AdminAction.
+ oneof action {
+ // Action that creates a user instance config.
+ CreateUserInstanceConfigAction create_user_instance_config = 1;
+
+ // Action that updates a user instance config.
+ UpdateUserInstanceConfigAction update_user_instance_config = 2;
+
+ // Action that deletes a user instance config.
+ DeleteUserInstanceConfigAction delete_user_instance_config = 3;
+
+ // Action that gets a user instance config.
+ GetCloudInstanceConfigAction get_cloud_instance_config = 4;
+
+ // Action that lists user instance configs.
+ ListCloudInstanceConfigsAction list_instance_configs = 5;
+
+ // Action that creates a Cloud Spanner instance.
+ CreateCloudInstanceAction create_cloud_instance = 6;
+
+ // Action that updates a Cloud Spanner instance.
+ UpdateCloudInstanceAction update_cloud_instance = 7;
+
+ // Action that deletes a Cloud Spanner instance.
+ DeleteCloudInstanceAction delete_cloud_instance = 8;
+
+ // Action that lists Cloud Spanner instances.
+ ListCloudInstancesAction list_cloud_instances = 9;
+
+ // Action that retrieves a Cloud Spanner instance.
+ GetCloudInstanceAction get_cloud_instance = 10;
+
+ // Action that creates a Cloud Spanner database.
+ CreateCloudDatabaseAction create_cloud_database = 11;
+
+ // Action that updates the schema of a Cloud Spanner database.
+ UpdateCloudDatabaseDdlAction update_cloud_database_ddl = 12;
+
+ // Action that updates the schema of a Cloud Spanner database.
+ UpdateCloudDatabaseAction update_cloud_database = 27;
+
+ // Action that drops a Cloud Spanner database.
+ DropCloudDatabaseAction drop_cloud_database = 13;
+
+ // Action that lists Cloud Spanner databases.
+ ListCloudDatabasesAction list_cloud_databases = 14;
+
+ // Action that lists Cloud Spanner database operations.
+ ListCloudDatabaseOperationsAction list_cloud_database_operations = 15;
+
+ // Action that restores a Cloud Spanner database from a backup.
+ RestoreCloudDatabaseAction restore_cloud_database = 16;
+
+ // Action that gets a Cloud Spanner database.
+ GetCloudDatabaseAction get_cloud_database = 17;
+
+ // Action that creates a Cloud Spanner database backup.
+ CreateCloudBackupAction create_cloud_backup = 18;
+
+ // Action that copies a Cloud Spanner database backup.
+ CopyCloudBackupAction copy_cloud_backup = 19;
+
+ // Action that gets a Cloud Spanner database backup.
+ GetCloudBackupAction get_cloud_backup = 20;
+
+ // Action that updates a Cloud Spanner database backup.
+ UpdateCloudBackupAction update_cloud_backup = 21;
+
+ // Action that deletes a Cloud Spanner database backup.
+ DeleteCloudBackupAction delete_cloud_backup = 22;
+
+ // Action that lists Cloud Spanner database backups.
+ ListCloudBackupsAction list_cloud_backups = 23;
+
+ // Action that lists Cloud Spanner database backup operations.
+ ListCloudBackupOperationsAction list_cloud_backup_operations = 24;
+
+ // Action that gets an operation.
+ GetOperationAction get_operation = 25;
+
+ // Action that cancels an operation.
+ CancelOperationAction cancel_operation = 26;
+
+ // Action that changes quorum of a Cloud Spanner database.
+ ChangeQuorumCloudDatabaseAction change_quorum_cloud_database = 28;
+
+ // Action that adds splits to a Cloud Spanner database.
+ AddSplitPointsAction add_split_points = 29;
+ }
+}
+
+// Action that creates a user instance config.
+message CreateUserInstanceConfigAction {
+ // User instance config ID (not path), e.g. "custom-config".
+ string user_config_id = 1;
+
+ // Cloud project ID, e.g. "spanner-cloud-systest".
+ string project_id = 2;
+
+ // Base config ID, e.g. "test-config".
+ string base_config_id = 3;
+
+ // Replicas that should be included in the user config.
+ repeated google.spanner.admin.instance.v1.ReplicaInfo replicas = 4;
+}
+
+// Action that updates a user instance config.
+message UpdateUserInstanceConfigAction {
+ // User instance config ID (not path), e.g. "custom-config".
+ string user_config_id = 1;
+
+ // Cloud project ID, e.g. "spanner-cloud-systest".
+ string project_id = 2;
+
+ // The descriptive name for this instance config as it appears in UIs.
+ optional string display_name = 3;
+
+ // labels.
+ map labels = 4;
+}
+
+// Action that gets a user instance config.
+message GetCloudInstanceConfigAction {
+ // Instance config ID (not path), e.g. "custom-config".
+ string instance_config_id = 1;
+
+ // Cloud project ID, e.g. "spanner-cloud-systest".
+ string project_id = 2;
+}
+
+// Action that deletes a user instance configs.
+message DeleteUserInstanceConfigAction {
+ // User instance config ID (not path), e.g. "custom-config".
+ string user_config_id = 1;
+
+ // Cloud project ID, e.g. "spanner-cloud-systest".
+ string project_id = 2;
+}
+
+// Action that lists user instance configs.
+message ListCloudInstanceConfigsAction {
+ // Cloud project ID, e.g. "spanner-cloud-systest".
+ string project_id = 1;
+
+ // Number of instance configs to be returned in the response. If 0 or
+ // less, defaults to the server's maximum allowed page size.
+ optional int32 page_size = 2;
+
+ // If non-empty, "page_token" should contain a next_page_token
+ // from a previous ListInstanceConfigsResponse to the same "parent".
+ optional string page_token = 3;
+}
+
+// Action that creates a Cloud Spanner instance.
+message CreateCloudInstanceAction {
+ // Cloud instance ID (not path), e.g. "test-instance".
+ string instance_id = 1;
+
+ // Cloud project ID, e.g. "spanner-cloud-systest".
+ string project_id = 2;
+
+ // Instance config ID, e.g. "test-config".
+ string instance_config_id = 3;
+
+ // Number of nodes (processing_units should not be set or set to 0 if used).
+ optional int32 node_count = 4;
+
+ // Number of processing units (node_count should be set to 0 if used).
+ optional int32 processing_units = 6;
+
+ // The autoscaling config for this instance. If non-empty, an autoscaling
+ // instance will be created (processing_units and node_count should be set to
+ // 0 if used).
+ optional google.spanner.admin.instance.v1.AutoscalingConfig
+ autoscaling_config = 7;
+
+ // labels.
+ map labels = 5;
+
+ // The edition of the instance.
+ google.spanner.admin.instance.v1.Instance.Edition edition = 8;
+}
+
+// Action that updates a Cloud Spanner instance.
+message UpdateCloudInstanceAction {
+ // Cloud instance ID (not path), e.g. "test-instance".
+ string instance_id = 1;
+
+ // Cloud project ID, e.g. "spanner-cloud-systest".
+ string project_id = 2;
+
+ // The descriptive name for this instance as it appears in UIs.
+ // Must be unique per project and between 4 and 30 characters in length.
+ optional string display_name = 3;
+
+ // The number of nodes allocated to this instance. At most one of either
+ // node_count or processing_units should be present in the message.
+ optional int32 node_count = 4;
+
+ // The number of processing units allocated to this instance. At most one of
+ // processing_units or node_count should be present in the message.
+ optional int32 processing_units = 5;
+
+ // The autoscaling config for this instance. If non-empty, this instance is
+ // using autoscaling (processing_units and node_count should be set to
+ // 0 if used).
+ optional google.spanner.admin.instance.v1.AutoscalingConfig
+ autoscaling_config = 7;
+
+ // labels.
+ map labels = 6;
+
+ // The edition of the instance.
+ google.spanner.admin.instance.v1.Instance.Edition edition = 8;
+}
+
+// Action that deletes a Cloud Spanner instance.
+message DeleteCloudInstanceAction {
+ // Cloud instance ID (not path), e.g. "test-instance".
+ string instance_id = 1;
+
+ // Cloud project ID, e.g. "spanner-cloud-systest".
+ string project_id = 2;
+}
+
+// Action that creates a Cloud Spanner database.
+message CreateCloudDatabaseAction {
+ // Cloud instance ID (not path), e.g. "test-instance".
+ string instance_id = 1;
+
+ // Cloud project ID, e.g. "spanner-cloud-systest".
+ string project_id = 2;
+
+ // Cloud database ID (not full path), e.g. "db0".
+ string database_id = 3;
+
+ // SDL statements to apply to the new database.
+ repeated string sdl_statement = 4;
+
+ // The KMS key used to encrypt the database to be created if the database
+ // should be CMEK protected.
+ google.spanner.admin.database.v1.EncryptionConfig encryption_config = 5;
+
+ // Optional SQL dialect (GOOGLESQL or POSTGRESQL). Default: GOOGLESQL.
+ optional string dialect = 6;
+
+ optional bytes proto_descriptors = 7;
+}
+
+// Action that updates the schema of a Cloud Spanner database.
+message UpdateCloudDatabaseDdlAction {
+ // Cloud instance ID (not path), e.g. "test-instance".
+ string instance_id = 1;
+
+ // Cloud project ID, e.g. "spanner-cloud-systest".
+ string project_id = 2;
+
+ // Cloud database ID (not full path), e.g. "db0".
+ string database_id = 3;
+
+ // SDL statements to apply to the database.
+ repeated string sdl_statement = 4;
+
+ // Op ID can be used to track progress of the update. If set, it must be
+ // unique per database. If not set, Cloud Spanner will generate operation ID
+ // automatically.
+ string operation_id = 5;
+
+ optional bytes proto_descriptors = 6;
+}
+
+// Action that updates a Cloud Spanner database.
+message UpdateCloudDatabaseAction {
+ // Cloud instance ID (not path), e.g. "test-instance".
+ string instance_id = 1;
+
+ // Cloud project ID, e.g. "spanner-cloud-systest".
+ string project_id = 2;
+
+ // Cloud database name (not full path), e.g. "db0".
+ string database_name = 3;
+
+ // Updated value of enable_drop_protection, this is the only field that has
+ // supported to be updated.
+ bool enable_drop_protection = 4;
+}
+
+// Action that drops a Cloud Spanner database.
+message DropCloudDatabaseAction {
+ // Cloud instance ID (not path), e.g. "test-instance".
+ string instance_id = 1;
+
+ // Cloud project ID, e.g. "spanner-cloud-systest".
+ string project_id = 2;
+
+ // Cloud database ID (not full path), e.g. "db0".
+ string database_id = 3;
+}
+
+// Action that changes quorum of a Cloud Spanner database.
+message ChangeQuorumCloudDatabaseAction {
+ // The fully qualified uri of the database whose quorum has to be changed.
+ optional string database_uri = 1;
+
+ // The locations of the serving regions, e.g. "asia-south1".
+ repeated string serving_locations = 2;
+}
+
+// A single Adapt message request.
+message AdaptMessageAction {
+ // The fully qualified uri of the database to send AdaptMessage to.
+ string database_uri = 1;
+
+ // The protocol to use for the request.
+ string protocol = 2;
+
+ // The payload of the request.
+ bytes payload = 3;
+
+ // Attachments to be sent with the request.
+ map attachments = 4;
+
+ // The query to be sent with the request.
+ string query = 5;
+
+ // If true, the action will send a Prepare request first and then an
+ // Execute request right after to execute the query. This is only supported
+ // for Cloud Client path.
+ bool prepare_then_execute = 6;
+}
+
+// Action that lists Cloud Spanner databases.
+message ListCloudDatabasesAction {
+ // Cloud project ID, e.g. "spanner-cloud-systest".
+ string project_id = 1;
+
+ // Cloud instance ID (not path) to list databases from, e.g. "test-instance".
+ string instance_id = 2;
+
+ // 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
+ // from a previous ListDatabasesResponse to the same "parent"
+ // and with the same "filter".
+ string page_token = 4;
+}
+
+// Action that lists Cloud Spanner instances.
+message ListCloudInstancesAction {
+ // Cloud project ID, e.g. "spanner-cloud-systest".
+ string project_id = 1;
+
+ // A filter expression that filters what operations are returned in the
+ // response.
+ // The expression must specify the field name, a comparison operator,
+ // and the value that you want to use for filtering.
+ // Refer spanner_instance_admin.proto.ListInstancesRequest for
+ // detail.
+ optional string filter = 2;
+
+ // Number of instances to be returned in the response. If 0 or
+ // less, defaults to the server's maximum allowed page size.
+ optional int32 page_size = 3;
+
+ // If non-empty, "page_token" should contain a next_page_token
+ // from a previous ListInstancesResponse to the same "parent"
+ // and with the same "filter".
+ optional string page_token = 4;
+}
+
+// Action that retrieves a Cloud Spanner instance.
+message GetCloudInstanceAction {
+ // Cloud project ID, e.g. "spanner-cloud-systest".
+ string project_id = 1;
+
+ // Cloud instance ID (not path) to retrieve the instance from,
+ // e.g. "test-instance".
+ string instance_id = 2;
+}
+
+// Action that lists Cloud Spanner database operations.
+message ListCloudDatabaseOperationsAction {
+ // Cloud project ID, e.g. "spanner-cloud-systest".
+ string project_id = 1;
+
+ // Cloud instance ID (not path) to list database operations from,
+ // e.g. "test-instance".
+ string instance_id = 2;
+
+ // A filter expression that filters what operations are returned in the
+ // response.
+ // The expression must specify the field name, a comparison operator,
+ // and the value that you want to use for filtering.
+ // Refer spanner_database_admin.proto.ListDatabaseOperationsRequest for
+ // detail.
+ string filter = 3;
+
+ // 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 = 4;
+
+ // If non-empty, "page_token" should contain a next_page_token
+ // from a previous ListDatabaseOperationsResponse to the same "parent"
+ // and with the same "filter".
+ string page_token = 5;
+}
+
+// Action that restores a Cloud Spanner database from a backup.
+message RestoreCloudDatabaseAction {
+ // Cloud project ID, e.g. "spanner-cloud-systest".
+ string project_id = 1;
+
+ // Cloud instance ID (not path) containing the backup, e.g. "backup-instance".
+ string backup_instance_id = 2;
+
+ // The id of the backup from which to restore, e.g. "test-backup".
+ string backup_id = 3;
+
+ // Cloud instance ID (not path) containing the database, e.g.
+ // "database-instance".
+ string database_instance_id = 4;
+
+ // The id of the database to create and restore to, e.g. "db0". Note that this
+ // database must not already exist.
+ string database_id = 5;
+
+ // The KMS key(s) used to encrypt the restored database to be created if the
+ // restored database should be CMEK protected.
+ google.spanner.admin.database.v1.EncryptionConfig encryption_config = 7;
+}
+
+// Action that gets a Cloud Spanner database.
+message GetCloudDatabaseAction {
+ // Cloud project ID, e.g. "spanner-cloud-systest".
+ string project_id = 1;
+
+ // Cloud instance ID (not path), e.g. "test-instance".
+ string instance_id = 2;
+
+ // The id of the database to get, e.g. "db0".
+ string database_id = 3;
+}
+
+// Action that creates a Cloud Spanner database backup.
+message CreateCloudBackupAction {
+ // Cloud project ID, e.g. "spanner-cloud-systest".
+ string project_id = 1;
+
+ // Cloud instance ID (not path), e.g. "test-instance".
+ string instance_id = 2;
+
+ // The id of the backup to be created, e.g. "test-backup".
+ string backup_id = 3;
+
+ // The id of the database from which this backup was
+ // created, e.g. "db0". Note that this needs to be in the
+ // same instance as the backup.
+ string database_id = 4;
+
+ // Output only. The expiration time of the backup, which must be at least 6
+ // hours and at most 366 days from the time the request is received.
+ google.protobuf.Timestamp expire_time = 5
+ [(google.api.field_behavior) = OUTPUT_ONLY];
+
+ // The version time of the backup, which must be within the time range of
+ // [earliest_version_time, NOW], where earliest_version_time is retrieved by
+ // cloud spanner frontend API (See details: go/cs-pitr-lite-design).
+ optional google.protobuf.Timestamp version_time = 6;
+
+ // The KMS key(s) used to encrypt the backup to be created if the backup
+ // should be CMEK protected.
+ google.spanner.admin.database.v1.EncryptionConfig encryption_config = 7;
+}
+
+// Action that copies a Cloud Spanner database backup.
+message CopyCloudBackupAction {
+ // Cloud project ID, e.g. "spanner-cloud-systest".
+ string project_id = 1;
+
+ // Cloud instance ID (not path), e.g. "test-instance".
+ string instance_id = 2;
+
+ // The id of the backup to be created, e.g. "test-backup".
+ string backup_id = 3;
+
+ // The fully qualified uri of the source backup from which this
+ // backup was copied. eg.
+ // "projects//instances//backups/".
+ string source_backup = 4;
+
+ // Output only. The expiration time of the backup, which must be at least 6
+ // hours and at most 366 days from the time the request is received.
+ google.protobuf.Timestamp expire_time = 5
+ [(google.api.field_behavior) = OUTPUT_ONLY];
+}
+
+// Action that gets a Cloud Spanner database backup.
+message GetCloudBackupAction {
+ // Cloud project ID, e.g. "spanner-cloud-systest".
+ string project_id = 1;
+
+ // Cloud instance ID (not path), e.g. "test-instance".
+ string instance_id = 2;
+
+ // The id of the backup to get, e.g. "test-backup".
+ string backup_id = 3;
+}
+
+// Action that updates a Cloud Spanner database backup.
+message UpdateCloudBackupAction {
+ // Cloud project ID, e.g. "spanner-cloud-systest".
+ string project_id = 1;
+
+ // Cloud instance ID (not path), e.g. "test-instance".
+ string instance_id = 2;
+
+ // The id of the backup to update, e.g. "test-backup".
+ string backup_id = 3;
+
+ // Output only. Updated value of expire_time, this is the only field
+ // that supported to be updated.
+ google.protobuf.Timestamp expire_time = 4
+ [(google.api.field_behavior) = OUTPUT_ONLY];
+}
+
+// Action that deletes a Cloud Spanner database backup.
+message DeleteCloudBackupAction {
+ // Cloud project ID, e.g. "spanner-cloud-systest".
+ string project_id = 1;
+
+ // Cloud instance ID (not path), e.g. "test-instance".
+ string instance_id = 2;
+
+ // The id of the backup to delete, e.g. "test-backup".
+ string backup_id = 3;
+}
+
+// Action that lists Cloud Spanner database backups.
+message ListCloudBackupsAction {
+ // Cloud project ID, e.g. "spanner-cloud-systest".
+ string project_id = 1;
+
+ // Cloud instance ID (not path) to list backups from, e.g. "test-instance".
+ string instance_id = 2;
+
+ // A filter expression that filters backups listed in the response.
+ // The expression must specify the field name, a comparison operator,
+ // and the value that you want to use for filtering.
+ // Refer backup.proto.ListBackupsRequest for detail.
+ string filter = 3;
+
+ // 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 = 4;
+
+ // If non-empty, "page_token" should contain a next_page_token
+ // from a previous ListBackupsResponse to the same "parent"
+ // and with the same "filter".
+ string page_token = 5;
+}
+
+// Action that lists Cloud Spanner database backup operations.
+message ListCloudBackupOperationsAction {
+ // Cloud project ID, e.g. "spanner-cloud-systest".
+ string project_id = 1;
+
+ // Cloud instance ID (not path) to list backup operations from,
+ // e.g. "test-instance".
+ string instance_id = 2;
+
+ // A filter expression that filters what operations are returned in the
+ // response.
+ // The expression must specify the field name, a comparison operator,
+ // and the value that you want to use for filtering.
+ // Refer backup.proto.ListBackupOperationsRequest for detail.
+ string filter = 3;
+
+ // 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 = 4;
+
+ // If non-empty, "page_token" should contain a next_page_token
+ // from a previous ListBackupOperationsResponse to the same "parent"
+ // and with the same "filter".
+ string page_token = 5;
+}
+
+// Action that gets an operation.
+message GetOperationAction {
+ // The name of the operation resource.
+ string operation = 1;
+}
+
+// Query cancellation action defines the long running query and the cancel query
+// format depening on the Cloud database dialect.
+message QueryCancellationAction {
+ // Long running query.
+ string long_running_sql = 1;
+
+ // Format of the cancel query for the cloud database dialect.
+ string cancel_query = 2;
+}
+
+// Action that cancels an operation.
+message CancelOperationAction {
+ // The name of the operation resource to be cancelled.
+ string operation = 1;
+}
+
+// Action that adds a split point to a Cloud Spanner database.
+message AddSplitPointsAction {
+ // Cloud project ID, e.g. "spanner-cloud-systest".
+ string project_id = 1;
+
+ // Cloud instance ID (not path), e.g. "test-instance".
+ string instance_id = 2;
+
+ // Cloud database ID (not full path), e.g. "db0".
+ string database_id = 3;
+
+ // The split points to add.
+ repeated google.spanner.admin.database.v1.SplitPoints split_points = 4;
+}
+
+// Starts a batch read-only transaction in executor. Successful outcomes of this
+// action will contain batch_txn_id--the identificator that can be used to start
+// the same transaction in other Executors to parallelize partition processing.
+//
+// Example of a batch read flow:
+// 1. Start batch transaction with a timestamp (StartBatchTransactionAction)
+// 2. Generate database partitions for a read or query
+// (GenerateDbPartitionsForReadAction/GenerateDbPartitionsForQueryAction)
+// 3. Call ExecutePartitionAction for some or all partitions, process rows
+// 4. Clean up the transaction (CloseBatchTransactionAction).
+//
+// More sophisticated example, with parallel processing:
+// 1. Start batch transaction with a timestamp (StartBatchTransactionAction),
+// note the returned BatchTransactionId
+// 2. Generate database partitions for a read or query
+// (GenerateDbPartitionsForReadAction/GenerateDbPartitionsForQueryAction)
+// 3. Distribute the partitions over a pool of workers, along with the
+// transaction ID.
+//
+// In each worker:
+// 4-1. StartBatchTransactionAction with the given transaction ID
+// 4-2. ExecutePartitionAction for each partition it got, process read results
+// 4-3. Close (not cleanup) the transaction (CloseBatchTransactionAction).
+//
+// When all workers are done:
+// 5. Cleanup the transaction (CloseBatchTransactionAction). This can be done
+// either by the last worker to finish the job, or by the main Executor that
+// initialized this transaction in the first place. It is also possible to clean
+// it up with a brand new Executor -- just execute StartBatchTransactionAction
+// with the ID, then clean it up right away.
+//
+// Cleaning up is optional, but recommended.
+message StartBatchTransactionAction {
+ // To start a new transaction, specify an exact timestamp. Alternatively, an
+ // existing batch transaction ID can be used. Either one of two must be
+ // set.
+ oneof param {
+ // The exact timestamp to start the batch transaction.
+ google.protobuf.Timestamp batch_txn_time = 1;
+
+ // ID of a batch read-only transaction. It can be used to start the same
+ // batch transaction on multiple executors and parallelize partition
+ // processing.
+ bytes tid = 2;
+ }
+
+ // Database role to assume while performing this action. Setting the
+ // database_role will enforce additional role-based access checks on this
+ // action.
+ string cloud_database_role = 3;
+}
+
+// Closes or cleans up the currently opened batch read-only transaction.
+//
+// Once a transaction is closed, the Executor can be disposed of or used to
+// start start another transaction. Closing a batch transaction in one Executor
+// doesn't affect the transaction's state in other Executors that also read from
+// it.
+//
+// When a transaction is cleaned up, it becomes globally invalid. Cleaning up is
+// optional, but recommended.
+message CloseBatchTransactionAction {
+ // Indicates whether the transaction needs to be cleaned up.
+ bool cleanup = 1;
+}
+
+// Generate database partitions for the given read. Successful outcomes will
+// contain database partitions in the db_partition field.
+message GenerateDbPartitionsForReadAction {
+ // Read to generate partitions for.
+ ReadAction read = 1;
+
+ // Metadata related to the tables involved in the read.
+ repeated TableMetadata table = 2;
+
+ // Desired size of data in each partition. Spanner doesn't guarantee to
+ // respect this value.
+ optional int64 desired_bytes_per_partition = 3;
+
+ // If set, the desired max number of partitions. Spanner doesn't guarantee to
+ // respect this value.
+ optional int64 max_partition_count = 4;
+}
+
+// Generate database partitions for the given query. Successful outcomes will
+// contain database partitions in the db_partition field.
+message GenerateDbPartitionsForQueryAction {
+ // Query to generate partitions for.
+ QueryAction query = 1;
+
+ // Desired size of data in each partition. Spanner doesn't guarantee to
+ // respect this value.
+ optional int64 desired_bytes_per_partition = 2;
+}
+
+// Identifies a database partition generated for a particular read or query. To
+// read rows from the partition, use ExecutePartitionAction.
+message BatchPartition {
+ // Serialized Partition instance.
+ bytes partition = 1;
+
+ // The partition token decrypted from partition.
+ bytes partition_token = 2;
+
+ // Table name is set iff the partition was generated for a read (as opposed to
+ // a query).
+ optional string table = 3;
+
+ // Index name if the partition was generated for an index read.
+ optional string index = 4;
+}
+
+// Performs a read or query for the given partitions. This action must be
+// executed in the context of the same transaction that was used to generate
+// given partitions.
+message ExecutePartitionAction {
+ // Batch partition to execute on.
+ BatchPartition partition = 1;
+}
+
+// Execute a change stream TVF query.
+message ExecuteChangeStreamQuery {
+ // Name for this change stream.
+ string name = 1;
+
+ // Specifies that records with commit_timestamp greater than or equal to
+ // start_time should be returned.
+ google.protobuf.Timestamp start_time = 2;
+
+ // Specifies that records with commit_timestamp less than or equal to
+ // end_time should be returned.
+ optional google.protobuf.Timestamp end_time = 3;
+
+ // Specifies which change stream partition to query, based on the content of
+ // child partitions records.
+ optional string partition_token = 4;
+
+ // Read options for this change stream query.
+ repeated string read_options = 5;
+
+ // Determines how frequently a heartbeat ChangeRecord will be returned in case
+ // there are no transactions committed in this partition, in milliseconds.
+ optional int32 heartbeat_milliseconds = 6;
+
+ // Deadline for this change stream query, in seconds.
+ optional int64 deadline_seconds = 7;
+
+ // Database role to assume while performing this action. This should only be
+ // set for cloud requests. Setting the database role will enforce additional
+ // role-based access checks on this action.
+ optional string cloud_database_role = 8;
+}
+
+// SpannerActionOutcome defines a result of execution of a single SpannerAction.
+message SpannerActionOutcome {
+ // If an outcome is split into multiple parts, status will be set only in the
+ // last part.
+ optional google.rpc.Status status = 1;
+
+ // Transaction timestamp. It must be set for successful committed actions.
+ optional google.protobuf.Timestamp commit_time = 2;
+
+ // Result of a ReadAction. This field must be set for ReadActions even if
+ // no rows were read.
+ optional ReadResult read_result = 3;
+
+ // Result of a Query. This field must be set for Queries even if no rows were
+ // read.
+ optional QueryResult query_result = 4;
+
+ // This bit indicates that Spanner has restarted the current transaction. It
+ // means that the client should replay all the reads and writes.
+ // Setting it to true is only valid in the context of a read-write
+ // transaction, as an outcome of a committing FinishTransactionAction.
+ optional bool transaction_restarted = 5;
+
+ // In successful StartBatchTransactionAction outcomes, this contains the ID of
+ // the transaction.
+ optional bytes batch_txn_id = 6;
+
+ // Generated database partitions (result of a
+ // GenetageDbPartitionsForReadAction/GenerateDbPartitionsForQueryAction).
+ repeated BatchPartition db_partition = 7;
+
+ // Result of admin related actions.
+ optional AdminResult admin_result = 8;
+
+ // Stores rows modified by query in single DML or batch DML action.
+ // In case of batch DML action, stores 0 as row count of errored DML query.
+ repeated int64 dml_rows_modified = 9;
+
+ // Change stream records returned by a change stream query.
+ repeated ChangeStreamRecord change_stream_records = 10;
+
+ // If not zero, it indicates the read timestamp to use for validating
+ // the SnapshotIsolation transaction.
+ optional int64 snapshot_isolation_txn_read_timestamp = 11;
+}
+
+// AdminResult contains admin action results, for database/backup/operation.
+message AdminResult {
+ // Results of cloud backup related actions.
+ CloudBackupResponse backup_response = 1;
+
+ // Results of operation related actions.
+ OperationResponse operation_response = 2;
+
+ // Results of database related actions.
+ CloudDatabaseResponse database_response = 3;
+
+ // Results of instance related actions.
+ CloudInstanceResponse instance_response = 4;
+
+ // Results of instance config related actions.
+ CloudInstanceConfigResponse instance_config_response = 5;
+}
+
+// CloudBackupResponse contains results returned by cloud backup related
+// actions.
+message CloudBackupResponse {
+ // List of backups returned by ListCloudBackupsAction.
+ repeated google.spanner.admin.database.v1.Backup listed_backups = 1;
+
+ // List of operations returned by ListCloudBackupOperationsAction.
+ repeated google.longrunning.Operation listed_backup_operations = 2;
+
+ // "next_page_token" can be sent in a subsequent list action
+ // to fetch more of the matching data.
+ string next_page_token = 3;
+
+ // Backup returned by GetCloudBackupAction/UpdateCloudBackupAction.
+ google.spanner.admin.database.v1.Backup backup = 4;
+}
+
+// OperationResponse contains results returned by operation related actions.
+message OperationResponse {
+ // List of operations returned by ListOperationsAction.
+ repeated google.longrunning.Operation listed_operations = 1;
+
+ // "next_page_token" can be sent in a subsequent list action
+ // to fetch more of the matching data.
+ string next_page_token = 2;
+
+ // Operation returned by GetOperationAction.
+ google.longrunning.Operation operation = 3;
+}
+
+// CloudInstanceResponse contains results returned by cloud instance related
+// actions.
+message CloudInstanceResponse {
+ // List of instances returned by ListCloudInstancesAction.
+ repeated google.spanner.admin.instance.v1.Instance listed_instances = 1;
+
+ // "next_page_token" can be sent in a subsequent list action
+ // to fetch more of the matching data.
+ string next_page_token = 2;
+
+ // Instance returned by GetCloudInstanceAction
+ google.spanner.admin.instance.v1.Instance instance = 3;
+}
+
+// CloudInstanceConfigResponse contains results returned by cloud instance
+// config related actions.
+message CloudInstanceConfigResponse {
+ // List of instance configs returned by ListCloudInstanceConfigsAction.
+ repeated google.spanner.admin.instance.v1.InstanceConfig
+ listed_instance_configs = 1;
+
+ // "next_page_token" can be sent in a subsequent list action
+ // to fetch more of the matching data.
+ string next_page_token = 2;
+
+ // Instance config returned by GetCloudInstanceConfigAction.
+ google.spanner.admin.instance.v1.InstanceConfig instance_config = 3;
+}
+
+// CloudDatabaseResponse contains results returned by cloud database related
+// actions.
+message CloudDatabaseResponse {
+ // List of databases returned by ListCloudDatabasesAction.
+ repeated google.spanner.admin.database.v1.Database listed_databases = 1;
+
+ // List of operations returned by ListCloudDatabaseOperationsAction.
+ repeated google.longrunning.Operation listed_database_operations = 2;
+
+ // "next_page_token" can be sent in a subsequent list action
+ // to fetch more of the matching data.
+ string next_page_token = 3;
+
+ // Database returned by GetCloudDatabaseAction
+ google.spanner.admin.database.v1.Database database = 4;
+}
+
+// ReadResult contains rows read.
+message ReadResult {
+ // Table name.
+ string table = 1;
+
+ // Index name, if read from an index.
+ optional string index = 2;
+
+ // Request index (multiread only).
+ optional int32 request_index = 3;
+
+ // Rows read. Each row is a struct with multiple fields, one for each column
+ // in read result. All rows have the same type.
+ repeated ValueList row = 4;
+
+ // The type of rows read. It must be set if at least one row was read.
+ optional google.spanner.v1.StructType row_type = 5;
+}
+
+// QueryResult contains result of a Query.
+message QueryResult {
+ // Rows read. Each row is a struct with multiple fields, one for each column
+ // in read result. All rows have the same type.
+ repeated ValueList row = 1;
+
+ // The type of rows read. It must be set if at least one row was read.
+ optional google.spanner.v1.StructType row_type = 2;
+}
+
+// Raw ChangeStream records.
+// Encodes one of: DataChangeRecord, HeartbeatRecord, ChildPartitionsRecord
+// returned from the ChangeStream API.
+message ChangeStreamRecord {
+ // Record represents one type of the change stream record.
+ oneof record {
+ // Data change record.
+ DataChangeRecord data_change = 1;
+
+ // Child partitions record.
+ ChildPartitionsRecord child_partition = 2;
+
+ // Heartbeat record.
+ HeartbeatRecord heartbeat = 3;
+ }
+}
+
+// ChangeStream data change record.
+message DataChangeRecord {
+ // Column types.
+ message ColumnType {
+ // Column name.
+ string name = 1;
+
+ // Column type in JSON.
+ string type = 2;
+
+ // Whether the column is a primary key column.
+ bool is_primary_key = 3;
+
+ // The position of the column as defined in the schema.
+ int64 ordinal_position = 4;
+ }
+
+ // Describes the changes that were made.
+ message Mod {
+ // The primary key values in JSON.
+ string keys = 1;
+
+ // The new values of the changed columns in JSON. Only contain the non-key
+ // columns.
+ string new_values = 2;
+
+ // The old values of the changed columns in JSON. Only contain the non-key
+ // columns.
+ string old_values = 3;
+ }
+
+ // The timestamp in which the change was committed.
+ google.protobuf.Timestamp commit_time = 1;
+
+ // The sequence number for the record within the transaction.
+ string record_sequence = 2;
+
+ // A globally unique string that represents the transaction in which the
+ // change was committed.
+ string transaction_id = 3;
+
+ // Indicates whether this is the last record for a transaction in the current
+ // partition.
+ bool is_last_record = 4;
+
+ // Name of the table affected by the change.
+ string table = 5;
+
+ // Column types defined in the schema.
+ repeated ColumnType column_types = 6;
+
+ // Changes made in the transaction.
+ repeated Mod mods = 7;
+
+ // Describes the type of change. One of INSERT, UPDATE or DELETE.
+ string mod_type = 8;
+
+ // One of value capture type: NEW_VALUES, OLD_VALUES, OLD_AND_NEW_VALUES.
+ string value_capture_type = 9;
+
+ // Number of records in transactions.
+ int64 record_count = 10;
+
+ // Number of partitions in transactions.
+ int64 partition_count = 11;
+
+ // Transaction tag info.
+ string transaction_tag = 12;
+
+ // Whether the transaction is a system transactionn.
+ bool is_system_transaction = 13;
+}
+
+// ChangeStream child partition record.
+message ChildPartitionsRecord {
+ // A single child partition.
+ message ChildPartition {
+ // Partition token string used to identify the child partition in queries.
+ string token = 1;
+
+ // Parent partition tokens of this child partition.
+ repeated string parent_partition_tokens = 2;
+ }
+
+ // Data change records returned from child partitions in this child partitions
+ // record will have a commit timestamp greater than or equal to start_time.
+ google.protobuf.Timestamp start_time = 1;
+
+ // A monotonically increasing sequence number that can be used to define the
+ // ordering of the child partitions record when there are multiple child
+ // partitions records returned with the same start_time in a particular
+ // partition.
+ string record_sequence = 2;
+
+ // A set of child partitions and their associated information.
+ repeated ChildPartition child_partitions = 3;
+}
+
+// ChangeStream heartbeat record.
+message HeartbeatRecord {
+ // Timestamp for this heartbeat check.
+ google.protobuf.Timestamp heartbeat_time = 1;
+}
+
+// Options for Cloud Spanner Service.
+message SpannerOptions {
+ // Options for configuring the session pool
+ SessionPoolOptions session_pool_options = 1;
+}
+
+// Options for the session pool used by the DatabaseClient.
+message SessionPoolOptions {
+ // passing this as true, will make applicable RPCs use multiplexed sessions
+ // instead of regular sessions
+ bool use_multiplexed = 1;
+}
diff --git a/packages/google-cloud-spanner-api/protos/google/spanner/v1/change_stream.proto b/packages/google-cloud-spanner-api/protos/google/spanner/v1/change_stream.proto
new file mode 100644
index 000000000000..e7d12e6084c6
--- /dev/null
+++ b/packages/google-cloud-spanner-api/protos/google/spanner/v1/change_stream.proto
@@ -0,0 +1,451 @@
+// Copyright 2026 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/protobuf/timestamp.proto";
+import "google/spanner/v1/type.proto";
+
+option csharp_namespace = "Google.Cloud.Spanner.V1";
+option go_package = "cloud.google.com/go/spanner/apiv1/spannerpb;spannerpb";
+option java_multiple_files = true;
+option java_outer_classname = "ChangeStreamProto";
+option java_package = "com.google.spanner.v1";
+option php_namespace = "Google\\Cloud\\Spanner\\V1";
+option ruby_package = "Google::Cloud::Spanner::V1";
+
+// Spanner Change Streams enable customers to capture and stream out changes to
+// their Spanner databases in real-time. A change stream
+// can be created with option partition_mode='IMMUTABLE_KEY_RANGE' or
+// partition_mode='MUTABLE_KEY_RANGE'.
+//
+// This message is only used in Change Streams created with the option
+// partition_mode='MUTABLE_KEY_RANGE'. Spanner automatically creates a special
+// Table-Valued Function (TVF) along with each Change Streams. The function
+// provides access to the change stream's records. The function is named
+// READ_ (where is the
+// name of the change stream), and it returns a table with only one column
+// called ChangeRecord.
+message ChangeStreamRecord {
+ // A data change record contains a set of changes to a table with the same
+ // modification type (insert, update, or delete) committed at the same commit
+ // timestamp in one change stream partition for the same transaction. Multiple
+ // data change records can be returned for the same transaction across
+ // multiple change stream partitions.
+ message DataChangeRecord {
+ // Metadata for a column.
+ message ColumnMetadata {
+ // Name of the column.
+ string name = 1;
+
+ // Type of the column.
+ Type type = 2;
+
+ // Indicates whether the column is a primary key column.
+ bool is_primary_key = 3;
+
+ // Ordinal position of the column based on the original table definition
+ // in the schema starting with a value of 1.
+ int64 ordinal_position = 4;
+ }
+
+ // Returns the value and associated metadata for a particular field of the
+ // [Mod][google.spanner.v1.ChangeStreamRecord.DataChangeRecord.Mod].
+ message ModValue {
+ // Index within the repeated
+ // [column_metadata][google.spanner.v1.ChangeStreamRecord.DataChangeRecord.column_metadata]
+ // field, to obtain the column metadata for the column that was modified.
+ int32 column_metadata_index = 1;
+
+ // The value of the column.
+ google.protobuf.Value value = 2;
+ }
+
+ // A mod describes all data changes in a watched table row.
+ message Mod {
+ // Returns the value of the primary key of the modified row.
+ repeated ModValue keys = 1;
+
+ // Returns the old values before the change for the modified columns.
+ // Always empty for
+ // [INSERT][google.spanner.v1.ChangeStreamRecord.DataChangeRecord.ModType.INSERT],
+ // or if old values are not being captured specified by
+ // [value_capture_type][google.spanner.v1.ChangeStreamRecord.DataChangeRecord.ValueCaptureType].
+ repeated ModValue old_values = 2;
+
+ // Returns the new values after the change for the modified columns.
+ // Always empty for
+ // [DELETE][google.spanner.v1.ChangeStreamRecord.DataChangeRecord.ModType.DELETE].
+ repeated ModValue new_values = 3;
+ }
+
+ // Mod type describes the type of change Spanner applied to the data. For
+ // example, if the client submits an INSERT_OR_UPDATE request, Spanner will
+ // perform an insert if there is no existing row and return ModType INSERT.
+ // Alternatively, if there is an existing row, Spanner will perform an
+ // update and return ModType UPDATE.
+ enum ModType {
+ // Not specified.
+ MOD_TYPE_UNSPECIFIED = 0;
+
+ // Indicates data was inserted.
+ INSERT = 10;
+
+ // Indicates existing data was updated.
+ UPDATE = 20;
+
+ // Indicates existing data was deleted.
+ DELETE = 30;
+ }
+
+ // Value capture type describes which values are recorded in the data
+ // change record.
+ enum ValueCaptureType {
+ // Not specified.
+ VALUE_CAPTURE_TYPE_UNSPECIFIED = 0;
+
+ // Records both old and new values of the modified watched columns.
+ OLD_AND_NEW_VALUES = 10;
+
+ // Records only new values of the modified watched columns.
+ NEW_VALUES = 20;
+
+ // Records new values of all watched columns, including modified and
+ // unmodified columns.
+ NEW_ROW = 30;
+
+ // Records the new values of all watched columns, including modified and
+ // unmodified columns. Also records the old values of the modified
+ // columns.
+ NEW_ROW_AND_OLD_VALUES = 40;
+ }
+
+ // Indicates the timestamp in which the change was committed.
+ // DataChangeRecord.commit_timestamps,
+ // PartitionStartRecord.start_timestamps,
+ // PartitionEventRecord.commit_timestamps, and
+ // PartitionEndRecord.end_timestamps can have the same value in the same
+ // partition.
+ google.protobuf.Timestamp commit_timestamp = 1;
+
+ // Record sequence numbers are unique and monotonically increasing (but not
+ // necessarily contiguous) for a specific timestamp across record
+ // types in the same partition. To guarantee ordered processing, the reader
+ // should process records (of potentially different types) in
+ // record_sequence order for a specific timestamp in the same partition.
+ //
+ // The record sequence number ordering across partitions is only meaningful
+ // in the context of a specific transaction. Record sequence numbers are
+ // unique across partitions for a specific transaction. Sort the
+ // DataChangeRecords for the same
+ // [server_transaction_id][google.spanner.v1.ChangeStreamRecord.DataChangeRecord.server_transaction_id]
+ // by
+ // [record_sequence][google.spanner.v1.ChangeStreamRecord.DataChangeRecord.record_sequence]
+ // to reconstruct the ordering of the changes within the transaction.
+ string record_sequence = 2;
+
+ // Provides a globally unique string that represents the transaction in
+ // which the change was committed. Multiple transactions can have the same
+ // commit timestamp, but each transaction has a unique
+ // server_transaction_id.
+ string server_transaction_id = 3;
+
+ // Indicates whether this is the last record for a transaction in the
+ // current partition. Clients can use this field to determine when all
+ // records for a transaction in the current partition have been received.
+ bool is_last_record_in_transaction_in_partition = 4;
+
+ // Name of the table affected by the change.
+ string table = 5;
+
+ // Provides metadata describing the columns associated with the
+ // [mods][google.spanner.v1.ChangeStreamRecord.DataChangeRecord.mods] listed
+ // below.
+ repeated ColumnMetadata column_metadata = 6;
+
+ // Describes the changes that were made.
+ repeated Mod mods = 7;
+
+ // Describes the type of change.
+ ModType mod_type = 8;
+
+ // Describes the value capture type that was specified in the change stream
+ // configuration when this change was captured.
+ ValueCaptureType value_capture_type = 9;
+
+ // Indicates the number of data change records that are part of this
+ // transaction across all change stream partitions. This value can be used
+ // to assemble all the records associated with a particular transaction.
+ int32 number_of_records_in_transaction = 10;
+
+ // Indicates the number of partitions that return data change records for
+ // this transaction. This value can be helpful in assembling all records
+ // associated with a particular transaction.
+ int32 number_of_partitions_in_transaction = 11;
+
+ // Indicates the transaction tag associated with this transaction.
+ string transaction_tag = 12;
+
+ // Indicates whether the transaction is a system transaction. System
+ // transactions include those issued by time-to-live (TTL), column backfill,
+ // etc.
+ bool is_system_transaction = 13;
+ }
+
+ // A heartbeat record is returned as a progress indicator, when there are no
+ // data changes or any other partition record types in the change stream
+ // partition.
+ message HeartbeatRecord {
+ // Indicates the timestamp at which the query has returned all the records
+ // in the change stream partition with timestamp <= heartbeat timestamp.
+ // The heartbeat timestamp will not be the same as the timestamps of other
+ // record types in the same partition.
+ google.protobuf.Timestamp timestamp = 1;
+ }
+
+ // A partition start record serves as a notification that the client should
+ // schedule the partitions to be queried. PartitionStartRecord returns
+ // information about one or more partitions.
+ message PartitionStartRecord {
+ // Start timestamp at which the partitions should be queried to return
+ // change stream records with timestamps >= start_timestamp.
+ // DataChangeRecord.commit_timestamps,
+ // PartitionStartRecord.start_timestamps,
+ // PartitionEventRecord.commit_timestamps, and
+ // PartitionEndRecord.end_timestamps can have the same value in the same
+ // partition.
+ google.protobuf.Timestamp start_timestamp = 1;
+
+ // Record sequence numbers are unique and monotonically increasing (but not
+ // necessarily contiguous) for a specific timestamp across record
+ // types in the same partition. To guarantee ordered processing, the reader
+ // should process records (of potentially different types) in
+ // record_sequence order for a specific timestamp in the same partition.
+ string record_sequence = 2;
+
+ // Unique partition identifiers to be used in queries.
+ repeated string partition_tokens = 3;
+ }
+
+ // A partition end record serves as a notification that the client should stop
+ // reading the partition. No further records are expected to be retrieved on
+ // it.
+ message PartitionEndRecord {
+ // End timestamp at which the change stream partition is terminated. All
+ // changes generated by this partition will have timestamps <=
+ // end_timestamp. DataChangeRecord.commit_timestamps,
+ // PartitionStartRecord.start_timestamps,
+ // PartitionEventRecord.commit_timestamps, and
+ // PartitionEndRecord.end_timestamps can have the same value in the same
+ // partition. PartitionEndRecord is the last record returned for a
+ // partition.
+ google.protobuf.Timestamp end_timestamp = 1;
+
+ // Record sequence numbers are unique and monotonically increasing (but not
+ // necessarily contiguous) for a specific timestamp across record
+ // types in the same partition. To guarantee ordered processing, the reader
+ // should process records (of potentially different types) in
+ // record_sequence order for a specific timestamp in the same partition.
+ string record_sequence = 2;
+
+ // Unique partition identifier describing the terminated change stream
+ // partition.
+ // [partition_token][google.spanner.v1.ChangeStreamRecord.PartitionEndRecord.partition_token]
+ // is equal to the partition token of the change stream partition currently
+ // queried to return this PartitionEndRecord.
+ string partition_token = 3;
+ }
+
+ // A partition event record describes key range changes for a change stream
+ // partition. The changes to a row defined by its primary key can be captured
+ // in one change stream partition for a specific time range, and then be
+ // captured in a different change stream partition for a different time range.
+ // This movement of key ranges across change stream partitions is a reflection
+ // of activities, such as Spanner's dynamic splitting and load balancing, etc.
+ // Processing this event is needed if users want to guarantee processing of
+ // the changes for any key in timestamp order. If time ordered processing of
+ // changes for a primary key is not needed, this event can be ignored.
+ // To guarantee time ordered processing for each primary key, if the event
+ // describes move-ins, the reader of this partition needs to wait until the
+ // readers of the source partitions have processed all records with timestamps
+ // <= this PartitionEventRecord.commit_timestamp, before advancing beyond this
+ // PartitionEventRecord. If the event describes move-outs, the reader can
+ // notify the readers of the destination partitions that they can continue
+ // processing.
+ message PartitionEventRecord {
+ // Describes move-in of the key ranges into the change stream partition
+ // identified by
+ // [partition_token][google.spanner.v1.ChangeStreamRecord.PartitionEventRecord.partition_token].
+ //
+ // To maintain processing the changes for a particular key in timestamp
+ // order, the query processing the change stream partition identified by
+ // [partition_token][google.spanner.v1.ChangeStreamRecord.PartitionEventRecord.partition_token]
+ // should not advance beyond the partition event record commit timestamp
+ // until the queries processing the source change stream partitions have
+ // processed all change stream records with timestamps <= the partition
+ // event record commit timestamp.
+ message MoveInEvent {
+ // An unique partition identifier describing the source change stream
+ // partition that recorded changes for the key range that is moving
+ // into this partition.
+ string source_partition_token = 1;
+ }
+
+ // Describes move-out of the key ranges out of the change stream partition
+ // identified by
+ // [partition_token][google.spanner.v1.ChangeStreamRecord.PartitionEventRecord.partition_token].
+ //
+ // To maintain processing the changes for a particular key in timestamp
+ // order, the query processing the
+ // [MoveOutEvent][google.spanner.v1.ChangeStreamRecord.PartitionEventRecord.MoveOutEvent]
+ // in the partition identified by
+ // [partition_token][google.spanner.v1.ChangeStreamRecord.PartitionEventRecord.partition_token]
+ // should inform the queries processing the destination partitions that
+ // they can unblock and proceed processing records past the
+ // [commit_timestamp][google.spanner.v1.ChangeStreamRecord.PartitionEventRecord.commit_timestamp].
+ message MoveOutEvent {
+ // An unique partition identifier describing the destination change
+ // stream partition that will record changes for the key range that is
+ // moving out of this partition.
+ string destination_partition_token = 1;
+ }
+
+ // Indicates the commit timestamp at which the key range change occurred.
+ // DataChangeRecord.commit_timestamps,
+ // PartitionStartRecord.start_timestamps,
+ // PartitionEventRecord.commit_timestamps, and
+ // PartitionEndRecord.end_timestamps can have the same value in the same
+ // partition.
+ google.protobuf.Timestamp commit_timestamp = 1;
+
+ // Record sequence numbers are unique and monotonically increasing (but not
+ // necessarily contiguous) for a specific timestamp across record
+ // types in the same partition. To guarantee ordered processing, the reader
+ // should process records (of potentially different types) in
+ // record_sequence order for a specific timestamp in the same partition.
+ string record_sequence = 2;
+
+ // Unique partition identifier describing the partition this event
+ // occurred on.
+ // [partition_token][google.spanner.v1.ChangeStreamRecord.PartitionEventRecord.partition_token]
+ // is equal to the partition token of the change stream partition currently
+ // queried to return this PartitionEventRecord.
+ string partition_token = 3;
+
+ // Set when one or more key ranges are moved into the change stream
+ // partition identified by
+ // [partition_token][google.spanner.v1.ChangeStreamRecord.PartitionEventRecord.partition_token].
+ //
+ // Example: Two key ranges are moved into partition (P1) from partition (P2)
+ // and partition (P3) in a single transaction at timestamp T.
+ //
+ // The PartitionEventRecord returned in P1 will reflect the move as:
+ //
+ // PartitionEventRecord {
+ // commit_timestamp: T
+ // partition_token: "P1"
+ // move_in_events {
+ // source_partition_token: "P2"
+ // }
+ // move_in_events {
+ // source_partition_token: "P3"
+ // }
+ // }
+ //
+ // The PartitionEventRecord returned in P2 will reflect the move as:
+ //
+ // PartitionEventRecord {
+ // commit_timestamp: T
+ // partition_token: "P2"
+ // move_out_events {
+ // destination_partition_token: "P1"
+ // }
+ // }
+ //
+ // The PartitionEventRecord returned in P3 will reflect the move as:
+ //
+ // PartitionEventRecord {
+ // commit_timestamp: T
+ // partition_token: "P3"
+ // move_out_events {
+ // destination_partition_token: "P1"
+ // }
+ // }
+ repeated MoveInEvent move_in_events = 4;
+
+ // Set when one or more key ranges are moved out of the change stream
+ // partition identified by
+ // [partition_token][google.spanner.v1.ChangeStreamRecord.PartitionEventRecord.partition_token].
+ //
+ // Example: Two key ranges are moved out of partition (P1) to partition (P2)
+ // and partition (P3) in a single transaction at timestamp T.
+ //
+ // The PartitionEventRecord returned in P1 will reflect the move as:
+ //
+ // PartitionEventRecord {
+ // commit_timestamp: T
+ // partition_token: "P1"
+ // move_out_events {
+ // destination_partition_token: "P2"
+ // }
+ // move_out_events {
+ // destination_partition_token: "P3"
+ // }
+ // }
+ //
+ // The PartitionEventRecord returned in P2 will reflect the move as:
+ //
+ // PartitionEventRecord {
+ // commit_timestamp: T
+ // partition_token: "P2"
+ // move_in_events {
+ // source_partition_token: "P1"
+ // }
+ // }
+ //
+ // The PartitionEventRecord returned in P3 will reflect the move as:
+ //
+ // PartitionEventRecord {
+ // commit_timestamp: T
+ // partition_token: "P3"
+ // move_in_events {
+ // source_partition_token: "P1"
+ // }
+ // }
+ repeated MoveOutEvent move_out_events = 5;
+ }
+
+ // One of the change stream subrecords.
+ oneof record {
+ // Data change record describing a data change for a change stream
+ // partition.
+ DataChangeRecord data_change_record = 1;
+
+ // Heartbeat record describing a heartbeat for a change stream partition.
+ HeartbeatRecord heartbeat_record = 2;
+
+ // Partition start record describing a new change stream partition.
+ PartitionStartRecord partition_start_record = 3;
+
+ // Partition end record describing a terminated change stream partition.
+ PartitionEndRecord partition_end_record = 4;
+
+ // Partition event record describing key range changes for a change stream
+ // partition.
+ PartitionEventRecord partition_event_record = 5;
+ }
+}
diff --git a/packages/google-cloud-spanner-api/protos/google/spanner/v1/commit_response.proto b/packages/google-cloud-spanner-api/protos/google/spanner/v1/commit_response.proto
new file mode 100644
index 000000000000..d6593d0c78fb
--- /dev/null
+++ b/packages/google-cloud-spanner-api/protos/google/spanner/v1/commit_response.proto
@@ -0,0 +1,80 @@
+// Copyright 2026 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/protobuf/timestamp.proto";
+import "google/spanner/v1/location.proto";
+import "google/spanner/v1/transaction.proto";
+
+option csharp_namespace = "Google.Cloud.Spanner.V1";
+option go_package = "cloud.google.com/go/spanner/apiv1/spannerpb;spannerpb";
+option java_multiple_files = true;
+option java_outer_classname = "CommitResponseProto";
+option java_package = "com.google.spanner.v1";
+option php_namespace = "Google\\Cloud\\Spanner\\V1";
+option ruby_package = "Google::Cloud::Spanner::V1";
+
+// The response for [Commit][google.spanner.v1.Spanner.Commit].
+message CommitResponse {
+ // Additional statistics about a commit.
+ message CommitStats {
+ // The total number of mutations for the transaction. Knowing the
+ // `mutation_count` value can help you maximize the number of mutations
+ // in a transaction and minimize the number of API round trips. You can
+ // also monitor this value to prevent transactions from exceeding the system
+ // [limit](https://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](https://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;
+
+ // You must examine and retry the commit if the following is populated.
+ oneof MultiplexedSessionRetry {
+ // If specified, transaction has not committed yet.
+ // You must retry the commit with the new precommit token.
+ MultiplexedSessionPrecommitToken precommit_token = 4;
+ }
+
+ // If `TransactionOptions.isolation_level` is set to
+ // `IsolationLevel.REPEATABLE_READ`, then the snapshot timestamp is the
+ // timestamp at which all reads in the transaction ran. This timestamp is
+ // never returned.
+ google.protobuf.Timestamp snapshot_timestamp = 5;
+
+ // Optional. A cache update expresses a set of changes the client should
+ // incorporate into its location cache. The client should discard the changes
+ // if they are older than the data it already has. This data can be obtained
+ // in response to requests that included a `RoutingHint` field, but may also
+ // be obtained by explicit location-fetching RPCs which may be added in the
+ // future.
+ CacheUpdate cache_update = 6 [(google.api.field_behavior) = OPTIONAL];
+
+ // The isolation level used for the read-write transaction.
+ TransactionOptions.IsolationLevel isolation_level = 7;
+
+ // The read lock mode used for the read-write transaction.
+ TransactionOptions.ReadWrite.ReadLockMode read_lock_mode = 8;
+}
diff --git a/packages/google-cloud-spanner-api/protos/google/spanner/v1/keys.proto b/packages/google-cloud-spanner-api/protos/google/spanner/v1/keys.proto
new file mode 100644
index 000000000000..5e30e831e64d
--- /dev/null
+++ b/packages/google-cloud-spanner-api/protos/google/spanner/v1/keys.proto
@@ -0,0 +1,163 @@
+// Copyright 2026 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";
+
+option csharp_namespace = "Google.Cloud.Spanner.V1";
+option go_package = "cloud.google.com/go/spanner/apiv1/spannerpb;spannerpb";
+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/packages/google-cloud-spanner-api/protos/google/spanner/v1/location.proto b/packages/google-cloud-spanner-api/protos/google/spanner/v1/location.proto
new file mode 100644
index 000000000000..870dc0ec0a9c
--- /dev/null
+++ b/packages/google-cloud-spanner-api/protos/google/spanner/v1/location.proto
@@ -0,0 +1,388 @@
+// Copyright 2026 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/type.proto";
+
+option csharp_namespace = "Google.Cloud.Spanner.V1";
+option go_package = "cloud.google.com/go/spanner/apiv1/spannerpb;spannerpb";
+option java_multiple_files = true;
+option java_outer_classname = "LocationProto";
+option java_package = "com.google.spanner.v1";
+option php_namespace = "Google\\Cloud\\Spanner\\V1";
+option ruby_package = "Google::Cloud::Spanner::V1";
+
+// A `Range` represents a range of keys in a database. The keys themselves
+// are encoded in "sortable string format", also known as ssformat. Consult
+// Spanner's open source client libraries for details on the encoding.
+//
+// Each range represents a contiguous range of rows, possibly from multiple
+// tables/indexes. Each range is associated with a single paxos group (known as
+// a "group" throughout this API), a split (which names the exact range within
+// the group), and a generation that can be used to determine whether a given
+// `Range` represents a newer or older location for the key range.
+message Range {
+ // The start key of the range, inclusive. Encoded in "sortable string format"
+ // (ssformat).
+ bytes start_key = 1;
+
+ // The limit key of the range, exclusive. Encoded in "sortable string format"
+ // (ssformat).
+ bytes limit_key = 2;
+
+ // The UID of the paxos group where this range is stored. UIDs are unique
+ // within the database. References `Group.group_uid`.
+ uint64 group_uid = 3;
+
+ // A group can store multiple ranges of keys. Each key range is named by an
+ // ID (the split ID). Within a group, split IDs are unique. The `split_id`
+ // names the exact split in `group_uid` where this range is stored.
+ uint64 split_id = 4;
+
+ // `generation` indicates the freshness of the range information contained
+ // in this proto. Generations can be compared lexicographically; if generation
+ // A is greater than generation B, then the `Range` corresponding to A is
+ // newer than the `Range` corresponding to B, and should be used
+ // preferentially.
+ bytes generation = 5;
+}
+
+// A `Tablet` represents a single replica of a `Group`. A tablet is served by a
+// single server at a time, and can move between servers due to server death or
+// simply load balancing.
+message Tablet {
+ // Indicates the role of the tablet.
+ enum Role {
+ // Not specified.
+ ROLE_UNSPECIFIED = 0;
+
+ // The tablet can perform reads and (if elected leader) writes.
+ READ_WRITE = 1;
+
+ // The tablet can only perform reads.
+ READ_ONLY = 2;
+ }
+
+ // The UID of the tablet, unique within the database. Matches the
+ // `tablet_uids` and `leader_tablet_uid` fields in `Group`.
+ uint64 tablet_uid = 1;
+
+ // The address of the server that is serving this tablet -- either an IP
+ // address or DNS hostname and a port number.
+ string server_address = 2;
+
+ // Where this tablet is located. This is the name of a Google Cloud region,
+ // such as "us-central1".
+ string location = 3;
+
+ // The role of the tablet.
+ Role role = 4;
+
+ // `incarnation` indicates the freshness of the tablet information contained
+ // in this proto. Incarnations can be compared lexicographically; if
+ // incarnation A is greater than incarnation B, then the `Tablet`
+ // corresponding to A is newer than the `Tablet` corresponding to B, and
+ // should be used preferentially.
+ bytes incarnation = 5;
+
+ // Distances help the client pick the closest tablet out of the list of
+ // tablets for a given request. Tablets with lower distances should generally
+ // be preferred. Tablets with the same distance are approximately equally
+ // close; the client can choose arbitrarily.
+ //
+ // Distances do not correspond precisely to expected latency, geographical
+ // distance, or anything else. Distances should be compared only between
+ // tablets of the same group; they are not meaningful between different
+ // groups.
+ //
+ // A value of zero indicates that the tablet may be in the same zone as
+ // the client, and have minimum network latency. A value less than or equal to
+ // five indicates that the tablet is thought to be in the same region as the
+ // client, and may have a few milliseconds of network latency. Values greater
+ // than five are most likely in a different region, with non-trivial network
+ // latency.
+ //
+ // Clients should use the following algorithm:
+ // * If the request is using a directed read, eliminate any tablets that
+ // do not match the directed read's target zone and/or replica type.
+ // * (Read-write transactions only) Choose leader tablet if it has an
+ // distance <=5.
+ // * Group and sort tablets by distance. Choose a random
+ // tablet with the lowest distance. If the request
+ // is not a directed read, only consider replicas with distances <=5.
+ // * Send the request to the fallback endpoint.
+ //
+ // The tablet picked by this algorithm may be skipped, either because it is
+ // marked as `skip` by the server or because the corresponding server is
+ // unreachable, flow controlled, etc. Skipped tablets should be added to the
+ // `skipped_tablet_uid` field in `RoutingHint`; the algorithm above should
+ // then be re-run without including the skipped tablet(s) to pick the next
+ // best tablet.
+ uint32 distance = 6;
+
+ // If true, the tablet should not be chosen by the client. Typically, this
+ // signals that the tablet is unhealthy in some way. Tablets with `skip`
+ // set to true should be reported back to the server in
+ // `RoutingHint.skipped_tablet_uid`; this cues the server to send updated
+ // information for this tablet should it become usable again.
+ bool skip = 7;
+}
+
+// A `Group` represents a paxos group in a database. A group is a set of
+// tablets that are replicated across multiple servers. Groups may have a leader
+// tablet. Groups store one (or sometimes more) ranges of keys.
+message Group {
+ // The UID of the paxos group, unique within the database. Matches the
+ // `group_uid` field in `Range`.
+ uint64 group_uid = 1;
+
+ // A list of tablets that are part of the group. Note that this list may not
+ // be exhaustive; it will only include tablets the server considers useful
+ // to the client. The returned list is ordered ascending by distance.
+ //
+ // Tablet UIDs reference `Tablet.tablet_uid`.
+ repeated Tablet tablets = 2;
+
+ // The last known leader tablet of the group as an index into `tablets`. May
+ // be negative if the group has no known leader.
+ int32 leader_index = 3;
+
+ // `generation` indicates the freshness of the group information (including
+ // leader information) contained in this proto. Generations can be compared
+ // lexicographically; if generation A is greater than generation B, then the
+ // `Group` corresponding to A is newer than the `Group` corresponding to B,
+ // and should be used preferentially.
+ bytes generation = 4;
+}
+
+// A `KeyRecipe` provides the metadata required to translate reads, mutations,
+// and queries into a byte array in "sortable string format" (ssformat)that can
+// be used with `Range`s to route requests. Note that the client *must* tolerate
+// `KeyRecipe`s that appear to be invalid, since the `KeyRecipe` format may
+// change over time. Requests with invalid `KeyRecipe`s should be routed to a
+// default server.
+message KeyRecipe {
+ // An ssformat key is composed of a sequence of tag numbers and key column
+ // values. `Part` represents a single tag or key column value.
+ message Part {
+ // The remaining fields encode column values.
+ enum Order {
+ // Default value, equivalent to `ASCENDING`.
+ ORDER_UNSPECIFIED = 0;
+
+ // The key is ascending - corresponds to `ASC` in the schema definition.
+ ASCENDING = 1;
+
+ // The key is descending - corresponds to `DESC` in the schema definition.
+ DESCENDING = 2;
+ }
+
+ // The null order of the key column. This dictates where NULL values sort
+ // in the sorted order. Note that columns which are `NOT NULL` can have a
+ // special encoding.
+ enum NullOrder {
+ // Default value. This value is unused.
+ NULL_ORDER_UNSPECIFIED = 0;
+
+ // NULL values sort before any non-NULL values.
+ NULLS_FIRST = 1;
+
+ // NULL values sort after any non-NULL values.
+ NULLS_LAST = 2;
+
+ // The column does not support NULL values.
+ NOT_NULL = 3;
+ }
+
+ // If non-zero, `tag` is the only field present in this `Part`. The part
+ // is encoded by appending `tag` to the ssformat key.
+ uint32 tag = 1;
+
+ // Whether the key column is sorted ascending or descending. Only present
+ // if `tag` is zero.
+ Order order = 2;
+
+ // How NULLs are represented in the encoded key part. Only present if `tag`
+ // is zero.
+ NullOrder null_order = 3;
+
+ // The type of the key part. Only present if `tag` is zero.
+ Type type = 4;
+
+ // Only present if `tag` is zero.
+ oneof value_type {
+ // `identifier` is the name of the column or query parameter.
+ string identifier = 5;
+
+ // The constant value of the key part.
+ // It is present when query uses a constant as a part of the key.
+ google.protobuf.Value value = 6;
+
+ // If true, the client is responsible to fill in the value randomly.
+ // It's relevant only for the INT64 type.
+ bool random = 8;
+ }
+
+ // It is a repeated field to support fetching key columns from nested
+ // structs, such as `STRUCT` query parameters.
+ repeated int32 struct_identifiers = 7;
+ }
+
+ // A recipe can be associated with a table, index, or query. Tables recipes
+ // are used to encode read and write keys; index recipes are used for index
+ // reads, and query recipes are used only for SQL queries.
+ oneof target {
+ // A table name, matching the name from the database schema.
+ string table_name = 1;
+
+ // An index name, matching the name from the database schema.
+ string index_name = 2;
+
+ // The UID of a query, matching the UID from `RoutingHint`.
+ uint64 operation_uid = 3;
+ }
+
+ // Parts are in the order they should appear in the encoded key.
+ repeated Part part = 4;
+}
+
+// A `RecipeList` contains a list of `KeyRecipe`s, which share the same
+// schema generation.
+message RecipeList {
+ // The schema generation of the recipes. To be sent to the server in
+ // `RoutingHint.schema_generation` whenever one of the recipes is used.
+ // `schema_generation` values are comparable with each other; if generation A
+ // compares greater than generation B, then A is a more recent schema than B.
+ // Clients should in general aim to cache only the latest schema generation,
+ // and discard more stale recipes.
+ bytes schema_generation = 1;
+
+ // A list of recipes to be cached.
+ repeated KeyRecipe recipe = 3;
+}
+
+// A `CacheUpdate` expresses a set of changes the client should incorporate into
+// its location cache. These changes may or may not be newer than what the
+// client has in its cache, and should be discarded if necessary. `CacheUpdate`s
+// can be obtained in response to requests that included a `RoutingHint`
+// field, but may also be obtained by explicit location-fetching RPCs which may
+// be added in the future.
+message CacheUpdate {
+ // An internal ID for the database. Database names can be reused if a database
+ // is deleted and re-created. Each time the database is re-created, it will
+ // get a new database ID, which will never be re-used for any other database.
+ uint64 database_id = 1;
+
+ // A list of ranges to be cached.
+ repeated Range range = 2;
+
+ // A list of groups to be cached.
+ repeated Group group = 3;
+
+ // A list of recipes to be cached.
+ RecipeList key_recipes = 5;
+}
+
+// `RoutingHint` can be optionally added to location-aware Spanner
+// requests. It gives the server hints that can be used to route the request to
+// an appropriate server, potentially significantly decreasing latency and
+// improving throughput. To achieve improved performance, most fields must be
+// filled in with accurate values.
+//
+// The presence of a valid `RoutingHint` tells the server that the client
+// is location-aware.
+//
+// `RoutingHint` does not change the semantics of the request; it is
+// purely a performance hint; the request will perform the same actions on the
+// database's data as if `RoutingHint` were not present. However, if
+// the `RoutingHint` is incomplete or incorrect, the response may include
+// a `CacheUpdate` the client can use to correct its location cache.
+message RoutingHint {
+ // A tablet that was skipped by the client. See `Tablet.tablet_uid` and
+ // `Tablet.incarnation`.
+ message SkippedTablet {
+ // The tablet UID of the tablet that was skipped. See `Tablet.tablet_uid`.
+ uint64 tablet_uid = 1;
+
+ // The incarnation of the tablet that was skipped. See `Tablet.incarnation`.
+ bytes incarnation = 2;
+ }
+
+ // A session-scoped unique ID for the operation, computed client-side.
+ // Requests with the same `operation_uid` should have a shared 'shape',
+ // meaning that some fields are expected to be the same, such as the SQL
+ // query, the target table/columns (for reads) etc. Requests with the same
+ // `operation_uid` are meant to differ only in fields like keys/key
+ // ranges/query parameters, transaction IDs, etc.
+ //
+ // `operation_uid` must be non-zero for `RoutingHint` to be valid.
+ uint64 operation_uid = 1;
+
+ // The database ID of the database being accessed, see
+ // `CacheUpdate.database_id`. Should match the cache entries that were used
+ // to generate the rest of the fields in this `RoutingHint`.
+ uint64 database_id = 2;
+
+ // The schema generation of the recipe that was used to generate `key` and
+ // `limit_key`. See also `RecipeList.schema_generation`.
+ bytes schema_generation = 3;
+
+ // The key / key range that this request accesses. For operations that
+ // access a single key, `key` should be set and `limit_key` should be empty.
+ // For operations that access a key range, `key` and `limit_key` should both
+ // be set, to the inclusive start and exclusive end of the range respectively.
+ //
+ // The keys are encoded in "sortable string format" (ssformat), using a
+ // `KeyRecipe` that is appropriate for the request. See `KeyRecipe` for more
+ // details.
+ bytes key = 4;
+
+ // If this request targets a key range, this is the exclusive end of the
+ // range. See `key` for more details.
+ bytes limit_key = 5;
+
+ // The group UID of the group that the client believes serves the range
+ // defined by `key` and `limit_key`. See `Range.group_uid` for more details.
+ uint64 group_uid = 6;
+
+ // The split ID of the split that the client believes contains the range
+ // defined by `key` and `limit_key`. See `Range.split_id` for more details.
+ uint64 split_id = 7;
+
+ // The tablet UID of the tablet from group `group_uid` that the client
+ // believes is best to serve this request. See `Group.local_tablet_uids` and
+ // `Group.leader_tablet_uid`.
+ uint64 tablet_uid = 8;
+
+ // If the client had multiple options for tablet selection, and some of its
+ // first choices were unhealthy (e.g., the server is unreachable, or
+ // `Tablet.skip` is true), this field will contain the tablet UIDs of those
+ // tablets, with their incarnations. The server may include a `CacheUpdate`
+ // with new locations for those tablets.
+ repeated SkippedTablet skipped_tablet_uid = 9;
+
+ // If present, the client's current location. This should be the name of a
+ // Google Cloud zone or region, such as "us-central1".
+ //
+ // If absent, the client's location will be assumed to be the same as the
+ // location of the server the client ends up connected to.
+ //
+ // Locations are primarily valuable for clients that connect from regions
+ // other than the ones that contain the Spanner database.
+ string client_location = 10;
+}
diff --git a/packages/google-cloud-spanner-api/protos/google/spanner/v1/mutation.proto b/packages/google-cloud-spanner-api/protos/google/spanner/v1/mutation.proto
new file mode 100644
index 000000000000..7e3306a20382
--- /dev/null
+++ b/packages/google-cloud-spanner-api/protos/google/spanner/v1/mutation.proto
@@ -0,0 +1,156 @@
+// Copyright 2026 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/protobuf/struct.proto";
+import "google/protobuf/timestamp.proto";
+import "google/spanner/v1/keys.proto";
+
+option csharp_namespace = "Google.Cloud.Spanner.V1";
+option go_package = "cloud.google.com/go/spanner/apiv1/spannerpb;spannerpb";
+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 [(google.api.field_behavior) = REQUIRED];
+
+ // 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 [(google.api.field_behavior) = REQUIRED];
+
+ // 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 [(google.api.field_behavior) = REQUIRED];
+ }
+
+ // Arguments to [send][google.spanner.v1.Mutation.send] operations.
+ message Send {
+ // Required. The queue to which the message will be sent.
+ string queue = 1 [(google.api.field_behavior) = REQUIRED];
+
+ // Required. The primary key of the message to be sent.
+ google.protobuf.ListValue key = 2 [(google.api.field_behavior) = REQUIRED];
+
+ // The time at which Spanner will begin attempting to deliver the message.
+ // If `deliver_time` is not set, Spanner will deliver the message
+ // immediately. If `deliver_time` is in the past, Spanner will replace it
+ // with a value closer to the current time.
+ google.protobuf.Timestamp deliver_time = 3;
+
+ // The payload of the message.
+ google.protobuf.Value payload = 4;
+ }
+
+ // Arguments to [ack][google.spanner.v1.Mutation.ack] operations.
+ message Ack {
+ // Required. The queue where the message to be acked is stored.
+ string queue = 1 [(google.api.field_behavior) = REQUIRED];
+
+ // Required. The primary key of the message to be acked.
+ google.protobuf.ListValue key = 2 [(google.api.field_behavior) = REQUIRED];
+
+ // By default, an attempt to ack a message that does not exist will fail
+ // with a `NOT_FOUND` error. With `ignore_not_found` set to true, the ack
+ // will succeed even if the message does not exist. This is useful for
+ // unconditionally acking a message, even if it is missing or has already
+ // been acked.
+ bool ignore_not_found = 3;
+ }
+
+ // 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;
+
+ // Send a message to a queue.
+ Send send = 6;
+
+ // Ack a message from a queue.
+ Ack ack = 7;
+ }
+}
diff --git a/packages/google-cloud-spanner-api/protos/google/spanner/v1/query_plan.proto b/packages/google-cloud-spanner-api/protos/google/spanner/v1/query_plan.proto
new file mode 100644
index 000000000000..5850ff97fb21
--- /dev/null
+++ b/packages/google-cloud-spanner-api/protos/google/spanner/v1/query_plan.proto
@@ -0,0 +1,156 @@
+// Copyright 2026 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/protobuf/struct.proto";
+
+option csharp_namespace = "Google.Cloud.Spanner.V1";
+option go_package = "cloud.google.com/go/spanner/apiv1/spannerpb;spannerpb";
+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 {
+ // 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;
+ }
+
+ // 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 `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;
+}
+
+// Output of query advisor analysis.
+message QueryAdvisorResult {
+ // Recommendation to add new indexes to run queries more efficiently.
+ message IndexAdvice {
+ // Optional. DDL statements to add new indexes that will improve the query.
+ repeated string ddl = 1 [(google.api.field_behavior) = OPTIONAL];
+
+ // Optional. Estimated latency improvement factor. For example if the query
+ // currently takes 500 ms to run and the estimated latency with new indexes
+ // is 100 ms this field will be 5.
+ double improvement_factor = 2 [(google.api.field_behavior) = OPTIONAL];
+ }
+
+ // Optional. Index Recommendation for a query. This is an optional field and
+ // the recommendation will only be available when the recommendation
+ // guarantees significant improvement in query performance.
+ repeated IndexAdvice index_advice = 1
+ [(google.api.field_behavior) = OPTIONAL];
+}
+
+// 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;
+
+ // Optional. The advise/recommendations for a query. Currently this field will
+ // be serving index recommendations for a query.
+ QueryAdvisorResult query_advice = 2 [(google.api.field_behavior) = OPTIONAL];
+}
diff --git a/packages/google-cloud-spanner-api/protos/google/spanner/v1/result_set.proto b/packages/google-cloud-spanner-api/protos/google/spanner/v1/result_set.proto
new file mode 100644
index 000000000000..3851d688ce27
--- /dev/null
+++ b/packages/google-cloud-spanner-api/protos/google/spanner/v1/result_set.proto
@@ -0,0 +1,260 @@
+// Copyright 2026 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/protobuf/struct.proto";
+import "google/spanner/v1/location.proto";
+import "google/spanner/v1/query_plan.proto";
+import "google/spanner/v1/transaction.proto";
+import "google/spanner/v1/type.proto";
+
+option csharp_namespace = "Google.Cloud.Spanner.V1";
+option go_package = "cloud.google.com/go/spanner/apiv1/spannerpb;spannerpb";
+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 might or might not be populated, based on the
+ // [ExecuteSqlRequest.query_mode][google.spanner.v1.ExecuteSqlRequest.query_mode].
+ ResultSetStats stats = 3;
+
+ // Optional. A precommit token is included if the read-write transaction is on
+ // a multiplexed session. Pass the precommit token with the highest sequence
+ // number from this transaction attempt to the
+ // [Commit][google.spanner.v1.Spanner.Commit] request for this transaction.
+ MultiplexedSessionPrecommitToken precommit_token = 5
+ [(google.api.field_behavior) = OPTIONAL];
+
+ // Optional. A cache update expresses a set of changes the client should
+ // incorporate into its location cache. The client should discard the changes
+ // if they are older than the data it already has. This data can be obtained
+ // in response to requests that included a `RoutingHint` field, but may also
+ // be obtained by explicit location-fetching RPCs which may be added in the
+ // future.
+ CacheUpdate cache_update = 6 [(google.api.field_behavior) = OPTIONAL];
+}
+
+// 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's 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`: can't 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
+ // }
+ // {
+ // "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"`.
+ //
+ // Not all `PartialResultSet`s contain a `resume_token`. Execution can only be
+ // resumed from a previously yielded `resume_token`. For the above sequence of
+ // `PartialResultSet`s, resuming the query with `"resume_token": "Af65..."`
+ // yields results from the `PartialResultSet` with value "orl".
+ 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 is
+ // also present in the last response for DML statements.
+ ResultSetStats stats = 5;
+
+ // Optional. A precommit token is included if the read-write transaction
+ // has multiplexed sessions enabled. Pass the precommit token with the highest
+ // sequence number from this transaction attempt to the
+ // [Commit][google.spanner.v1.Spanner.Commit] request for this transaction.
+ MultiplexedSessionPrecommitToken precommit_token = 8
+ [(google.api.field_behavior) = OPTIONAL];
+
+ // Optional. Indicates whether this is the last `PartialResultSet` in the
+ // stream. The server might optionally set this field. Clients shouldn't rely
+ // on this field being set in all cases.
+ bool last = 9 [(google.api.field_behavior) = OPTIONAL];
+
+ // Optional. A cache update expresses a set of changes the client should
+ // incorporate into its location cache. The client should discard the changes
+ // if they are older than the data it already has. This data can be obtained
+ // in response to requests that included a `RoutingHint` field, but may also
+ // be obtained by explicit location-fetching RPCs which may be added in the
+ // future.
+ CacheUpdate cache_update = 10 [(google.api.field_behavior) = OPTIONAL];
+}
+
+// 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;
+
+ // A SQL query can be parameterized. In PLAN mode, these parameters can be
+ // undeclared. This indicates the field names and types for those undeclared
+ // parameters in the SQL query. For example, a SQL query like `"SELECT * FROM
+ // Users where UserId = @userId and UserName = @userName "` could return a
+ // `undeclared_parameters` value like:
+ //
+ // "fields": [
+ // { "name": "UserId", "type": { "code": "INT64" } },
+ // { "name": "UserName", "type": { "code": "STRING" } },
+ // ]
+ StructType undeclared_parameters = 3;
+}
+
+// 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 doesn't offer exactly-once semantics, so it
+ // returns a lower bound of the rows modified.
+ int64 row_count_lower_bound = 4;
+ }
+}
diff --git a/packages/google-cloud-spanner-api/protos/google/spanner/v1/spanner.proto b/packages/google-cloud-spanner-api/protos/google/spanner/v1/spanner.proto
new file mode 100644
index 000000000000..598c61494067
--- /dev/null
+++ b/packages/google-cloud-spanner-api/protos/google/spanner/v1/spanner.proto
@@ -0,0 +1,1472 @@
+// Copyright 2026 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 public "google/spanner/v1/commit_response.proto";
+
+import "google/api/annotations.proto";
+import "google/api/client.proto";
+import "google/api/field_behavior.proto";
+import "google/api/resource.proto";
+import "google/protobuf/duration.proto";
+import "google/protobuf/empty.proto";
+import "google/protobuf/struct.proto";
+import "google/protobuf/timestamp.proto";
+import "google/rpc/status.proto";
+import "google/spanner/v1/keys.proto";
+import "google/spanner/v1/location.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 = "cloud.google.com/go/spanner/apiv1/spannerpb;spannerpb";
+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's a good idea to
+ // delete idle and unneeded sessions.
+ // Aside from explicit deletes, Cloud Spanner can delete sessions when 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, for example, `"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 doesn't 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
+ // asynchronously triggers the 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 can't 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.
+ //
+ // The query string can be SQL or [Graph Query Language
+ // (GQL)](https://cloud.google.com/spanner/docs/reference/standard-sql/graph-intro).
+ 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.
+ //
+ // The query string can be SQL or [Graph Query Language
+ // (GQL)](https://cloud.google.com/spanner/docs/reference/standard-sql/graph-intro).
+ 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 can't 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 retry
+ // the transaction from the beginning, reusing 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's 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 isn't
+ // 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 isn't 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 isn't 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: "*"
+ };
+ }
+
+ // Batches the supplied mutation groups in a collection of efficient
+ // transactions. All mutations in a group are committed atomically. However,
+ // mutations across groups can be committed non-atomically in an unspecified
+ // order and thus, they must be independent of each other. Partial failure is
+ // possible, that is, some groups might have been committed successfully,
+ // while some might have failed. The results of individual batches are
+ // streamed into the response as the batches are applied.
+ //
+ // `BatchWrite` requests are not replay protected, meaning that each mutation
+ // group can be applied more than once. Replays of non-idempotent mutations
+ // can have undesirable effects. For example, replays of an insert mutation
+ // can produce an already exists error or if you use generated or commit
+ // timestamp-based keys, it can result in additional rows being added to the
+ // mutation's table. We recommend structuring your mutation groups to be
+ // idempotent to avoid this issue.
+ rpc BatchWrite(BatchWriteRequest) returns (stream BatchWriteResponse) {
+ option (google.api.http) = {
+ post: "/v1/{session=projects/*/instances/*/databases/*/sessions/*}:batchWrite"
+ body: "*"
+ };
+ option (google.api.method_signature) = "session,mutation_groups";
+ }
+
+ // Retrieves a cache update for a given database.
+ //
+ // This RPC can be used to warm up the client cache by fetching key recipes
+ // and server information for a given database. It is recommended to call
+ // this RPC at the beginning of the client's lifecycle, prior to any other
+ // data plane operations.
+ //
+ // The cache update is returned as a stream because the response can be too
+ // large to fit into a single `CacheUpdate` message.
+ rpc FetchCacheUpdate(FetchCacheUpdateRequest) returns (stream CacheUpdate) {
+ option (google.api.http) = {
+ post: "/v1/{database=projects/*/instances/*/databases/*}:cacheUpdate"
+ body: "*"
+ };
+ option (google.api.method_signature) = "database";
+ }
+}
+
+// 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"
+ }
+ ];
+
+ // Required. The session to create.
+ Session session = 2 [(google.api.field_behavior) = REQUIRED];
+}
+
+// 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 apply to each created session.
+ Session session_template = 2;
+
+ // Required. The number of sessions to be created in this batch call. At least
+ // one session is created. The API can 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}"
+ plural: "sessions"
+ singular: "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's
+ // typically earlier than the actual last use time.
+ google.protobuf.Timestamp approximate_last_use_time = 4
+ [(google.api.field_behavior) = OUTPUT_ONLY];
+
+ // The database role which created this session.
+ string creator_role = 5;
+
+ // Optional. If `true`, specifies a multiplexed session. Use a multiplexed
+ // session for multiple, concurrent operations including any combination of
+ // read-only and read-write transactions. Use
+ // [`sessions.create`][google.spanner.v1.Spanner.CreateSession] to create
+ // multiplexed sessions. Don't use
+ // [BatchCreateSessions][google.spanner.v1.Spanner.BatchCreateSessions] to
+ // create a multiplexed session. You can't delete or list multiplexed
+ // sessions.
+ bool multiplexed = 6 [(google.api.field_behavior) = OPTIONAL];
+}
+
+// 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 isn't applicable
+ // for [BeginTransaction][google.spanner.v1.Spanner.BeginTransaction].
+ //
+ // The priority acts as a hint to the Cloud Spanner scheduler and doesn't
+ // 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 can 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 is fulfilled ahead of a higher priority
+ // request.
+ // * If a transaction contains multiple operations with different priorities,
+ // Cloud Spanner doesn't guarantee to process the higher priority
+ // operations first. There might be other constraints to satisfy, such as
+ // the 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;
+ }
+
+ // Container for various pieces of client-owned context attached to a request.
+ message ClientContext {
+ // Optional. Map of parameter name to value for this request. These values
+ // will be returned by any SECURE_CONTEXT() calls invoked by this request
+ // (e.g., by queries against Parameterized Secure Views).
+ map secure_context = 1
+ [(google.api.field_behavior) = OPTIONAL];
+ }
+
+ // 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 (for example,
+ // `CommitRequest`).
+ // Legal characters for `request_tag` values are all printable characters
+ // (ASCII 32 - 126) and the length of a request_tag is limited to 50
+ // characters. Values that exceed this limit are truncated.
+ // Any leading underscore (_) characters are removed from the string.
+ 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.
+ // To enable tagging on a transaction, `transaction_tag` must be set to the
+ // same value for all requests belonging to the same transaction, including
+ // [BeginTransaction][google.spanner.v1.Spanner.BeginTransaction].
+ // If this request doesn't belong to any transaction, `transaction_tag` is
+ // ignored.
+ // Legal characters for `transaction_tag` values are all printable characters
+ // (ASCII 32 - 126) and the length of a `transaction_tag` is limited to 50
+ // characters. Values that exceed this limit are truncated.
+ // Any leading underscore (_) characters are removed from the string.
+ string transaction_tag = 3;
+
+ // Optional. Optional context that may be needed for some requests.
+ ClientContext client_context = 4 [(google.api.field_behavior) = OPTIONAL];
+}
+
+// The `DirectedReadOptions` can be used to indicate which replicas or regions
+// should be used for non-transactional reads or queries.
+//
+// `DirectedReadOptions` can only be specified for a read-only transaction,
+// otherwise the API returns an `INVALID_ARGUMENT` error.
+message DirectedReadOptions {
+ // The directed read replica selector.
+ // Callers must provide one or more of the following fields for replica
+ // selection:
+ //
+ // * `location` - The location must be one of the regions within the
+ // multi-region configuration of your database.
+ // * `type` - The type of the replica.
+ //
+ // Some examples of using replica_selectors are:
+ //
+ // * `location:us-east1` --> The "us-east1" replica(s) of any available type
+ // is used to process the request.
+ // * `type:READ_ONLY` --> The "READ_ONLY" type replica(s) in the nearest
+ // available location are used to process the
+ // request.
+ // * `location:us-east1 type:READ_ONLY` --> The "READ_ONLY" type replica(s)
+ // in location "us-east1" is used to process
+ // the request.
+ message ReplicaSelection {
+ // Indicates the type of replica.
+ enum Type {
+ // Not specified.
+ TYPE_UNSPECIFIED = 0;
+
+ // Read-write replicas support both reads and writes.
+ READ_WRITE = 1;
+
+ // Read-only replicas only support reads (not writes).
+ READ_ONLY = 2;
+ }
+
+ // The location or region of the serving requests, for example, "us-east1".
+ string location = 1;
+
+ // The type of replica.
+ Type type = 2;
+ }
+
+ // An `IncludeReplicas` contains a repeated set of `ReplicaSelection` which
+ // indicates the order in which replicas should be considered.
+ message IncludeReplicas {
+ // The directed read replica selector.
+ repeated ReplicaSelection replica_selections = 1;
+
+ // If `true`, Spanner doesn't route requests to a replica outside the
+ // <`include_replicas` list when all of the specified replicas are
+ // unavailable or unhealthy. Default value is `false`.
+ bool auto_failover_disabled = 2;
+ }
+
+ // An ExcludeReplicas contains a repeated set of ReplicaSelection that should
+ // be excluded from serving requests.
+ message ExcludeReplicas {
+ // The directed read replica selector.
+ repeated ReplicaSelection replica_selections = 1;
+ }
+
+ // Required. At most one of either `include_replicas` or `exclude_replicas`
+ // should be present in the message.
+ oneof replicas {
+ // `Include_replicas` indicates the order of replicas (as they appear in
+ // this list) to process the request. If `auto_failover_disabled` is set to
+ // `true` and all replicas are exhausted without finding a healthy replica,
+ // Spanner waits for a replica in the list to become available, requests
+ // might fail due to `DEADLINE_EXCEEDED` errors.
+ IncludeReplicas include_replicas = 1;
+
+ // `Exclude_replicas` indicates that specified replicas should be excluded
+ // from serving requests. Spanner doesn't route requests to the replicas
+ // in this list.
+ ExcludeReplicas exclude_replicas = 2;
+ }
+}
+
+// The request for [ExecuteSql][google.spanner.v1.Spanner.ExecuteSql] and
+// [ExecuteStreamingSql][google.spanner.v1.Spanner.ExecuteStreamingSql].
+message ExecuteSqlRequest {
+ // 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 the query plan, overall execution statistics,
+ // operator level execution statistics along with the results. This has a
+ // performance overhead compared to the other modes. It isn't recommended
+ // to use this mode for production traffic.
+ PROFILE = 2;
+
+ // This mode returns the overall (but not operator-level) execution
+ // statistics along with the results.
+ WITH_STATS = 3;
+
+ // This mode returns the query plan, overall (but not operator-level)
+ // execution statistics along with the results.
+ WITH_PLAN_AND_STATS = 4;
+ }
+
+ // 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 isn't set.
+ //
+ // The statistics package requested by the query has to be exempt from
+ // garbage collection. This can be achieved with the following DDL
+ // statement:
+ //
+ // ```sql
+ // 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;
+ }
+
+ // 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's an error to execute a SQL statement with unbound parameters.
+ google.protobuf.Struct params = 4;
+
+ // It isn't 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, you can use `param_types` 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