Google Cloud Spanner C++ Client  1.34.0
A C++ Client Library for Google Cloud Spanner
database_admin_client.h
Go to the documentation of this file.
1 // Copyright 2021 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 // https://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 // Generated by the Codegen C++ plugin.
16 // If you make any local changes, they will be lost.
17 // source: google/spanner/admin/database/v1/spanner_database_admin.proto
18 
19 #ifndef GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_SPANNER_ADMIN_DATABASE_ADMIN_CLIENT_H
20 #define GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_SPANNER_ADMIN_DATABASE_ADMIN_CLIENT_H
21 
22 #include "google/cloud/spanner/admin/database_admin_connection.h"
23 #include "google/cloud/future.h"
24 #include "google/cloud/iam_updater.h"
25 #include "google/cloud/options.h"
26 #include "google/cloud/polling_policy.h"
27 #include "google/cloud/status_or.h"
28 #include "google/cloud/version.h"
29 #include <google/longrunning/operations.grpc.pb.h>
30 #include <memory>
31 
32 namespace google {
33 namespace cloud {
34 namespace spanner_admin {
36 
37 ///
38 /// Cloud Spanner Database Admin API
39 ///
40 /// The Cloud Spanner Database Admin API can be used to create, drop, and
41 /// list databases. It also enables updating the schema of pre-existing
42 /// databases. It can be also used to create, delete and list backups for a
43 /// database and to restore from an existing backup.
44 ///
45 /// @par Equality
46 ///
47 /// Instances of this class created via copy-construction or copy-assignment
48 /// always compare equal. Instances created with equal
49 /// `std::shared_ptr<*Connection>` objects compare equal. Objects that compare
50 /// equal share the same underlying resources.
51 ///
52 /// @par Performance
53 ///
54 /// Creating a new instance of this class is a relatively expensive operation,
55 /// new objects establish new connections to the service. In contrast,
56 /// copy-construction, move-construction, and the corresponding assignment
57 /// operations are relatively efficient as the copies share all underlying
58 /// resources.
59 ///
60 /// @par Thread Safety
61 ///
62 /// Concurrent access to different instances of this class, even if they compare
63 /// equal, is guaranteed to work. Two or more threads operating on the same
64 /// instance of this class is not guaranteed to work. Since copy-construction
65 /// and move-construction is a relatively efficient operation, consider using
66 /// such a copy when using this class from multiple threads.
67 ///
69  public:
71  std::shared_ptr<DatabaseAdminConnection> connection);
73 
74  //@{
75  // @name Copy and move support
80  //@}
81 
82  //@{
83  // @name Equality
84  friend bool operator==(DatabaseAdminClient const& a,
85  DatabaseAdminClient const& b) {
86  return a.connection_ == b.connection_;
87  }
88  friend bool operator!=(DatabaseAdminClient const& a,
89  DatabaseAdminClient const& b) {
90  return !(a == b);
91  }
92  //@}
93 
94  ///
95  /// Lists Cloud Spanner databases.
96  ///
97  /// @param parent Required. The instance whose databases should be listed.
98  /// Values are of the form `projects/<project>/instances/<instance>`.
99  /// @return
100  /// @googleapis_link{google::spanner::admin::database::v1::Database,google/spanner/admin/database/v1/spanner_database_admin.proto#L326}
101  ///
102  /// [google.spanner.admin.database.v1.ListDatabasesRequest]:
103  /// @googleapis_reference_link{google/spanner/admin/database/v1/spanner_database_admin.proto#L413}
104  /// [google.spanner.admin.database.v1.Database]:
105  /// @googleapis_reference_link{google/spanner/admin/database/v1/spanner_database_admin.proto#L326}
106  ///
107  StreamRange<google::spanner::admin::database::v1::Database> ListDatabases(
108  std::string const& parent);
109 
110  ///
111  /// Creates a new Cloud Spanner database and starts to prepare it for serving.
112  /// The returned [long-running operation][google.longrunning.Operation] will
113  /// have a name of the format `<database_name>/operations/<operation_id>` and
114  /// can be used to track preparation of the database. The
115  /// [metadata][google.longrunning.Operation.metadata] field type is
116  /// [CreateDatabaseMetadata][google.spanner.admin.database.v1.CreateDatabaseMetadata].
117  /// The [response][google.longrunning.Operation.response] field type is
118  /// [Database][google.spanner.admin.database.v1.Database], if successful.
119  ///
120  /// @param parent Required. The name of the instance that will serve the new
121  /// database.
122  /// Values are of the form `projects/<project>/instances/<instance>`.
123  /// @param create_statement Required. A `CREATE DATABASE` statement, which
124  /// specifies the ID of the
125  /// new database. The database ID must conform to the regular expression
126  /// `[a-z][a-z0-9_\-]*[a-z0-9]` and be between 2 and 30 characters in length.
127  /// If the database ID is a reserved word or if it contains a hyphen, the
128  /// database ID must be enclosed in backticks (`` ` ``).
129  /// @return
130  /// @googleapis_link{google::spanner::admin::database::v1::Database,google/spanner/admin/database/v1/spanner_database_admin.proto#L326}
131  ///
132  /// [google.spanner.admin.database.v1.CreateDatabaseRequest]:
133  /// @googleapis_reference_link{google/spanner/admin/database/v1/spanner_database_admin.proto#L445}
134  /// [google.spanner.admin.database.v1.Database]:
135  /// @googleapis_reference_link{google/spanner/admin/database/v1/spanner_database_admin.proto#L326}
136  ///
137  future<StatusOr<google::spanner::admin::database::v1::Database>>
138  CreateDatabase(std::string const& parent,
139  std::string const& create_statement);
140 
141  ///
142  /// Gets the state of a Cloud Spanner database.
143  ///
144  /// @param name Required. The name of the requested database. Values are of
145  /// the form
146  /// `projects/<project>/instances/<instance>/databases/<database>`.
147  /// @return
148  /// @googleapis_link{google::spanner::admin::database::v1::Database,google/spanner/admin/database/v1/spanner_database_admin.proto#L326}
149  ///
150  /// [google.spanner.admin.database.v1.GetDatabaseRequest]:
151  /// @googleapis_reference_link{google/spanner/admin/database/v1/spanner_database_admin.proto#L484}
152  /// [google.spanner.admin.database.v1.Database]:
153  /// @googleapis_reference_link{google/spanner/admin/database/v1/spanner_database_admin.proto#L326}
154  ///
155  StatusOr<google::spanner::admin::database::v1::Database> GetDatabase(
156  std::string const& name);
157 
158  ///
159  /// Updates the schema of a Cloud Spanner database by
160  /// creating/altering/dropping tables, columns, indexes, etc. The returned
161  /// [long-running operation][google.longrunning.Operation] will have a name of
162  /// the format `<database_name>/operations/<operation_id>` and can be used to
163  /// track execution of the schema change(s). The
164  /// [metadata][google.longrunning.Operation.metadata] field type is
165  /// [UpdateDatabaseDdlMetadata][google.spanner.admin.database.v1.UpdateDatabaseDdlMetadata].
166  /// The operation has no response.
167  ///
168  /// @param database Required. The database to update.
169  /// @param statements Required. DDL statements to be applied to the database.
170  /// @return
171  /// @googleapis_link{google::spanner::admin::database::v1::UpdateDatabaseDdlMetadata,google/spanner/admin/database/v1/spanner_database_admin.proto#L547}
172  ///
173  /// [google.spanner.admin.database.v1.UpdateDatabaseDdlRequest]:
174  /// @googleapis_reference_link{google/spanner/admin/database/v1/spanner_database_admin.proto#L511}
175  /// [google.spanner.admin.database.v1.UpdateDatabaseDdlMetadata]:
176  /// @googleapis_reference_link{google/spanner/admin/database/v1/spanner_database_admin.proto#L547}
177  ///
178  future<
179  StatusOr<google::spanner::admin::database::v1::UpdateDatabaseDdlMetadata>>
180  UpdateDatabaseDdl(std::string const& database,
181  std::vector<std::string> const& statements);
182 
183  ///
184  /// Drops (aka deletes) a Cloud Spanner database.
185  /// Completed backups for the database will be retained according to their
186  /// `expire_time`.
187  ///
188  /// @param database Required. The database to be dropped.
189  ///
190  /// [google.spanner.admin.database.v1.DropDatabaseRequest]:
191  /// @googleapis_reference_link{google/spanner/admin/database/v1/spanner_database_admin.proto#L579}
192  ///
193  Status DropDatabase(std::string const& database);
194 
195  ///
196  /// Returns the schema of a Cloud Spanner database as a list of formatted
197  /// DDL statements. This method does not show pending schema updates, those
198  /// may be queried using the [Operations][google.longrunning.Operations] API.
199  ///
200  /// @param database Required. The database whose schema we wish to get.
201  /// Values are of the form
202  /// `projects/<project>/instances/<instance>/databases/<database>`
203  /// @return
204  /// @googleapis_link{google::spanner::admin::database::v1::GetDatabaseDdlResponse,google/spanner/admin/database/v1/spanner_database_admin.proto#L603}
205  ///
206  /// [google.spanner.admin.database.v1.GetDatabaseDdlRequest]:
207  /// @googleapis_reference_link{google/spanner/admin/database/v1/spanner_database_admin.proto#L590}
208  /// [google.spanner.admin.database.v1.GetDatabaseDdlResponse]:
209  /// @googleapis_reference_link{google/spanner/admin/database/v1/spanner_database_admin.proto#L603}
210  ///
211  StatusOr<google::spanner::admin::database::v1::GetDatabaseDdlResponse>
212  GetDatabaseDdl(std::string const& database);
213 
214  ///
215  /// Sets the access control policy on a database or backup resource.
216  /// Replaces any existing policy.
217  ///
218  /// Authorization requires `spanner.databases.setIamPolicy`
219  /// permission on [resource][google.iam.v1.SetIamPolicyRequest.resource].
220  /// For backups, authorization requires `spanner.backups.setIamPolicy`
221  /// permission on [resource][google.iam.v1.SetIamPolicyRequest.resource].
222  ///
223  /// @param resource REQUIRED: The resource for which the policy is being
224  /// specified.
225  /// See the operation documentation for the appropriate value for this field.
226  /// @param policy REQUIRED: The complete policy to be applied to the
227  /// `resource`. The size of
228  /// the policy is limited to a few 10s of KB. An empty policy is a
229  /// valid policy but certain Cloud Platform services (such as Projects)
230  /// might reject them.
231  /// @return
232  /// @googleapis_link{google::iam::v1::Policy,google/iam/v1/policy.proto#L88}
233  ///
234  /// [google.iam.v1.SetIamPolicyRequest]:
235  /// @googleapis_reference_link{google/iam/v1/iam_policy.proto#L98}
236  /// [google.iam.v1.Policy]:
237  /// @googleapis_reference_link{google/iam/v1/policy.proto#L88}
238  ///
239  StatusOr<google::iam::v1::Policy> SetIamPolicy(
240  std::string const& resource, google::iam::v1::Policy const& policy);
241 
242  /**
243  * Updates the IAM policy for @p resource using an optimistic concurrency
244  * control loop.
245  *
246  * The loop fetches the current policy for @p resource, and passes it to @p
247  * updater, which should return the new policy. This new policy should use the
248  * current etag so that the read-modify-write cycle can detect races and rerun
249  * the update when there is a mismatch. If the new policy does not have an
250  * etag, the existing policy will be blindly overwritten. If @p updater does
251  * not yield a policy, the control loop is terminated and kCancelled is
252  * returned.
253  *
254  * @param resource Required. The resource for which the policy is being
255  * specified. See the operation documentation for the appropriate value for
256  * this field.
257  * @param updater Required. Functor to map the current policy to a new one.
258  * @param options Optional. Options to control the loop. Expected options
259  * are:
260  * - `DatabaseAdminBackoffPolicyOption`
261  * @return google::iam::v1::Policy
262  */
263  StatusOr<google::iam::v1::Policy> SetIamPolicy(std::string const& resource,
264  IamUpdater const& updater,
265  Options options = {});
266 
267  ///
268  /// Gets the access control policy for a database or backup resource.
269  /// Returns an empty policy if a database or backup exists but does not have a
270  /// policy set.
271  ///
272  /// Authorization requires `spanner.databases.getIamPolicy` permission on
273  /// [resource][google.iam.v1.GetIamPolicyRequest.resource].
274  /// For backups, authorization requires `spanner.backups.getIamPolicy`
275  /// permission on [resource][google.iam.v1.GetIamPolicyRequest.resource].
276  ///
277  /// @param resource REQUIRED: The resource for which the policy is being
278  /// requested.
279  /// See the operation documentation for the appropriate value for this field.
280  /// @return
281  /// @googleapis_link{google::iam::v1::Policy,google/iam/v1/policy.proto#L88}
282  ///
283  /// [google.iam.v1.GetIamPolicyRequest]:
284  /// @googleapis_reference_link{google/iam/v1/iam_policy.proto#L113}
285  /// [google.iam.v1.Policy]:
286  /// @googleapis_reference_link{google/iam/v1/policy.proto#L88}
287  ///
288  StatusOr<google::iam::v1::Policy> GetIamPolicy(std::string const& resource);
289 
290  ///
291  /// Returns permissions that the caller has on the specified database or
292  /// backup resource.
293  ///
294  /// Attempting this RPC on a non-existent Cloud Spanner database will
295  /// result in a NOT_FOUND error if the user has
296  /// `spanner.databases.list` permission on the containing Cloud
297  /// Spanner instance. Otherwise returns an empty set of permissions.
298  /// Calling this method on a backup that does not exist will
299  /// result in a NOT_FOUND error if the user has
300  /// `spanner.backups.list` permission on the containing instance.
301  ///
302  /// @param resource REQUIRED: The resource for which the policy detail is
303  /// being requested.
304  /// See the operation documentation for the appropriate value for this field.
305  /// @param permissions The set of permissions to check for the `resource`.
306  /// Permissions with
307  /// wildcards (such as '*' or 'storage.*') are not allowed. For more
308  /// information see
309  /// [IAM Overview](https://cloud.google.com/iam/docs/overview#permissions).
310  /// @return
311  /// @googleapis_link{google::iam::v1::TestIamPermissionsResponse,google/iam/v1/iam_policy.proto#L141}
312  ///
313  /// [google.iam.v1.TestIamPermissionsRequest]:
314  /// @googleapis_reference_link{google/iam/v1/iam_policy.proto#L126}
315  /// [google.iam.v1.TestIamPermissionsResponse]:
316  /// @googleapis_reference_link{google/iam/v1/iam_policy.proto#L141}
317  ///
318  StatusOr<google::iam::v1::TestIamPermissionsResponse> TestIamPermissions(
319  std::string const& resource, std::vector<std::string> const& permissions);
320 
321  ///
322  /// Starts creating a new Cloud Spanner Backup.
323  /// The returned backup [long-running operation][google.longrunning.Operation]
324  /// will have a name of the format
325  /// `projects/<project>/instances/<instance>/backups/<backup>/operations/<operation_id>`
326  /// and can be used to track creation of the backup. The
327  /// [metadata][google.longrunning.Operation.metadata] field type is
328  /// [CreateBackupMetadata][google.spanner.admin.database.v1.CreateBackupMetadata].
329  /// The [response][google.longrunning.Operation.response] field type is
330  /// [Backup][google.spanner.admin.database.v1.Backup], if successful.
331  /// Cancelling the returned operation will stop the creation and delete the
332  /// backup. There can be only one pending backup creation per database. Backup
333  /// creation of different databases can run concurrently.
334  ///
335  /// @param parent Required. The name of the instance in which the backup will
336  /// be
337  /// created. This must be the same instance that contains the database the
338  /// backup will be created from. The backup will be stored in the
339  /// location(s) specified in the instance configuration of this
340  /// instance. Values are of the form
341  /// `projects/<project>/instances/<instance>`.
342  /// @param backup Required. The backup to create.
343  /// @param backup_id Required. The id of the backup to be created. The
344  /// `backup_id` appended to
345  /// `parent` forms the full backup name of the form
346  /// `projects/<project>/instances/<instance>/backups/<backup_id>`.
347  /// @return
348  /// @googleapis_link{google::spanner::admin::database::v1::Backup,google/spanner/admin/database/v1/backup.proto#L36}
349  ///
350  /// [google.spanner.admin.database.v1.CreateBackupRequest]:
351  /// @googleapis_reference_link{google/spanner/admin/database/v1/backup.proto#L123}
352  /// [google.spanner.admin.database.v1.Backup]:
353  /// @googleapis_reference_link{google/spanner/admin/database/v1/backup.proto#L36}
354  ///
355  future<StatusOr<google::spanner::admin::database::v1::Backup>> CreateBackup(
356  std::string const& parent,
357  google::spanner::admin::database::v1::Backup const& backup,
358  std::string const& backup_id);
359 
360  ///
361  /// Gets metadata on a pending or completed
362  /// [Backup][google.spanner.admin.database.v1.Backup].
363  ///
364  /// @param name Required. Name of the backup.
365  /// Values are of the form
366  /// `projects/<project>/instances/<instance>/backups/<backup>`.
367  /// @return
368  /// @googleapis_link{google::spanner::admin::database::v1::Backup,google/spanner/admin/database/v1/backup.proto#L36}
369  ///
370  /// [google.spanner.admin.database.v1.GetBackupRequest]:
371  /// @googleapis_reference_link{google/spanner/admin/database/v1/backup.proto#L202}
372  /// [google.spanner.admin.database.v1.Backup]:
373  /// @googleapis_reference_link{google/spanner/admin/database/v1/backup.proto#L36}
374  ///
375  StatusOr<google::spanner::admin::database::v1::Backup> GetBackup(
376  std::string const& name);
377 
378  ///
379  /// Updates a pending or completed
380  /// [Backup][google.spanner.admin.database.v1.Backup].
381  ///
382  /// @param backup Required. The backup to update. `backup.name`, and the
383  /// fields to be updated
384  /// as specified by `update_mask` are required. Other fields are ignored.
385  /// Update is only supported for the following fields:
386  /// * `backup.expire_time`.
387  /// @param update_mask Required. A mask specifying which fields (e.g.
388  /// `expire_time`) in the
389  /// Backup resource should be updated. This mask is relative to the Backup
390  /// resource, not to the request message. The field mask must always be
391  /// specified; this prevents any future fields from being erased accidentally
392  /// by clients that do not know about them.
393  /// @return
394  /// @googleapis_link{google::spanner::admin::database::v1::Backup,google/spanner/admin/database/v1/backup.proto#L36}
395  ///
396  /// [google.spanner.admin.database.v1.UpdateBackupRequest]:
397  /// @googleapis_reference_link{google/spanner/admin/database/v1/backup.proto#L186}
398  /// [google.spanner.admin.database.v1.Backup]:
399  /// @googleapis_reference_link{google/spanner/admin/database/v1/backup.proto#L36}
400  ///
401  StatusOr<google::spanner::admin::database::v1::Backup> UpdateBackup(
402  google::spanner::admin::database::v1::Backup const& backup,
403  google::protobuf::FieldMask const& update_mask);
404 
405  ///
406  /// Deletes a pending or completed
407  /// [Backup][google.spanner.admin.database.v1.Backup].
408  ///
409  /// @param name Required. Name of the backup to delete.
410  /// Values are of the form
411  /// `projects/<project>/instances/<instance>/backups/<backup>`.
412  ///
413  /// [google.spanner.admin.database.v1.DeleteBackupRequest]:
414  /// @googleapis_reference_link{google/spanner/admin/database/v1/backup.proto#L215}
415  ///
416  Status DeleteBackup(std::string const& name);
417 
418  ///
419  /// Lists completed and pending backups.
420  /// Backups returned are ordered by `create_time` in descending order,
421  /// starting from the most recent `create_time`.
422  ///
423  /// @param parent Required. The instance to list backups from. Values are of
424  /// the
425  /// form `projects/<project>/instances/<instance>`.
426  /// @return
427  /// @googleapis_link{google::spanner::admin::database::v1::Backup,google/spanner/admin/database/v1/backup.proto#L36}
428  ///
429  /// [google.spanner.admin.database.v1.ListBackupsRequest]:
430  /// @googleapis_reference_link{google/spanner/admin/database/v1/backup.proto#L228}
431  /// [google.spanner.admin.database.v1.Backup]:
432  /// @googleapis_reference_link{google/spanner/admin/database/v1/backup.proto#L36}
433  ///
434  StreamRange<google::spanner::admin::database::v1::Backup> ListBackups(
435  std::string const& parent);
436 
437  ///
438  /// Create a new database by restoring from a completed backup. The new
439  /// database must be in the same project and in an instance with the same
440  /// instance configuration as the instance containing
441  /// the backup. The returned database [long-running
442  /// operation][google.longrunning.Operation] has a name of the format
443  /// `projects/<project>/instances/<instance>/databases/<database>/operations/<operation_id>`,
444  /// and can be used to track the progress of the operation, and to cancel it.
445  /// The [metadata][google.longrunning.Operation.metadata] field type is
446  /// [RestoreDatabaseMetadata][google.spanner.admin.database.v1.RestoreDatabaseMetadata].
447  /// The [response][google.longrunning.Operation.response] type
448  /// is [Database][google.spanner.admin.database.v1.Database], if
449  /// successful. Cancelling the returned operation will stop the restore and
450  /// delete the database.
451  /// There can be only one database being restored into an instance at a time.
452  /// Once the restore operation completes, a new restore operation can be
453  /// initiated, without waiting for the optimize operation associated with the
454  /// first restore to complete.
455  ///
456  /// @param parent Required. The name of the instance in which to create the
457  /// restored database. This instance must be in the same project and
458  /// have the same instance configuration as the instance containing
459  /// the source backup. Values are of the form
460  /// `projects/<project>/instances/<instance>`.
461  /// @param database_id Required. The id of the database to create and restore
462  /// to. This
463  /// database must not already exist. The `database_id` appended to
464  /// `parent` forms the full database name of the form
465  /// `projects/<project>/instances/<instance>/databases/<database_id>`.
466  /// @param backup Name of the backup from which to restore. Values are of
467  /// the form
468  /// `projects/<project>/instances/<instance>/backups/<backup>`.
469  /// @return
470  /// @googleapis_link{google::spanner::admin::database::v1::Database,google/spanner/admin/database/v1/spanner_database_admin.proto#L326}
471  ///
472  /// [google.spanner.admin.database.v1.RestoreDatabaseRequest]:
473  /// @googleapis_reference_link{google/spanner/admin/database/v1/spanner_database_admin.proto#L692}
474  /// [google.spanner.admin.database.v1.Database]:
475  /// @googleapis_reference_link{google/spanner/admin/database/v1/spanner_database_admin.proto#L326}
476  ///
477  future<StatusOr<google::spanner::admin::database::v1::Database>>
478  RestoreDatabase(std::string const& parent, std::string const& database_id,
479  std::string const& backup);
480 
481  ///
482  /// Lists database [longrunning-operations][google.longrunning.Operation].
483  /// A database operation has a name of the form
484  /// `projects/<project>/instances/<instance>/databases/<database>/operations/<operation>`.
485  /// The long-running operation
486  /// [metadata][google.longrunning.Operation.metadata] field type
487  /// `metadata.type_url` describes the type of the metadata. Operations
488  /// returned include those that have completed/failed/canceled within the last
489  /// 7 days, and pending operations.
490  ///
491  /// @param parent Required. The instance of the database operations.
492  /// Values are of the form `projects/<project>/instances/<instance>`.
493  /// @return
494  /// @googleapis_link{google::longrunning::Operation,google/longrunning/operations.proto#L128}
495  ///
496  /// [google.spanner.admin.database.v1.ListDatabaseOperationsRequest]:
497  /// @googleapis_reference_link{google/spanner/admin/database/v1/spanner_database_admin.proto#L611}
498  /// [google.longrunning.Operation]:
499  /// @googleapis_reference_link{google/longrunning/operations.proto#L128}
500  ///
501  StreamRange<google::longrunning::Operation> ListDatabaseOperations(
502  std::string const& parent);
503 
504  ///
505  /// Lists the backup [long-running operations][google.longrunning.Operation]
506  /// in the given instance. A backup operation has a name of the form
507  /// `projects/<project>/instances/<instance>/backups/<backup>/operations/<operation>`.
508  /// The long-running operation
509  /// [metadata][google.longrunning.Operation.metadata] field type
510  /// `metadata.type_url` describes the type of the metadata. Operations
511  /// returned include those that have completed/failed/canceled within the last
512  /// 7 days, and pending operations. Operations returned are ordered by
513  /// `operation.metadata.value.progress.start_time` in descending order
514  /// starting from the most recently started operation.
515  ///
516  /// @param parent Required. The instance of the backup operations. Values are
517  /// of
518  /// the form `projects/<project>/instances/<instance>`.
519  /// @return
520  /// @googleapis_link{google::longrunning::Operation,google/longrunning/operations.proto#L128}
521  ///
522  /// [google.spanner.admin.database.v1.ListBackupOperationsRequest]:
523  /// @googleapis_reference_link{google/spanner/admin/database/v1/backup.proto#L300}
524  /// [google.longrunning.Operation]:
525  /// @googleapis_reference_link{google/longrunning/operations.proto#L128}
526  ///
527  StreamRange<google::longrunning::Operation> ListBackupOperations(
528  std::string const& parent);
529 
530  ///
531  /// Lists Cloud Spanner databases.
532  ///
533  /// @param request
534  /// @googleapis_link{google::spanner::admin::database::v1::ListDatabasesRequest,google/spanner/admin/database/v1/spanner_database_admin.proto#L413}
535  /// @return
536  /// @googleapis_link{google::spanner::admin::database::v1::Database,google/spanner/admin/database/v1/spanner_database_admin.proto#L326}
537  ///
538  /// [google.spanner.admin.database.v1.ListDatabasesRequest]:
539  /// @googleapis_reference_link{google/spanner/admin/database/v1/spanner_database_admin.proto#L413}
540  /// [google.spanner.admin.database.v1.Database]:
541  /// @googleapis_reference_link{google/spanner/admin/database/v1/spanner_database_admin.proto#L326}
542  ///
543  StreamRange<google::spanner::admin::database::v1::Database> ListDatabases(
544  google::spanner::admin::database::v1::ListDatabasesRequest request);
545 
546  ///
547  /// Creates a new Cloud Spanner database and starts to prepare it for serving.
548  /// The returned [long-running operation][google.longrunning.Operation] will
549  /// have a name of the format `<database_name>/operations/<operation_id>` and
550  /// can be used to track preparation of the database. The
551  /// [metadata][google.longrunning.Operation.metadata] field type is
552  /// [CreateDatabaseMetadata][google.spanner.admin.database.v1.CreateDatabaseMetadata].
553  /// The [response][google.longrunning.Operation.response] field type is
554  /// [Database][google.spanner.admin.database.v1.Database], if successful.
555  ///
556  /// @param request
557  /// @googleapis_link{google::spanner::admin::database::v1::CreateDatabaseRequest,google/spanner/admin/database/v1/spanner_database_admin.proto#L445}
558  /// @return
559  /// @googleapis_link{google::spanner::admin::database::v1::Database,google/spanner/admin/database/v1/spanner_database_admin.proto#L326}
560  ///
561  /// [google.spanner.admin.database.v1.CreateDatabaseRequest]:
562  /// @googleapis_reference_link{google/spanner/admin/database/v1/spanner_database_admin.proto#L445}
563  /// [google.spanner.admin.database.v1.Database]:
564  /// @googleapis_reference_link{google/spanner/admin/database/v1/spanner_database_admin.proto#L326}
565  ///
566  future<StatusOr<google::spanner::admin::database::v1::Database>>
568  google::spanner::admin::database::v1::CreateDatabaseRequest const&
569  request);
570 
571  ///
572  /// Gets the state of a Cloud Spanner database.
573  ///
574  /// @param request
575  /// @googleapis_link{google::spanner::admin::database::v1::GetDatabaseRequest,google/spanner/admin/database/v1/spanner_database_admin.proto#L484}
576  /// @return
577  /// @googleapis_link{google::spanner::admin::database::v1::Database,google/spanner/admin/database/v1/spanner_database_admin.proto#L326}
578  ///
579  /// [google.spanner.admin.database.v1.GetDatabaseRequest]:
580  /// @googleapis_reference_link{google/spanner/admin/database/v1/spanner_database_admin.proto#L484}
581  /// [google.spanner.admin.database.v1.Database]:
582  /// @googleapis_reference_link{google/spanner/admin/database/v1/spanner_database_admin.proto#L326}
583  ///
584  StatusOr<google::spanner::admin::database::v1::Database> GetDatabase(
585  google::spanner::admin::database::v1::GetDatabaseRequest const& request);
586 
587  ///
588  /// Updates the schema of a Cloud Spanner database by
589  /// creating/altering/dropping tables, columns, indexes, etc. The returned
590  /// [long-running operation][google.longrunning.Operation] will have a name of
591  /// the format `<database_name>/operations/<operation_id>` and can be used to
592  /// track execution of the schema change(s). The
593  /// [metadata][google.longrunning.Operation.metadata] field type is
594  /// [UpdateDatabaseDdlMetadata][google.spanner.admin.database.v1.UpdateDatabaseDdlMetadata].
595  /// The operation has no response.
596  ///
597  /// @param request
598  /// @googleapis_link{google::spanner::admin::database::v1::UpdateDatabaseDdlRequest,google/spanner/admin/database/v1/spanner_database_admin.proto#L511}
599  /// @return
600  /// @googleapis_link{google::spanner::admin::database::v1::UpdateDatabaseDdlMetadata,google/spanner/admin/database/v1/spanner_database_admin.proto#L547}
601  ///
602  /// [google.spanner.admin.database.v1.UpdateDatabaseDdlRequest]:
603  /// @googleapis_reference_link{google/spanner/admin/database/v1/spanner_database_admin.proto#L511}
604  /// [google.spanner.admin.database.v1.UpdateDatabaseDdlMetadata]:
605  /// @googleapis_reference_link{google/spanner/admin/database/v1/spanner_database_admin.proto#L547}
606  ///
607  future<
608  StatusOr<google::spanner::admin::database::v1::UpdateDatabaseDdlMetadata>>
610  google::spanner::admin::database::v1::UpdateDatabaseDdlRequest const&
611  request);
612 
613  ///
614  /// Drops (aka deletes) a Cloud Spanner database.
615  /// Completed backups for the database will be retained according to their
616  /// `expire_time`.
617  ///
618  /// @param request
619  /// @googleapis_link{google::spanner::admin::database::v1::DropDatabaseRequest,google/spanner/admin/database/v1/spanner_database_admin.proto#L579}
620  ///
621  /// [google.spanner.admin.database.v1.DropDatabaseRequest]:
622  /// @googleapis_reference_link{google/spanner/admin/database/v1/spanner_database_admin.proto#L579}
623  ///
625  google::spanner::admin::database::v1::DropDatabaseRequest const& request);
626 
627  ///
628  /// Returns the schema of a Cloud Spanner database as a list of formatted
629  /// DDL statements. This method does not show pending schema updates, those
630  /// may be queried using the [Operations][google.longrunning.Operations] API.
631  ///
632  /// @param request
633  /// @googleapis_link{google::spanner::admin::database::v1::GetDatabaseDdlRequest,google/spanner/admin/database/v1/spanner_database_admin.proto#L590}
634  /// @return
635  /// @googleapis_link{google::spanner::admin::database::v1::GetDatabaseDdlResponse,google/spanner/admin/database/v1/spanner_database_admin.proto#L603}
636  ///
637  /// [google.spanner.admin.database.v1.GetDatabaseDdlRequest]:
638  /// @googleapis_reference_link{google/spanner/admin/database/v1/spanner_database_admin.proto#L590}
639  /// [google.spanner.admin.database.v1.GetDatabaseDdlResponse]:
640  /// @googleapis_reference_link{google/spanner/admin/database/v1/spanner_database_admin.proto#L603}
641  ///
642  StatusOr<google::spanner::admin::database::v1::GetDatabaseDdlResponse>
644  google::spanner::admin::database::v1::GetDatabaseDdlRequest const&
645  request);
646 
647  ///
648  /// Sets the access control policy on a database or backup resource.
649  /// Replaces any existing policy.
650  ///
651  /// Authorization requires `spanner.databases.setIamPolicy`
652  /// permission on [resource][google.iam.v1.SetIamPolicyRequest.resource].
653  /// For backups, authorization requires `spanner.backups.setIamPolicy`
654  /// permission on [resource][google.iam.v1.SetIamPolicyRequest.resource].
655  ///
656  /// @param request
657  /// @googleapis_link{google::iam::v1::SetIamPolicyRequest,google/iam/v1/iam_policy.proto#L98}
658  /// @return
659  /// @googleapis_link{google::iam::v1::Policy,google/iam/v1/policy.proto#L88}
660  ///
661  /// [google.iam.v1.SetIamPolicyRequest]:
662  /// @googleapis_reference_link{google/iam/v1/iam_policy.proto#L98}
663  /// [google.iam.v1.Policy]:
664  /// @googleapis_reference_link{google/iam/v1/policy.proto#L88}
665  ///
666  StatusOr<google::iam::v1::Policy> SetIamPolicy(
667  google::iam::v1::SetIamPolicyRequest const& request);
668 
669  ///
670  /// Gets the access control policy for a database or backup resource.
671  /// Returns an empty policy if a database or backup exists but does not have a
672  /// policy set.
673  ///
674  /// Authorization requires `spanner.databases.getIamPolicy` permission on
675  /// [resource][google.iam.v1.GetIamPolicyRequest.resource].
676  /// For backups, authorization requires `spanner.backups.getIamPolicy`
677  /// permission on [resource][google.iam.v1.GetIamPolicyRequest.resource].
678  ///
679  /// @param request
680  /// @googleapis_link{google::iam::v1::GetIamPolicyRequest,google/iam/v1/iam_policy.proto#L113}
681  /// @return
682  /// @googleapis_link{google::iam::v1::Policy,google/iam/v1/policy.proto#L88}
683  ///
684  /// [google.iam.v1.GetIamPolicyRequest]:
685  /// @googleapis_reference_link{google/iam/v1/iam_policy.proto#L113}
686  /// [google.iam.v1.Policy]:
687  /// @googleapis_reference_link{google/iam/v1/policy.proto#L88}
688  ///
689  StatusOr<google::iam::v1::Policy> GetIamPolicy(
690  google::iam::v1::GetIamPolicyRequest const& request);
691 
692  ///
693  /// Returns permissions that the caller has on the specified database or
694  /// backup resource.
695  ///
696  /// Attempting this RPC on a non-existent Cloud Spanner database will
697  /// result in a NOT_FOUND error if the user has
698  /// `spanner.databases.list` permission on the containing Cloud
699  /// Spanner instance. Otherwise returns an empty set of permissions.
700  /// Calling this method on a backup that does not exist will
701  /// result in a NOT_FOUND error if the user has
702  /// `spanner.backups.list` permission on the containing instance.
703  ///
704  /// @param request
705  /// @googleapis_link{google::iam::v1::TestIamPermissionsRequest,google/iam/v1/iam_policy.proto#L126}
706  /// @return
707  /// @googleapis_link{google::iam::v1::TestIamPermissionsResponse,google/iam/v1/iam_policy.proto#L141}
708  ///
709  /// [google.iam.v1.TestIamPermissionsRequest]:
710  /// @googleapis_reference_link{google/iam/v1/iam_policy.proto#L126}
711  /// [google.iam.v1.TestIamPermissionsResponse]:
712  /// @googleapis_reference_link{google/iam/v1/iam_policy.proto#L141}
713  ///
714  StatusOr<google::iam::v1::TestIamPermissionsResponse> TestIamPermissions(
715  google::iam::v1::TestIamPermissionsRequest const& request);
716 
717  ///
718  /// Starts creating a new Cloud Spanner Backup.
719  /// The returned backup [long-running operation][google.longrunning.Operation]
720  /// will have a name of the format
721  /// `projects/<project>/instances/<instance>/backups/<backup>/operations/<operation_id>`
722  /// and can be used to track creation of the backup. The
723  /// [metadata][google.longrunning.Operation.metadata] field type is
724  /// [CreateBackupMetadata][google.spanner.admin.database.v1.CreateBackupMetadata].
725  /// The [response][google.longrunning.Operation.response] field type is
726  /// [Backup][google.spanner.admin.database.v1.Backup], if successful.
727  /// Cancelling the returned operation will stop the creation and delete the
728  /// backup. There can be only one pending backup creation per database. Backup
729  /// creation of different databases can run concurrently.
730  ///
731  /// @param request
732  /// @googleapis_link{google::spanner::admin::database::v1::CreateBackupRequest,google/spanner/admin/database/v1/backup.proto#L123}
733  /// @return
734  /// @googleapis_link{google::spanner::admin::database::v1::Backup,google/spanner/admin/database/v1/backup.proto#L36}
735  ///
736  /// [google.spanner.admin.database.v1.CreateBackupRequest]:
737  /// @googleapis_reference_link{google/spanner/admin/database/v1/backup.proto#L123}
738  /// [google.spanner.admin.database.v1.Backup]:
739  /// @googleapis_reference_link{google/spanner/admin/database/v1/backup.proto#L36}
740  ///
741  future<StatusOr<google::spanner::admin::database::v1::Backup>> CreateBackup(
742  google::spanner::admin::database::v1::CreateBackupRequest const& request);
743 
744  ///
745  /// Gets metadata on a pending or completed
746  /// [Backup][google.spanner.admin.database.v1.Backup].
747  ///
748  /// @param request
749  /// @googleapis_link{google::spanner::admin::database::v1::GetBackupRequest,google/spanner/admin/database/v1/backup.proto#L202}
750  /// @return
751  /// @googleapis_link{google::spanner::admin::database::v1::Backup,google/spanner/admin/database/v1/backup.proto#L36}
752  ///
753  /// [google.spanner.admin.database.v1.GetBackupRequest]:
754  /// @googleapis_reference_link{google/spanner/admin/database/v1/backup.proto#L202}
755  /// [google.spanner.admin.database.v1.Backup]:
756  /// @googleapis_reference_link{google/spanner/admin/database/v1/backup.proto#L36}
757  ///
758  StatusOr<google::spanner::admin::database::v1::Backup> GetBackup(
759  google::spanner::admin::database::v1::GetBackupRequest const& request);
760 
761  ///
762  /// Updates a pending or completed
763  /// [Backup][google.spanner.admin.database.v1.Backup].
764  ///
765  /// @param request
766  /// @googleapis_link{google::spanner::admin::database::v1::UpdateBackupRequest,google/spanner/admin/database/v1/backup.proto#L186}
767  /// @return
768  /// @googleapis_link{google::spanner::admin::database::v1::Backup,google/spanner/admin/database/v1/backup.proto#L36}
769  ///
770  /// [google.spanner.admin.database.v1.UpdateBackupRequest]:
771  /// @googleapis_reference_link{google/spanner/admin/database/v1/backup.proto#L186}
772  /// [google.spanner.admin.database.v1.Backup]:
773  /// @googleapis_reference_link{google/spanner/admin/database/v1/backup.proto#L36}
774  ///
775  StatusOr<google::spanner::admin::database::v1::Backup> UpdateBackup(
776  google::spanner::admin::database::v1::UpdateBackupRequest const& request);
777 
778  ///
779  /// Deletes a pending or completed
780  /// [Backup][google.spanner.admin.database.v1.Backup].
781  ///
782  /// @param request
783  /// @googleapis_link{google::spanner::admin::database::v1::DeleteBackupRequest,google/spanner/admin/database/v1/backup.proto#L215}
784  ///
785  /// [google.spanner.admin.database.v1.DeleteBackupRequest]:
786  /// @googleapis_reference_link{google/spanner/admin/database/v1/backup.proto#L215}
787  ///
789  google::spanner::admin::database::v1::DeleteBackupRequest const& request);
790 
791  ///
792  /// Lists completed and pending backups.
793  /// Backups returned are ordered by `create_time` in descending order,
794  /// starting from the most recent `create_time`.
795  ///
796  /// @param request
797  /// @googleapis_link{google::spanner::admin::database::v1::ListBackupsRequest,google/spanner/admin/database/v1/backup.proto#L228}
798  /// @return
799  /// @googleapis_link{google::spanner::admin::database::v1::Backup,google/spanner/admin/database/v1/backup.proto#L36}
800  ///
801  /// [google.spanner.admin.database.v1.ListBackupsRequest]:
802  /// @googleapis_reference_link{google/spanner/admin/database/v1/backup.proto#L228}
803  /// [google.spanner.admin.database.v1.Backup]:
804  /// @googleapis_reference_link{google/spanner/admin/database/v1/backup.proto#L36}
805  ///
806  StreamRange<google::spanner::admin::database::v1::Backup> ListBackups(
807  google::spanner::admin::database::v1::ListBackupsRequest request);
808 
809  ///
810  /// Create a new database by restoring from a completed backup. The new
811  /// database must be in the same project and in an instance with the same
812  /// instance configuration as the instance containing
813  /// the backup. The returned database [long-running
814  /// operation][google.longrunning.Operation] has a name of the format
815  /// `projects/<project>/instances/<instance>/databases/<database>/operations/<operation_id>`,
816  /// and can be used to track the progress of the operation, and to cancel it.
817  /// The [metadata][google.longrunning.Operation.metadata] field type is
818  /// [RestoreDatabaseMetadata][google.spanner.admin.database.v1.RestoreDatabaseMetadata].
819  /// The [response][google.longrunning.Operation.response] type
820  /// is [Database][google.spanner.admin.database.v1.Database], if
821  /// successful. Cancelling the returned operation will stop the restore and
822  /// delete the database.
823  /// There can be only one database being restored into an instance at a time.
824  /// Once the restore operation completes, a new restore operation can be
825  /// initiated, without waiting for the optimize operation associated with the
826  /// first restore to complete.
827  ///
828  /// @param request
829  /// @googleapis_link{google::spanner::admin::database::v1::RestoreDatabaseRequest,google/spanner/admin/database/v1/spanner_database_admin.proto#L692}
830  /// @return
831  /// @googleapis_link{google::spanner::admin::database::v1::Database,google/spanner/admin/database/v1/spanner_database_admin.proto#L326}
832  ///
833  /// [google.spanner.admin.database.v1.RestoreDatabaseRequest]:
834  /// @googleapis_reference_link{google/spanner/admin/database/v1/spanner_database_admin.proto#L692}
835  /// [google.spanner.admin.database.v1.Database]:
836  /// @googleapis_reference_link{google/spanner/admin/database/v1/spanner_database_admin.proto#L326}
837  ///
838  future<StatusOr<google::spanner::admin::database::v1::Database>>
840  google::spanner::admin::database::v1::RestoreDatabaseRequest const&
841  request);
842 
843  ///
844  /// Lists database [longrunning-operations][google.longrunning.Operation].
845  /// A database operation has a name of the form
846  /// `projects/<project>/instances/<instance>/databases/<database>/operations/<operation>`.
847  /// The long-running operation
848  /// [metadata][google.longrunning.Operation.metadata] field type
849  /// `metadata.type_url` describes the type of the metadata. Operations
850  /// returned include those that have completed/failed/canceled within the last
851  /// 7 days, and pending operations.
852  ///
853  /// @param request
854  /// @googleapis_link{google::spanner::admin::database::v1::ListDatabaseOperationsRequest,google/spanner/admin/database/v1/spanner_database_admin.proto#L611}
855  /// @return
856  /// @googleapis_link{google::longrunning::Operation,google/longrunning/operations.proto#L128}
857  ///
858  /// [google.spanner.admin.database.v1.ListDatabaseOperationsRequest]:
859  /// @googleapis_reference_link{google/spanner/admin/database/v1/spanner_database_admin.proto#L611}
860  /// [google.longrunning.Operation]:
861  /// @googleapis_reference_link{google/longrunning/operations.proto#L128}
862  ///
863  StreamRange<google::longrunning::Operation> ListDatabaseOperations(
864  google::spanner::admin::database::v1::ListDatabaseOperationsRequest
865  request);
866 
867  ///
868  /// Lists the backup [long-running operations][google.longrunning.Operation]
869  /// in the given instance. A backup operation has a name of the form
870  /// `projects/<project>/instances/<instance>/backups/<backup>/operations/<operation>`.
871  /// The long-running operation
872  /// [metadata][google.longrunning.Operation.metadata] field type
873  /// `metadata.type_url` describes the type of the metadata. Operations
874  /// returned include those that have completed/failed/canceled within the last
875  /// 7 days, and pending operations. Operations returned are ordered by
876  /// `operation.metadata.value.progress.start_time` in descending order
877  /// starting from the most recently started operation.
878  ///
879  /// @param request
880  /// @googleapis_link{google::spanner::admin::database::v1::ListBackupOperationsRequest,google/spanner/admin/database/v1/backup.proto#L300}
881  /// @return
882  /// @googleapis_link{google::longrunning::Operation,google/longrunning/operations.proto#L128}
883  ///
884  /// [google.spanner.admin.database.v1.ListBackupOperationsRequest]:
885  /// @googleapis_reference_link{google/spanner/admin/database/v1/backup.proto#L300}
886  /// [google.longrunning.Operation]:
887  /// @googleapis_reference_link{google/longrunning/operations.proto#L128}
888  ///
889  StreamRange<google::longrunning::Operation> ListBackupOperations(
890  google::spanner::admin::database::v1::ListBackupOperationsRequest
891  request);
892 
893  private:
894  std::shared_ptr<DatabaseAdminConnection> connection_;
895 };
896 
898 namespace gcpcxxV1 = GOOGLE_CLOUD_CPP_NS; // NOLINT(misc-unused-alias-decls)
899 } // namespace spanner_admin
900 } // namespace cloud
901 } // namespace google
902 
903 #endif // GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_SPANNER_ADMIN_DATABASE_ADMIN_CLIENT_H