Google Cloud Spanner C++ Client  1.32.0
A C++ Client Library for Google Cloud Spanner
database_admin_client.h
Go to the documentation of this file.
1 // Copyright 2019 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 #ifndef GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_SPANNER_DATABASE_ADMIN_CLIENT_H
16 #define GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_SPANNER_DATABASE_ADMIN_CLIENT_H
17 
18 #include "google/cloud/spanner/backup.h"
19 #include "google/cloud/spanner/connection_options.h"
20 #include "google/cloud/spanner/database.h"
21 #include "google/cloud/spanner/database_admin_connection.h"
22 #include "google/cloud/spanner/encryption_config.h"
23 #include "google/cloud/spanner/iam_updater.h"
24 #include "google/cloud/spanner/instance.h"
25 #include "google/cloud/spanner/timestamp.h"
26 #include "google/cloud/spanner/version.h"
27 #include "google/cloud/future.h"
28 #include "google/cloud/status_or.h"
29 #include "absl/types/optional.h"
30 #include <chrono>
31 #include <string>
32 #include <vector>
33 
34 namespace google {
35 namespace cloud {
36 namespace spanner {
37 inline namespace SPANNER_CLIENT_NS {
38 
39 /**
40  * Performs database administration operations on Spanner.
41  *
42  * Applications use this class to perform administrative operations on spanner
43  * [Databases][database-doc-link].
44  *
45  * @par Performance
46  *
47  * Creating a new `DatabaseAdminClient` is a relatively expensive operation, new
48  * objects establish new connections to the service. In contrast, copying or
49  * moving an existing `DatabaseAdminClient` object is a relatively cheap
50  * operation. Copied clients share the underlying resources.
51  *
52  * @par Thread Safety
53  *
54  * Instances of this class created via copy-construction or copy-assignment
55  * share the underlying pool of connections. Access to these copies via multiple
56  * threads is guaranteed to work. Two threads operating on the same instance of
57  * this class is not guaranteed to work.
58  *
59  * @par Error Handling
60  *
61  * This class uses `StatusOr<T>` to report errors. When an operation fails to
62  * perform its work the returned `StatusOr<T>` contains the error details. If
63  * the `ok()` member function in the `StatusOr<T>` returns `true` then it
64  * contains the expected result. Please consult the
65  * [`StatusOr<T>` documentation](#google::cloud::v0::StatusOr) for more details.
66  *
67  * @code
68  * namespace spanner = ::google::cloud::spanner;
69  * using ::google::cloud::StatusOr;
70  * spanner::DatabaseAdminClient client = ...;
71  * StatusOr<google::spanner::admin::database::v1::Database> db =
72  * client.CreateDatabase(...).get();
73  *
74  * if (!db) {
75  * std::cerr << "Error in CreateDatabase: " << db.status() << "\n";
76  * return;
77  * }
78  *
79  * // Use `db` as a smart pointer here, e.g.:
80  * std::cout << "The database fully qualified name is: " << db->name() << "\n";
81  * @endcode
82  *
83  * @par Long running operations
84  *
85  * Some operations in this class can take minutes to complete. In this case the
86  * class returns a `google::cloud::future<StatusOr<T>>`, the application can
87  * then poll the `future` or associate a callback to be invoked when the
88  * operation completes:
89  *
90  * @code
91  * namespace spanner = ::google::cloud::spanner;
92  * spanner::DatabaseAdminClient client = ...;
93  * // Make example less verbose.
94  * using ::google::cloud::future;
95  * using ::google::cloud::StatusOr;
96  * using std::chrono::chrono_literals; // C++14
97  *
98  * auto database = client.CreateDatabase(...);
99  * if (database.wait_for(5m) == std::future_state::ready) {
100  * std::cout << "Database created in under 5 minutes, yay!\n";
101  * return;
102  * }
103  * // Too slow, setup a callback instead:
104  * database.then([](auto f) {
105  * StatusOr<google::spanner::admin::database::v1::Database> db = f.get();
106  * if (!db) {
107  * std::cout << "Failed creating a database!\n";
108  * return;
109  * }
110  * std::cout << "Database created!\n";
111  * });
112  * @endcode
113  *
114  * [database-doc-link]:
115  * https://cloud.google.com/spanner/docs/schema-and-data-model
116  */
119  public:
120  explicit DatabaseAdminClient(
121  ConnectionOptions const& options = ConnectionOptions());
122 
123  /**
124  * Creates a new Cloud Spanner database in the given project and instance.
125  *
126  * This function creates a database (using the "CREATE DATABASE" DDL
127  * statement) in the given Google Cloud Project and Cloud Spanner instance.
128  * The application can provide an optional list of additional DDL statements
129  * to atomically create tables and indices as well as the new database.
130  *
131  * Note that the database id must be between 2 and 30 characters long, it must
132  * start with a lowercase letter (`[a-z]`), it must end with a lowercase
133  * letter or a number (`[a-z0-9]`) and any characters between the beginning
134  * and ending characters must be lower case letters, numbers, underscore (`_`)
135  * or dashes (`-`), that is, they must belong to the `[a-z0-9_-]` character
136  * set.
137  *
138  * @p encryption_config How to encrypt the database.
139  *
140  * @return A `google::cloud::future` that becomes satisfied when the operation
141  * completes on the service. Note that this can take minutes in some cases.
142  *
143  * @par Example
144  * @snippet samples.cc create-database
145  *
146  * @see https://cloud.google.com/spanner/docs/data-definition-language for a
147  * full list of the DDL operations
148  *
149  * @see
150  * https://cloud.google.com/spanner/docs/data-definition-language#create_database
151  * for the regular expression that must be satisfied by the database id.
152  */
153  future<StatusOr<google::spanner::admin::database::v1::Database>>
154  CreateDatabase(Database db, std::vector<std::string> extra_statements = {},
155  EncryptionConfig encryption_config = DefaultEncryption());
156 
157  /**
158  * Retrieve metadata information about a database.
159  *
160  * @par Idempotency
161  * This is a read-only operation and therefore always idempotent. Transient
162  * failures are automatically retried.
163  *
164  * @par Example
165  * @snippet samples.cc get-database
166  */
167  StatusOr<google::spanner::admin::database::v1::Database> GetDatabase(
168  Database db);
169 
170  /**
171  * Retrieve a database schema.
172  *
173  * @par Idempotency
174  * This is a read-only operation and therefore always idempotent. Transient
175  * failures are automatically retried.
176  *
177  * @par Example
178  * @snippet samples.cc get-database-ddl
179  */
180  StatusOr<google::spanner::admin::database::v1::GetDatabaseDdlResponse>
182 
183  /**
184  * Updates the database using a series of DDL statements.
185  *
186  * This function schedules a series of updates to the database using a
187  * sequence of DDL statements.
188  *
189  * @return A `google::cloud::future` that becomes satisfied when all the
190  * statements complete. Note that Cloud Spanner may fail to execute some of
191  * the statements.
192  *
193  * @par Example
194  * @snippet samples.cc update-database
195  *
196  * @see https://cloud.google.com/spanner/docs/data-definition-language for a
197  * full list of the DDL operations
198  */
199  future<
200  StatusOr<google::spanner::admin::database::v1::UpdateDatabaseDdlMetadata>>
201  UpdateDatabase(Database db, std::vector<std::string> statements);
202 
203  /**
204  * Drops (deletes) an existing Cloud Spanner database.
205  *
206  * @warning Dropping a database deletes all the tables and other data in the
207  * database. This is an unrecoverable operation.
208  *
209  * @par Example
210  * @snippet samples.cc drop-database
211  */
213 
214  /**
215  * List all the databases in a give project and instance.
216  *
217  * @par Idempotency
218  * This operation is read-only and therefore always idempotent.
219  *
220  * @par Example
221  * @snippet samples.cc list-databases
222  */
223  ListDatabaseRange ListDatabases(Instance in);
224 
225  /**
226  * Create a new database by restoring from a completed backup.
227  *
228  * @par Idempotency
229  * This is not an idempotent operation. Transient failures are not retried.
230  *
231  * The new database must be in the same project and in an instance with the
232  * same instance configuration as the instance containing the backup.
233  *
234  * @p encryption_config How to encrypt the database.
235  *
236  * @return A `google::cloud::future` that becomes satisfied when the operation
237  * completes on the service. Note that this can take minutes in some cases.
238  *
239  * @par Example
240  * @snippet samples.cc restore-database
241  */
242  future<StatusOr<google::spanner::admin::database::v1::Database>>
243  RestoreDatabase(Database db, Backup const& backup,
244  EncryptionConfig encryption_config = DefaultEncryption());
245 
246  /**
247  * Create a new database by restoring from a completed backup.
248  *
249  * @par Idempotency
250  * This is not an idempotent operation. Transient failures are not retried.
251  *
252  * The new database must be in the same project and in an instance with the
253  * same instance configuration as the instance containing the backup.
254  *
255  * @p encryption_config How to encrypt the database.
256  *
257  * @return A `google::cloud::future` that becomes satisfied when the operation
258  * completes on the service. Note that this can take minutes in some cases.
259  */
260  future<StatusOr<google::spanner::admin::database::v1::Database>>
262  google::spanner::admin::database::v1::Backup const& backup,
263  EncryptionConfig encryption_config = DefaultEncryption());
264 
265  /**
266  * Gets the IAM policy for a database.
267  *
268  * @par Idempotency
269  * This operation is read-only and therefore always idempotent.
270  *
271  * @par Example
272  * @snippet samples.cc database-get-iam-policy
273  */
274  StatusOr<google::iam::v1::Policy> GetIamPolicy(Database db);
275 
276  /**
277  * Set the IAM policy for the given database.
278  *
279  * This function changes the IAM policy configured in the given database to
280  * the value of @p policy.
281  *
282  * @par Idempotency
283  * This function is only idempotent if the `etag` field in @p policy is set.
284  * Therefore, the underlying RPCs are only retried if the field is set, and
285  * the function returns the first RPC error in any other case.
286  *
287  * @see The [Cloud Spanner
288  * documentation](https://cloud.google.com/spanner/docs/iam) for a
289  * description of the roles and permissions supported by Cloud Spanner.
290  * @see [IAM Overview](https://cloud.google.com/iam/docs/overview#permissions)
291  * for an introduction to Identity and Access Management in Google Cloud
292  * Platform.
293  */
294  StatusOr<google::iam::v1::Policy> SetIamPolicy(
295  Database db, google::iam::v1::Policy policy);
296 
297  /**
298  * Updates the IAM policy for an instance using an optimistic concurrency
299  * control loop.
300  *
301  * This function repeatedly reads the current IAM policy in @p db, and then
302  * calls the @p updater with the this policy. The @p updater returns an empty
303  * optional if no changes are required, or it returns the new desired value
304  * for the IAM policy. This function then updates the policy.
305  *
306  * Updating an IAM policy can fail with retryable errors or can be aborted
307  * because there were simultaneous changes the to IAM policy. In these cases
308  * this function reruns the loop until it succeeds.
309  *
310  * The function returns the final IAM policy, or an error if the rerun policy
311  * for the underlying connection has expired.
312  *
313  * @par Idempotency
314  * This function always sets the `etag` field on the policy, so the underlying
315  * RPCs are retried automatically.
316  *
317  * @par Example
318  * @snippet samples.cc add-database-reader-on-database
319  *
320  * @param db the identifier for the database where you want to change the IAM
321  * policy.
322  * @param updater a callback to modify the policy. Return an unset optional
323  * to indicate that no changes to the policy are needed.
324  */
325  StatusOr<google::iam::v1::Policy> SetIamPolicy(Database const& db,
326  IamUpdater const& updater);
327 
328  /**
329  * @copydoc SetIamPolicy(Database const&,IamUpdater const&)
330  *
331  * @param rerun_policy controls for how long (or how many times) the updater
332  * will be rerun after the IAM policy update aborts.
333  * @param backoff_policy controls how long `SetIamPolicy` waits between
334  * reruns.
335  */
336  StatusOr<google::iam::v1::Policy> SetIamPolicy(
337  Database const& db, IamUpdater const& updater,
338  std::unique_ptr<TransactionRerunPolicy> rerun_policy,
339  std::unique_ptr<BackoffPolicy> backoff_policy);
340 
341  /**
342  * Get the subset of the permissions the caller has on the given database.
343  *
344  * This function compares the given list of permissions against those
345  * permissions granted to the caller, and returns the subset of the list that
346  * the caller actually holds.
347  *
348  * @note Permission wildcards, such as `spanner.*` are not allowed.
349  *
350  * @par Idempotency
351  * This operation is read-only and therefore always idempotent.
352  *
353  * @par Example
354  * @snippet samples.cc database-test-iam-permissions
355  *
356  * @see The [Cloud Spanner
357  * documentation](https://cloud.google.com/spanner/docs/iam) for a description
358  * of the roles and permissions supported by Cloud Spanner.
359  * @see [IAM Overview](https://cloud.google.com/iam/docs/overview#permissions)
360  * for an introduction to Identity and Access Management in Google Cloud
361  * Platform.
362  */
363  StatusOr<google::iam::v1::TestIamPermissionsResponse> TestIamPermissions(
364  Database db, std::vector<std::string> permissions);
365 
366  /**
367  * Creates a new Cloud Spanner backup for the given database.
368  *
369  * @par Idempotency
370  * This is not an idempotent operation. Transient failures are not retried.
371  *
372  * This function creates a database backup for the given Google Cloud Spanner
373  * database.
374  *
375  * Note that the @p backup_id must be unique within the same instance, it must
376  * be between 2 and 60 characters long, it must start with a lowercase letter
377  * (`[a-z]`), it must end with a lowercase letter or a number (`[a-z0-9]`) and
378  * any characters between the beginning and ending characters must be lower
379  * case letters, numbers, underscore (`_`) or dashes (`-`), that is, they must
380  * belong to the `[a-z0-9_-]` character set.
381  *
382  * The @p expire_time must be at least 6 hours and at most 366 days from the
383  * time the `CreateBackup()` request is processed.
384  *
385  * The backup will contain an externally consistent copy of the database
386  * at @p version_time, if set. Otherwise, the version_time will be the
387  * create_time of the backup.
388  *
389  * @p encryption_config How to encrypt the backup.
390  *
391  * @return A `google::cloud::future` that becomes satisfied when the operation
392  * completes on the service. Note that this can take minutes in some cases.
393  *
394  * @par Example
395  * @snippet samples.cc create-backup
396  */
397  future<StatusOr<google::spanner::admin::database::v1::Backup>> CreateBackup(
398  Database db, std::string backup_id, Timestamp expire_time,
399  absl::optional<Timestamp> version_time = absl::nullopt,
400  EncryptionConfig encryption_config = DefaultEncryption());
401 
402  /**
403  * Creates a new Cloud Spanner backup for the given database.
404  *
405  * @deprecated this overload is deprecated; use the `Timestamp` overload
406  * instead.
407  *
408  * @par Idempotency
409  * This is not an idempotent operation. Transient failures are not retried.
410  *
411  * This function creates a database backup for the given Google Cloud Spanner
412  * database.
413  *
414  * Note that the @p backup_id must be unique within the same instance, it must
415  * be between 2 and 60 characters long, it must start with a lowercase letter
416  * (`[a-z]`), it must end with a lowercase letter or a number (`[a-z0-9]`) and
417  * any characters between the beginning and ending characters must be lower
418  * case letters, numbers, underscore (`_`) or dashes (`-`), that is, they must
419  * belong to the `[a-z0-9_-]` character set.
420  *
421  * The @p expire_time must be at least 6 hours and at most 366 days from the
422  * time the `CreateBackup()` request is processed.
423  *
424  * @return A `google::cloud::future` that becomes satisfied when the operation
425  * completes on the service. Note that this can take minutes in some cases.
426  */
427  future<StatusOr<google::spanner::admin::database::v1::Backup>> CreateBackup(
428  Database db, std::string backup_id,
429  std::chrono::system_clock::time_point expire_time);
430 
431  /**
432  * Retrieve metadata information about a Backup.
433  *
434  * @par Idempotency
435  * This is a read-only operation and therefore always idempotent. Transient
436  * failures are automatically retried.
437  *
438  * @par Example
439  * @snippet samples.cc get-backup
440  */
441  StatusOr<google::spanner::admin::database::v1::Backup> GetBackup(
442  Backup const& backup);
443 
444  /**
445  * Deletes a pending or completed Backup.
446  *
447  * @par Idempotency
448  * We treat this operation as idempotent. Transient failures are automatically
449  * retried.
450  */
452  google::spanner::admin::database::v1::Backup const& backup);
453 
454  /**
455  * Deletes a pending or completed Backup.
456  *
457  * @par Idempotency
458  * We treat this operation as idempotent. Transient failures are automatically
459  * retried.
460  *
461  * @par Example
462  * @snippet samples.cc delete-backup
463  */
464  Status DeleteBackup(Backup const& backup);
465 
466  /**
467  * List all the backups in a given project and instance that match
468  * the filter.
469  *
470  * @par Idempotency
471  * This operation is read-only and therefore always idempotent.
472  *
473  * @param in An instance where the backup operations belong to.
474  * @param filter A filter expression that filters backups listed in the
475  * response. See [this documentation][spanner-api-reference-link] for the
476  * syntax of the filter expression.
477  *
478  * @par Example
479  * @snippet samples.cc list-backups
480  *
481  * [spanner-api-reference-link]:
482  * https://cloud.google.com/spanner/docs/reference/rpc/google.spanner.admin.database.v1#google.spanner.admin.database.v1.ListBackupsRequest
483  */
484  ListBackupsRange ListBackups(Instance in, std::string filter = {});
485 
486  /**
487  * Update backup's @p expire_time.
488  *
489  * @par Idempotency
490  * This operation is idempotent as its result does not depend on the previous
491  * state of the backup. Note that, as is the case with all operations, it is
492  * subject to race conditions if multiple tasks are attempting to change the
493  * expire time in the same backup.
494  */
495  StatusOr<google::spanner::admin::database::v1::Backup> UpdateBackupExpireTime(
496  google::spanner::admin::database::v1::Backup const& backup,
497  Timestamp expire_time);
498 
499  /**
500  * Update backup's @p expire_time.
501  *
502  * @par Idempotency
503  * This operation is idempotent as its result does not depend on the previous
504  * state of the backup. Note that, as is the case with all operations, it is
505  * subject to race conditions if multiple tasks are attempting to change the
506  * expire time in the same backup.
507  *
508  * @par Example
509  * @snippet samples.cc update-backup
510  */
511  StatusOr<google::spanner::admin::database::v1::Backup> UpdateBackupExpireTime(
512  Backup const& backup, Timestamp expire_time);
513 
514  /**
515  * Update backup's @p expire_time.
516  *
517  * @deprecated this overload is deprecated; use the `Timestamp` overload
518  * instead.
519  *
520  * @par Idempotency
521  * This operation is idempotent as its result does not depend on the previous
522  * state of the backup. Note that, as is the case with all operations, it is
523  * subject to race conditions if multiple tasks are attempting to change the
524  * expire time in the same backup.
525  */
526  StatusOr<google::spanner::admin::database::v1::Backup> UpdateBackupExpireTime(
527  google::spanner::admin::database::v1::Backup const& backup,
528  std::chrono::system_clock::time_point const& expire_time);
529 
530  /**
531  * Update backup's @p expire_time.
532  *
533  * @deprecated this overload is deprecated; use the `Timestamp` overload
534  * instead.
535  *
536  * @par Idempotency
537  * This operation is idempotent as its result does not depend on the previous
538  * state of the backup. Note that, as is the case with all operations, it is
539  * subject to race conditions if multiple tasks are attempting to change the
540  * expire time in the same backup.
541  */
542  StatusOr<google::spanner::admin::database::v1::Backup> UpdateBackupExpireTime(
543  Backup const& backup,
544  std::chrono::system_clock::time_point const& expire_time);
545 
546  /**
547  * List all the backup operations in a given project and instance that match
548  * the filter.
549  *
550  * @par Idempotency
551  * This operation is read-only and therefore always idempotent.
552  *
553  * @param in An instance where the backup operations belong to.
554  * @param filter A filter expression that filters what operations are returned
555  * in the response. See [this documentation][spanner-api-reference-link] for
556  * the syntax of the filter expression.
557  *
558  * @par Example
559  * @snippet samples.cc list-backup-operations
560  *
561  * [spanner-api-reference-link]:
562  * https://cloud.google.com/spanner/docs/reference/rpc/google.spanner.admin.database.v1#google.spanner.admin.database.v1.ListBackupOperationsRequest
563  */
564  ListBackupOperationsRange ListBackupOperations(Instance in,
565  std::string filter = {});
566 
567  /**
568  * List all the database operations in a given project and instance that match
569  * the filter.
570  *
571  * @par Idempotency
572  * This operation is read-only and therefore always idempotent.
573  *
574  * @param in An instance where the database operations belong to.
575  * @param filter A filter expression that filters what operations are returned
576  * in the response. See [this documentation][spanner-api-reference-link] for
577  * the syntax of the filter expression.
578  *
579  * @par Example
580  * @snippet samples.cc list-database-operations
581  *
582  * [spanner-api-reference-link]:
583  * https://cloud.google.com/spanner/docs/reference/rpc/google.spanner.admin.database.v1#google.spanner.admin.database.v1.ListDatabaseOperationsRequest
584  */
585  ListDatabaseOperationsRange ListDatabaseOperations(Instance in,
586  std::string filter = {});
587 
588  /// Create a new client with the given stub. For testing only.
589  explicit DatabaseAdminClient(std::shared_ptr<DatabaseAdminConnection> c)
590  : conn_(std::move(c)) {}
591 
592  private:
593  std::shared_ptr<DatabaseAdminConnection> conn_;
594 };
595 
596 } // namespace SPANNER_CLIENT_NS
597 } // namespace spanner
598 } // namespace cloud
599 } // namespace google
600 
601 #endif // GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_SPANNER_DATABASE_ADMIN_CLIENT_H