legacy-libs/google-proto-files/google/spanner/admin/database/v1/spanner_database_admin.proto

   1 // Copyright 2018 Google LLC
   2 //
   3 // Licensed under the Apache License, Version 2.0 (the "License");
   4 // you may not use this file except in compliance with the License.
   5 // You may obtain a copy of the License at
   6 //
   7 //     http://www.apache.org/licenses/LICENSE-2.0
   8 //
   9 // Unless required by applicable law or agreed to in writing, software
  10 // distributed under the License is distributed on an "AS IS" BASIS,
  11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12 // See the License for the specific language governing permissions and
  13 // limitations under the License.
  14
  15 syntax = "proto3";
  16
  17 package google.spanner.admin.database.v1;
  18
  19 import "google/api/annotations.proto";
  20 import "google/iam/v1/iam_policy.proto";
  21 import "google/iam/v1/policy.proto";
  22 import "google/longrunning/operations.proto";
  23 import "google/protobuf/empty.proto";
  24 import "google/protobuf/timestamp.proto";
  25
  26 option csharp_namespace = "Google.Cloud.Spanner.Admin.Database.V1";
  27 option go_package = "google.golang.org/genproto/googleapis/spanner/admin/database/v1;database";
  28 option java_multiple_files = true;
  29 option java_outer_classname = "SpannerDatabaseAdminProto";
  30 option java_package = "com.google.spanner.admin.database.v1";
  31 option php_namespace = "Google\\Cloud\\Spanner\\Admin\\Database\\V1";
  32
  33 // Cloud Spanner Database Admin API
  34 //
  35 // The Cloud Spanner Database Admin API can be used to create, drop, and
  36 // list databases. It also enables updating the schema of pre-existing
  37 // databases.
  38 service DatabaseAdmin {
  39   // Lists Cloud Spanner databases.
  40   rpc ListDatabases(ListDatabasesRequest) returns (ListDatabasesResponse) {
  41     option (google.api.http) = {
  42       get: "/v1/{parent=projects/*/instances/*}/databases"
  43     };
  44   }
  45
  46   // Creates a new Cloud Spanner database and starts to prepare it for serving.
  47   // The returned [long-running operation][google.longrunning.Operation] will
  48   // have a name of the format `<database_name>/operations/<operation_id>` and
  49   // can be used to track preparation of the database. The
  50   // [metadata][google.longrunning.Operation.metadata] field type is
  51   // [CreateDatabaseMetadata][google.spanner.admin.database.v1.CreateDatabaseMetadata].
  52   // The [response][google.longrunning.Operation.response] field type is
  53   // [Database][google.spanner.admin.database.v1.Database], if successful.
  54   rpc CreateDatabase(CreateDatabaseRequest)
  55       returns (google.longrunning.Operation) {
  56     option (google.api.http) = {
  57       post: "/v1/{parent=projects/*/instances/*}/databases"
  58       body: "*"
  59     };
  60   }
  61
  62   // Gets the state of a Cloud Spanner database.
  63   rpc GetDatabase(GetDatabaseRequest) returns (Database) {
  64     option (google.api.http) = {
  65       get: "/v1/{name=projects/*/instances/*/databases/*}"
  66     };
  67   }
  68
  69   // Updates the schema of a Cloud Spanner database by
  70   // creating/altering/dropping tables, columns, indexes, etc. The returned
  71   // [long-running operation][google.longrunning.Operation] will have a name of
  72   // the format `<database_name>/operations/<operation_id>` and can be used to
  73   // track execution of the schema change(s). The
  74   // [metadata][google.longrunning.Operation.metadata] field type is
  75   // [UpdateDatabaseDdlMetadata][google.spanner.admin.database.v1.UpdateDatabaseDdlMetadata].
  76   // The operation has no response.
  77   rpc UpdateDatabaseDdl(UpdateDatabaseDdlRequest)
  78       returns (google.longrunning.Operation) {
  79     option (google.api.http) = {
  80       patch: "/v1/{database=projects/*/instances/*/databases/*}/ddl"
  81       body: "*"
  82     };
  83   }
  84
  85   // Drops (aka deletes) a Cloud Spanner database.
  86   rpc DropDatabase(DropDatabaseRequest) returns (google.protobuf.Empty) {
  87     option (google.api.http) = {
  88       delete: "/v1/{database=projects/*/instances/*/databases/*}"
  89     };
  90   }
  91
  92   // Returns the schema of a Cloud Spanner database as a list of formatted
  93   // DDL statements. This method does not show pending schema updates, those may
  94   // be queried using the [Operations][google.longrunning.Operations] API.
  95   rpc GetDatabaseDdl(GetDatabaseDdlRequest) returns (GetDatabaseDdlResponse) {
  96     option (google.api.http) = {
  97       get: "/v1/{database=projects/*/instances/*/databases/*}/ddl"
  98     };
  99   }
 100
 101   // Sets the access control policy on a database resource. Replaces any
 102   // existing policy.
 103   //
 104   // Authorization requires `spanner.databases.setIamPolicy` permission on
 105   // [resource][google.iam.v1.SetIamPolicyRequest.resource].
 106   rpc SetIamPolicy(google.iam.v1.SetIamPolicyRequest)
 107       returns (google.iam.v1.Policy) {
 108     option (google.api.http) = {
 109       post: "/v1/{resource=projects/*/instances/*/databases/*}:setIamPolicy"
 110       body: "*"
 111     };
 112   }
 113
 114   // Gets the access control policy for a database resource. Returns an empty
 115   // policy if a database exists but does not have a policy set.
 116   //
 117   // Authorization requires `spanner.databases.getIamPolicy` permission on
 118   // [resource][google.iam.v1.GetIamPolicyRequest.resource].
 119   rpc GetIamPolicy(google.iam.v1.GetIamPolicyRequest)
 120       returns (google.iam.v1.Policy) {
 121     option (google.api.http) = {
 122       post: "/v1/{resource=projects/*/instances/*/databases/*}:getIamPolicy"
 123       body: "*"
 124     };
 125   }
 126
 127   // Returns permissions that the caller has on the specified database resource.
 128   //
 129   // Attempting this RPC on a non-existent Cloud Spanner database will result in
 130   // a NOT_FOUND error if the user has `spanner.databases.list` permission on
 131   // the containing Cloud Spanner instance. Otherwise returns an empty set of
 132   // permissions.
 133   rpc TestIamPermissions(google.iam.v1.TestIamPermissionsRequest)
 134       returns (google.iam.v1.TestIamPermissionsResponse) {
 135     option (google.api.http) = {
 136       post: "/v1/{resource=projects/*/instances/*/databases/*}:testIamPermissions"
 137       body: "*"
 138     };
 139   }
 140 }
 141
 142 // A Cloud Spanner database.
 143 message Database {
 144   // Indicates the current state of the database.
 145   enum State {
 146     // Not specified.
 147     STATE_UNSPECIFIED = 0;
 148
 149     // The database is still being created. Operations on the database may fail
 150     // with `FAILED_PRECONDITION` in this state.
 151     CREATING = 1;
 152
 153     // The database is fully created and ready for use.
 154     READY = 2;
 155   }
 156
 157   // Required. The name of the database. Values are of the form
 158   // `projects/<project>/instances/<instance>/databases/<database>`,
 159   // where `<database>` is as specified in the `CREATE DATABASE`
 160   // statement. This name can be passed to other API methods to
 161   // identify the database.
 162   string name = 1;
 163
 164   // Output only. The current database state.
 165   State state = 2;
 166 }
 167
 168 // The request for
 169 // [ListDatabases][google.spanner.admin.database.v1.DatabaseAdmin.ListDatabases].
 170 message ListDatabasesRequest {
 171   // Required. The instance whose databases should be listed.
 172   // Values are of the form `projects/<project>/instances/<instance>`.
 173   string parent = 1;
 174
 175   // Number of databases to be returned in the response. If 0 or less,
 176   // defaults to the server's maximum allowed page size.
 177   int32 page_size = 3;
 178
 179   // If non-empty, `page_token` should contain a
 180   // [next_page_token][google.spanner.admin.database.v1.ListDatabasesResponse.next_page_token]
 181   // from a previous
 182   // [ListDatabasesResponse][google.spanner.admin.database.v1.ListDatabasesResponse].
 183   string page_token = 4;
 184 }
 185
 186 // The response for
 187 // [ListDatabases][google.spanner.admin.database.v1.DatabaseAdmin.ListDatabases].
 188 message ListDatabasesResponse {
 189   // Databases that matched the request.
 190   repeated Database databases = 1;
 191
 192   // `next_page_token` can be sent in a subsequent
 193   // [ListDatabases][google.spanner.admin.database.v1.DatabaseAdmin.ListDatabases]
 194   // call to fetch more of the matching databases.
 195   string next_page_token = 2;
 196 }
 197
 198 // The request for
 199 // [CreateDatabase][google.spanner.admin.database.v1.DatabaseAdmin.CreateDatabase].
 200 message CreateDatabaseRequest {
 201   // Required. The name of the instance that will serve the new database.
 202   // Values are of the form `projects/<project>/instances/<instance>`.
 203   string parent = 1;
 204
 205   // Required. A `CREATE DATABASE` statement, which specifies the ID of the
 206   // new database.  The database ID must conform to the regular expression
 207   // `[a-z][a-z0-9_\-]*[a-z0-9]` and be between 2 and 30 characters in length.
 208   // If the database ID is a reserved word or if it contains a hyphen, the
 209   // database ID must be enclosed in backticks (`` ` ``).
 210   string create_statement = 2;
 211
 212   // An optional list of DDL statements to run inside the newly created
 213   // database. Statements can create tables, indexes, etc. These
 214   // statements execute atomically with the creation of the database:
 215   // if there is an error in any statement, the database is not created.
 216   repeated string extra_statements = 3;
 217 }
 218
 219 // Metadata type for the operation returned by
 220 // [CreateDatabase][google.spanner.admin.database.v1.DatabaseAdmin.CreateDatabase].
 221 message CreateDatabaseMetadata {
 222   // The database being created.
 223   string database = 1;
 224 }
 225
 226 // The request for
 227 // [GetDatabase][google.spanner.admin.database.v1.DatabaseAdmin.GetDatabase].
 228 message GetDatabaseRequest {
 229   // Required. The name of the requested database. Values are of the form
 230   // `projects/<project>/instances/<instance>/databases/<database>`.
 231   string name = 1;
 232 }
 233
 234 // Enqueues the given DDL statements to be applied, in order but not
 235 // necessarily all at once, to the database schema at some point (or
 236 // points) in the future. The server checks that the statements
 237 // are executable (syntactically valid, name tables that exist, etc.)
 238 // before enqueueing them, but they may still fail upon
 239 // later execution (e.g., if a statement from another batch of
 240 // statements is applied first and it conflicts in some way, or if
 241 // there is some data-related problem like a `NULL` value in a column to
 242 // which `NOT NULL` would be added). If a statement fails, all
 243 // subsequent statements in the batch are automatically cancelled.
 244 //
 245 // Each batch of statements is assigned a name which can be used with
 246 // the [Operations][google.longrunning.Operations] API to monitor
 247 // progress. See the
 248 // [operation_id][google.spanner.admin.database.v1.UpdateDatabaseDdlRequest.operation_id]
 249 // field for more details.
 250 message UpdateDatabaseDdlRequest {
 251   // Required. The database to update.
 252   string database = 1;
 253
 254   // DDL statements to be applied to the database.
 255   repeated string statements = 2;
 256
 257   // If empty, the new update request is assigned an
 258   // automatically-generated operation ID. Otherwise, `operation_id`
 259   // is used to construct the name of the resulting
 260   // [Operation][google.longrunning.Operation].
 261   //
 262   // Specifying an explicit operation ID simplifies determining
 263   // whether the statements were executed in the event that the
 264   // [UpdateDatabaseDdl][google.spanner.admin.database.v1.DatabaseAdmin.UpdateDatabaseDdl]
 265   // call is replayed, or the return value is otherwise lost: the
 266   // [database][google.spanner.admin.database.v1.UpdateDatabaseDdlRequest.database]
 267   // and `operation_id` fields can be combined to form the
 268   // [name][google.longrunning.Operation.name] of the resulting
 269   // [longrunning.Operation][google.longrunning.Operation]:
 270   // `<database>/operations/<operation_id>`.
 271   //
 272   // `operation_id` should be unique within the database, and must be
 273   // a valid identifier: `[a-z][a-z0-9_]*`. Note that
 274   // automatically-generated operation IDs always begin with an
 275   // underscore. If the named operation already exists,
 276   // [UpdateDatabaseDdl][google.spanner.admin.database.v1.DatabaseAdmin.UpdateDatabaseDdl]
 277   // returns `ALREADY_EXISTS`.
 278   string operation_id = 3;
 279 }
 280
 281 // Metadata type for the operation returned by
 282 // [UpdateDatabaseDdl][google.spanner.admin.database.v1.DatabaseAdmin.UpdateDatabaseDdl].
 283 message UpdateDatabaseDdlMetadata {
 284   // The database being modified.
 285   string database = 1;
 286
 287   // For an update this list contains all the statements. For an
 288   // individual statement, this list contains only that statement.
 289   repeated string statements = 2;
 290
 291   // Reports the commit timestamps of all statements that have
 292   // succeeded so far, where `commit_timestamps[i]` is the commit
 293   // timestamp for the statement `statements[i]`.
 294   repeated google.protobuf.Timestamp commit_timestamps = 3;
 295 }
 296
 297 // The request for
 298 // [DropDatabase][google.spanner.admin.database.v1.DatabaseAdmin.DropDatabase].
 299 message DropDatabaseRequest {
 300   // Required. The database to be dropped.
 301   string database = 1;
 302 }
 303
 304 // The request for
 305 // [GetDatabaseDdl][google.spanner.admin.database.v1.DatabaseAdmin.GetDatabaseDdl].
 306 message GetDatabaseDdlRequest {
 307   // Required. The database whose schema we wish to get.
 308   string database = 1;
 309 }
 310
 311 // The response for
 312 // [GetDatabaseDdl][google.spanner.admin.database.v1.DatabaseAdmin.GetDatabaseDdl].
 313 message GetDatabaseDdlResponse {
 314   // A list of formatted DDL statements defining the schema of the database
 315   // specified in the request.
 316   repeated string statements = 1;
 317 }