Google Cloud Spanner C++ Client  1.34.0
A C++ Client Library for Google Cloud Spanner
database_admin_connection.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_CONNECTION_H
16 #define GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_SPANNER_DATABASE_ADMIN_CONNECTION_H
17 
18 #include "google/cloud/spanner/backoff_policy.h"
19 #include "google/cloud/spanner/backup.h"
20 #include "google/cloud/spanner/database.h"
21 #include "google/cloud/spanner/encryption_config.h"
22 #include "google/cloud/spanner/instance.h"
23 #include "google/cloud/spanner/internal/database_admin_stub.h"
24 #include "google/cloud/spanner/polling_policy.h"
25 #include "google/cloud/spanner/retry_policy.h"
26 #include "google/cloud/spanner/timestamp.h"
27 #include "google/cloud/spanner/version.h"
28 #include "google/cloud/backoff_policy.h"
29 #include "google/cloud/internal/pagination_range.h"
30 #include "absl/types/optional.h"
31 #include <google/spanner/admin/database/v1/spanner_database_admin.pb.h>
32 #include <chrono>
33 #include <string>
34 #include <vector>
35 
36 namespace google {
37 namespace cloud {
38 namespace spanner {
40 
41 /**
42  * An input range to stream all the databases in a Cloud Spanner instance.
43  *
44  * This type models an [input range][cppref-input-range] of
45  * `google::spanner::admin::v1::Database` objects. Applications can make a
46  * single pass through the results.
47  *
48  * [cppref-input-range]: https://en.cppreference.com/w/cpp/ranges/input_range
49  */
50 using ListDatabaseRange = ::google::cloud::internal::PaginationRange<
51  google::spanner::admin::database::v1::Database>;
52 
53 /**
54  * An input range to stream backup operations in Cloud Spanner instance.
55  *
56  * This type models an [input range][cppref-input-range] of
57  * `google::longrunning::Operation` objects. Applications can make a
58  * single pass through the results.
59  *
60  * [cppref-input-range]: https://en.cppreference.com/w/cpp/ranges/input_range
61  */
62 using ListBackupOperationsRange =
63  google::cloud::internal::PaginationRange<google::longrunning::Operation>;
64 
65 /**
66  * An input range to stream database operations in Cloud Spanner instance.
67  *
68  * This type models an [input range][cppref-input-range] of
69  * `google::longrunning::Operation` objects. Applications can make a
70  * single pass through the results.
71  *
72  * [cppref-input-range]: https://en.cppreference.com/w/cpp/ranges/input_range
73  */
74 using ListDatabaseOperationsRange =
75  google::cloud::internal::PaginationRange<google::longrunning::Operation>;
76 
77 /**
78  * An input range to stream backups in Cloud Spanner instance.
79  *
80  * This type models an [input range][cppref-input-range] of
81  * `google::longrunning::Operation` objects. Applications can make a
82  * single pass through the results.
83  *
84  * [cppref-input-range]: https://en.cppreference.com/w/cpp/ranges/input_range
85  */
86 using ListBackupsRange = ::google::cloud::internal::PaginationRange<
87  google::spanner::admin::database::v1::Backup>;
88 
89 /**
90  * A connection to the Cloud Spanner instance administration service.
91  *
92  * This interface defines pure-virtual methods for each of the user-facing
93  * overload sets in `DatabaseAdminClient`. This allows users to inject custom
94  * behavior (e.g., with a Google Mock object) in a `DatabaseAdminClient` object
95  * for use in their own tests.
96  *
97  * To create a concrete instance that connects you to a real Cloud Spanner
98  * instance administration service, see `MakeDatabaseAdminConnection()`.
99  */
100 class GOOGLE_CLOUD_CPP_SPANNER_ADMIN_API_DEPRECATED("DatabaseAdminConnection")
102  public:
103  virtual ~DatabaseAdminConnection() = 0;
104 
105  //@{
106  /**
107  * @name Define the arguments for each member function.
108  *
109  * Applications may define classes derived from `DatabaseAdminConnection`, for
110  * example, because they want to mock the class. To avoid breaking all such
111  * derived classes when we change the number or type of the arguments to the
112  * member functions we define light weight structures to pass the arguments.
113  */
114  /// Wrap the arguments for `CreateDatabase()`.
116  /// The name of the database.
118  /// Any additional statements to execute after creating the database.
119  std::vector<std::string> extra_statements;
120  /// How to encrypt the database.
121  EncryptionConfig encryption_config;
122  };
123 
124  /// Wrap the arguments for `GetDatabase()`.
126  /// The name of the database.
128  };
129 
130  /// Wrap the arguments for `GetDatabaseDdl()`.
132  /// The name of the database.
134  };
135 
136  /// Wrap the arguments for `UpdateDatabase()`.
138  /// The name of the database.
140  /// The DDL statements updating the database schema.
141  std::vector<std::string> statements;
142  };
143 
144  /// Wrap the arguments for `DropDatabase()`.
146  /// The name of the database.
148  };
149 
150  /// Wrap the arguments for `ListDatabases()`.
152  /// The name of the instance.
154  };
155 
156  /// Wrap the arguments for `GetIamPolicy()`.
158  /// The name of the database.
160  };
161 
162  /// Wrap the arguments for `SetIamPolicy()`.
164  /// The name of the database.
166  google::iam::v1::Policy policy;
167  };
168 
169  /// Wrap the arguments for `TestIamPermissions()`.
171  /// The name of the database.
173  std::vector<std::string> permissions;
174  };
175 
176  /// Wrap the arguments for `CreateBackup()`.
178  /// The name of the database.
180  std::string backup_id;
181  /// @deprecated `DatabaseAdminClient::CreateBackup()` initializes
182  /// `expire_time`, but `DatabaseAdminConnection::CreateBackup()` now
183  /// ignores it. Use `expire_timestamp` instead.
184  std::chrono::system_clock::time_point expire_time;
186  /// The backup will contain an externally consistent copy of the database
187  /// at `version_time`. If `version_time` is not specified, the system will
188  /// set `version_time` to the `create_time` of the backup.
189  absl::optional<Timestamp> version_time;
190  /// How to encrypt the backup.
191  EncryptionConfig encryption_config;
192  };
193 
194  /// Wrap the arguments for `GetBackup()`.
196  /// The name of the backup.
197  std::string backup_full_name;
198  };
199 
200  /// Wrap the arguments for `DeleteBackup()`.
202  /// The name of the backup.
203  std::string backup_full_name;
204  };
205 
206  /// Wrap the arguments for `ListBackups()`.
208  /// The name of the instance.
210  std::string filter;
211  };
212 
213  /// Wrap the arguments for `RestoreDatabase()`.
215  /// The name of the database.
217  /// The source backup for the restore.
218  std::string backup_full_name;
219  /// How to encrypt the database.
220  EncryptionConfig encryption_config;
221  };
222 
223  /// Wrap the arguments for `UpdateBackup()`.
225  google::spanner::admin::database::v1::UpdateBackupRequest request;
226  };
227 
228  /// Wrap the arguments for `ListBackupOperations()`.
230  /// The name of the instance.
232  std::string filter;
233  };
234 
235  /// Wrap the arguments for `ListDatabaseOperations()`.
237  /// The name of the instance.
239  std::string filter;
240  };
241  //@}
242 
243  /// Define the interface for a google.spanner.v1.DatabaseAdmin.CreateDatabase
244  /// RPC.
245  virtual future<StatusOr<google::spanner::admin::database::v1::Database>>
247 
248  /// Define the interface for a google.spanner.v1.DatabaseAdmin.GetDatabase
249  /// RPC.
250  virtual StatusOr<google::spanner::admin::database::v1::Database> GetDatabase(
251  GetDatabaseParams) = 0;
252 
253  /// Define the interface for a google.spanner.v1.DatabaseAdmin.GetDatabaseDdl
254  /// RPC.
255  virtual StatusOr<google::spanner::admin::database::v1::GetDatabaseDdlResponse>
257 
258  /// Define the interface for a google.spanner.v1.DatabaseAdmin.UpdateDatabase
259  /// RPC.
260  virtual future<
261  StatusOr<google::spanner::admin::database::v1::UpdateDatabaseDdlMetadata>>
263 
264  /// Define the interface for a google.spanner.v1.DatabaseAdmin.DropDatabase
265  /// RPC.
267 
268  /// Define the interface for a google.spanner.v1.DatabaseAdmin.DropDatabase
269  /// RPC.
270  virtual ListDatabaseRange ListDatabases(ListDatabasesParams) = 0;
271 
272  /// Define the interface for a google.spanner.v1.DatabaseAdmin.RestoreDatabase
273  /// RPC.
274  virtual future<StatusOr<google::spanner::admin::database::v1::Database>>
276 
277  /// Define the interface for a google.spanner.v1.DatabaseAdmin.GetIamPolicy
278  /// RPC.
279  virtual StatusOr<google::iam::v1::Policy> GetIamPolicy(
280  GetIamPolicyParams) = 0;
281 
282  /// Define the interface for a google.spanner.v1.DatabaseAdmin.SetIamPolicy
283  /// RPC.
284  virtual StatusOr<google::iam::v1::Policy> SetIamPolicy(
285  SetIamPolicyParams) = 0;
286 
287  /// Define the interface for a
288  /// google.spanner.v1.DatabaseAdmin.TestIamPermissions RPC.
289  virtual StatusOr<google::iam::v1::TestIamPermissionsResponse>
291 
292  /// Define the interface for a google.spanner.v1.DatabaseAdmin.CreateBackup
293  /// RPC.
294  virtual future<StatusOr<google::spanner::admin::database::v1::Backup>>
296 
297  /// Define the interface for a google.spanner.v1.DatabaseAdmin.GetBackup RPC.
298  virtual StatusOr<google::spanner::admin::database::v1::Backup> GetBackup(
300 
301  /// Define the interface for a google.spanner.v1.DatabaseAdmin.DeleteBackup
302  /// RPC.
304 
305  /// Define the interface for a google.spanner.v1.DatabaseAdmin.ListBackups
306  /// RPC.
307  virtual ListBackupsRange ListBackups(ListBackupsParams);
308 
309  /// Define the interface for a google.spanner.v1.DatabaseAdmin.UpdateBackup
310  /// RPC.
311  virtual StatusOr<google::spanner::admin::database::v1::Backup> UpdateBackup(
313 
314  /// Define the interface for a
315  /// google.spanner.v1.DatabaseAdmin.ListBackupOperations RPC.
316  virtual ListBackupOperationsRange ListBackupOperations(
318 
319  /// Define the interface for a
320  /// google.spanner.v1.DatabaseAdmin.ListDatabaseOperations RPC.
321  virtual ListDatabaseOperationsRange ListDatabaseOperations(
323 };
324 
325 /**
326  * Returns a DatabaseAdminConnection object that can be used for interacting
327  * with Cloud Spanner's admin APIs.
328  *
329  * The returned connection object should not be used directly; instead it
330  * should be given to a `DatabaseAdminClient` instance.
331  *
332  * The optional @p opts argument may be used to configure aspects of the
333  * returned `DatabaseAdminConnection`. Expected options are any of types in the
334  * following option lists.
335  *
336  * - `google::cloud::CommonOptionList`
337  * - `google::cloud::GrpcOptionList`
338  * - `google::cloud::SpannerPolicyOptionList`
339  *
340  * @see `DatabaseAdminConnection`
341  *
342  * @param opts (optional) configure the `DatabaseAdminConnection` created by
343  * this function.
344  */
345 GOOGLE_CLOUD_CPP_SPANNER_ADMIN_API_DEPRECATED("MakeDatabaseAdminConnection()")
347  Options opts = {});
348 
349 /**
350  * Returns a DatabaseAdminConnection object that can be used for interacting
351  * with Cloud Spanner's admin APIs.
352  *
353  * The returned connection object should not be used directly, rather it should
354  * be given to a `DatabaseAdminClient` instance.
355  *
356  * @note Prefer using the `MakeDatabaseAdminConnection()` overload that accepts
357  * `google::cloud::Options`.
358  *
359  * @see `DatabaseAdminConnection`
360  *
361  * @param options configure the `DatabaseAdminConnection` created by this
362  * function.
363  */
364 GOOGLE_CLOUD_CPP_SPANNER_ADMIN_API_DEPRECATED("MakeDatabaseAdminConnection()")
366  ConnectionOptions const& options);
367 
368 /**
369  * Returns a DatabaseAdminConnection object that can be used for interacting
370  * with Cloud Spanner's admin APIs.
371  *
372  * The returned connection object should not be used directly, rather it should
373  * be given to a `DatabaseAdminClient` instance.
374  *
375  * @note Prefer using the `MakeDatabaseAdminConnection()` overload that accepts
376  * `google::cloud::Options`.
377  *
378  * @param options configure the `DatabaseAdminConnection` created by this
379  * function.
380  * @param retry_policy control for how long (or how many times) are retryable
381  * RPCs attempted
382  * @param backoff_policy controls the backoff behavior between retry attempts,
383  * typically some form of exponential backoff with jitter
384  * @param polling_policy controls for how often, and how quickly, are long
385  * running checked for completion
386  *
387  * @par Example
388  * @snippet samples.cc custom-database-admin-policies
389  */
390 GOOGLE_CLOUD_CPP_SPANNER_ADMIN_API_DEPRECATED("MakeDatabaseAdminConnection()")
392  ConnectionOptions const& options, std::unique_ptr<RetryPolicy> retry_policy,
393  std::unique_ptr<BackoffPolicy> backoff_policy,
394  std::unique_ptr<PollingPolicy> polling_policy);
395 
397 } // namespace spanner
398 
399 namespace spanner_internal {
401 
402 /// Internal-only factory that allows us to inject mock stubs for testing.
403 std::shared_ptr<spanner::DatabaseAdminConnection>
404 MakeDatabaseAdminConnectionForTesting(std::shared_ptr<DatabaseAdminStub> stub,
405  Options opts);
406 
408 } // namespace spanner_internal
409 
410 } // namespace cloud
411 } // namespace google
412 
413 #endif // GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_SPANNER_DATABASE_ADMIN_CONNECTION_H