Google Cloud Spanner C++ Client  1.32.1
A C++ Client Library for Google Cloud Spanner
Public Member Functions | List of all members
google::cloud::spanner::v1::DatabaseAdminClient Class Reference

Performs database administration operations on Spanner. More...

#include <google/cloud/spanner/database_admin_client.h>

Public Member Functions

 DatabaseAdminClient (ConnectionOptions const &options=ConnectionOptions())
 
future< StatusOr< google::spanner::admin::database::v1::Database > > CreateDatabase (Database db, std::vector< std::string > extra_statements={}, EncryptionConfig encryption_config=DefaultEncryption())
 Creates a new Cloud Spanner database in the given project and instance. More...
 
StatusOr< google::spanner::admin::database::v1::Database > GetDatabase (Database db)
 Retrieve metadata information about a database. More...
 
StatusOr< google::spanner::admin::database::v1::GetDatabaseDdlResponse > GetDatabaseDdl (Database db)
 Retrieve a database schema. More...
 
future< StatusOr< google::spanner::admin::database::v1::UpdateDatabaseDdlMetadata > > UpdateDatabase (Database db, std::vector< std::string > statements)
 Updates the database using a series of DDL statements. More...
 
Status DropDatabase (Database db)
 Drops (deletes) an existing Cloud Spanner database. More...
 
ListDatabaseRange ListDatabases (Instance in)
 List all the databases in a give project and instance. More...
 
future< StatusOr< google::spanner::admin::database::v1::Database > > RestoreDatabase (Database db, Backup const &backup, EncryptionConfig encryption_config=DefaultEncryption())
 Create a new database by restoring from a completed backup. More...
 
future< StatusOr< google::spanner::admin::database::v1::Database > > RestoreDatabase (Database db, google::spanner::admin::database::v1::Backup const &backup, EncryptionConfig encryption_config=DefaultEncryption())
 Create a new database by restoring from a completed backup. More...
 
StatusOr< google::iam::v1::Policy > GetIamPolicy (Database db)
 Gets the IAM policy for a database. More...
 
StatusOr< google::iam::v1::Policy > SetIamPolicy (Database db, google::iam::v1::Policy policy)
 Set the IAM policy for the given database. More...
 
StatusOr< google::iam::v1::Policy > SetIamPolicy (Database const &db, IamUpdater const &updater)
 Updates the IAM policy for an instance using an optimistic concurrency control loop. More...
 
StatusOr< google::iam::v1::Policy > SetIamPolicy (Database const &db, IamUpdater const &updater, std::unique_ptr< TransactionRerunPolicy > rerun_policy, std::unique_ptr< BackoffPolicy > backoff_policy)
 Updates the IAM policy for an instance using an optimistic concurrency control loop. More...
 
StatusOr< google::iam::v1::TestIamPermissionsResponse > TestIamPermissions (Database db, std::vector< std::string > permissions)
 Get the subset of the permissions the caller has on the given database. More...
 
future< StatusOr< google::spanner::admin::database::v1::Backup > > CreateBackup (Database db, std::string backup_id, Timestamp expire_time, absl::optional< Timestamp > version_time=absl::nullopt, EncryptionConfig encryption_config=DefaultEncryption())
 Creates a new Cloud Spanner backup for the given database. More...
 
future< StatusOr< google::spanner::admin::database::v1::Backup > > CreateBackup (Database db, std::string backup_id, std::chrono::system_clock::time_point expire_time)
 Creates a new Cloud Spanner backup for the given database. More...
 
StatusOr< google::spanner::admin::database::v1::Backup > GetBackup (Backup const &backup)
 Retrieve metadata information about a Backup. More...
 
Status DeleteBackup (google::spanner::admin::database::v1::Backup const &backup)
 Deletes a pending or completed Backup. More...
 
Status DeleteBackup (Backup const &backup)
 Deletes a pending or completed Backup. More...
 
ListBackupsRange ListBackups (Instance in, std::string filter={})
 List all the backups in a given project and instance that match the filter. More...
 
StatusOr< google::spanner::admin::database::v1::Backup > UpdateBackupExpireTime (google::spanner::admin::database::v1::Backup const &backup, Timestamp expire_time)
 Update backup's expire_time. More...
 
StatusOr< google::spanner::admin::database::v1::Backup > UpdateBackupExpireTime (Backup const &backup, Timestamp expire_time)
 Update backup's expire_time. More...
 
StatusOr< google::spanner::admin::database::v1::Backup > UpdateBackupExpireTime (google::spanner::admin::database::v1::Backup const &backup, std::chrono::system_clock::time_point const &expire_time)
 Update backup's expire_time. More...
 
StatusOr< google::spanner::admin::database::v1::Backup > UpdateBackupExpireTime (Backup const &backup, std::chrono::system_clock::time_point const &expire_time)
 Update backup's expire_time. More...
 
ListBackupOperationsRange ListBackupOperations (Instance in, std::string filter={})
 List all the backup operations in a given project and instance that match the filter. More...
 
ListDatabaseOperationsRange ListDatabaseOperations (Instance in, std::string filter={})
 List all the database operations in a given project and instance that match the filter. More...
 
 DatabaseAdminClient (std::shared_ptr< DatabaseAdminConnection > c)
 Create a new client with the given stub. For testing only. More...
 

Detailed Description

Performs database administration operations on Spanner.

Applications use this class to perform administrative operations on spanner Databases.

Performance

Creating a new DatabaseAdminClient is a relatively expensive operation, new objects establish new connections to the service. In contrast, copying or moving an existing DatabaseAdminClient object is a relatively cheap operation. Copied clients share the underlying resources.

Thread Safety

Instances of this class created via copy-construction or copy-assignment share the underlying pool of connections. Access to these copies via multiple threads is guaranteed to work. Two threads operating on the same instance of this class is not guaranteed to work.

Error Handling

This class uses StatusOr<T> to report errors. When an operation fails to perform its work the returned StatusOr<T> contains the error details. If the ok() member function in the StatusOr<T> returns true then it contains the expected result. Please consult the StatusOr<T> documentation for more details.

namespace spanner = ::google::cloud::spanner;
using ::google::cloud::StatusOr;
StatusOr<google::spanner::admin::database::v1::Database> db =
client.CreateDatabase(...).get();
if (!db) {
std::cerr << "Error in CreateDatabase: " << db.status() << "\n";
return;
}
// Use `db` as a smart pointer here, e.g.:
std::cout << "The database fully qualified name is: " << db->name() << "\n";
Performs database administration operations on Spanner.
future< StatusOr< google::spanner::admin::database::v1::Database > > CreateDatabase(Database db, std::vector< std::string > extra_statements={}, EncryptionConfig encryption_config=DefaultEncryption())
Creates a new Cloud Spanner database in the given project and instance.
Contains all the Cloud Spanner C++ client types and functions.
Definition: backup.cc:21
Long running operations

Some operations in this class can take minutes to complete. In this case the class returns a google::cloud::future<StatusOr<T>>, the application can then poll the future or associate a callback to be invoked when the operation completes:

namespace spanner = ::google::cloud::spanner;
// Make example less verbose.
using ::google::cloud::future;
using ::google::cloud::StatusOr;
using std::chrono::chrono_literals; // C++14
auto database = client.CreateDatabase(...);
if (database.wait_for(5m) == std::future_state::ready) {
std::cout << "Database created in under 5 minutes, yay!\n";
return;
}
// Too slow, setup a callback instead:
database.then([](auto f) {
StatusOr<google::spanner::admin::database::v1::Database> db = f.get();
if (!db) {
std::cout << "Failed creating a database!\n";
return;
}
std::cout << "Database created!\n";
});

Definition at line 117 of file database_admin_client.h.

Constructor & Destructor Documentation

◆ DatabaseAdminClient() [1/2]

google::cloud::spanner::v1::DatabaseAdminClient::DatabaseAdminClient ( ConnectionOptions const &  options = ConnectionOptions())
explicit

Definition at line 28 of file database_admin_client.cc.

◆ DatabaseAdminClient() [2/2]

google::cloud::spanner::v1::DatabaseAdminClient::DatabaseAdminClient ( std::shared_ptr< DatabaseAdminConnection c)
inlineexplicit

Create a new client with the given stub. For testing only.

Definition at line 589 of file database_admin_client.h.

Member Function Documentation

◆ CreateBackup() [1/2]

future< StatusOr< gcsa::Backup > > google::cloud::spanner::v1::DatabaseAdminClient::CreateBackup ( Database  db,
std::string  backup_id,
std::chrono::system_clock::time_point  expire_time 
)

Creates a new Cloud Spanner backup for the given database.

Deprecated:
this overload is deprecated; use the Timestamp overload instead.
Idempotency
This is not an idempotent operation. Transient failures are not retried.

This function creates a database backup for the given Google Cloud Spanner database.

Note that the backup_id must be unique within the same instance, it must be between 2 and 60 characters long, it must start with a lowercase letter ([a-z]), it must end with a lowercase letter or a number ([a-z0-9]) and any characters between the beginning and ending characters must be lower case letters, numbers, underscore (_) or dashes (-), that is, they must belong to the [a-z0-9_-] character set.

The expire_time must be at least 6 hours and at most 366 days from the time the CreateBackup() request is processed.

Returns
A google::cloud::future that becomes satisfied when the operation completes on the service. Note that this can take minutes in some cases.

Definition at line 152 of file database_admin_client.cc.

◆ CreateBackup() [2/2]

future< StatusOr< gcsa::Backup > > google::cloud::spanner::v1::DatabaseAdminClient::CreateBackup ( Database  db,
std::string  backup_id,
Timestamp  expire_time,
absl::optional< Timestamp version_time = absl::nullopt,
EncryptionConfig  encryption_config = DefaultEncryption() 
)

Creates a new Cloud Spanner backup for the given database.

Idempotency
This is not an idempotent operation. Transient failures are not retried.

This function creates a database backup for the given Google Cloud Spanner database.

Note that the backup_id must be unique within the same instance, it must be between 2 and 60 characters long, it must start with a lowercase letter ([a-z]), it must end with a lowercase letter or a number ([a-z0-9]) and any characters between the beginning and ending characters must be lower case letters, numbers, underscore (_) or dashes (-), that is, they must belong to the [a-z0-9_-] character set.

The expire_time must be at least 6 hours and at most 366 days from the time the CreateBackup() request is processed.

The backup will contain an externally consistent copy of the database at version_time, if set. Otherwise, the version_time will be the create_time of the backup.

encryption_config How to encrypt the backup.

Returns
A google::cloud::future that becomes satisfied when the operation completes on the service. Note that this can take minutes in some cases.
Example
std::string const& project_id, std::string const& instance_id,
std::string const& database_id, std::string const& backup_id,
google::cloud::spanner::Database database(project_id, instance_id,
database_id);
google::spanner::admin::database::v1::CreateBackupRequest request;
request.set_parent(database.instance().FullName());
request.set_backup_id(backup_id);
request.mutable_backup()->set_database(database.FullName());
*request.mutable_backup()->mutable_expire_time() =
expire_time.get<google::protobuf::Timestamp>().value();
*request.mutable_backup()->mutable_version_time() =
version_time.get<google::protobuf::Timestamp>().value();
auto backup = client.CreateBackup(request).get();
if (!backup) throw std::runtime_error(backup.status().message());
std::cout
<< "Backup " << backup->name() << " of " << backup->database()
<< " of size " << backup->size_bytes() << " bytes"
<< " was created at "
<< google::cloud::spanner::MakeTimestamp(backup->create_time()).value()
<< ".\n";
}
future< StatusOr< google::spanner::admin::database::v1::Backup > > CreateBackup(Database db, std::string backup_id, Timestamp expire_time, absl::optional< Timestamp > version_time=absl::nullopt, EncryptionConfig encryption_config=DefaultEncryption())
Creates a new Cloud Spanner backup for the given database.
This class identifies a Cloud Spanner Database.
Definition: database.h:43
A representation of the Spanner TIMESTAMP type: An instant in time.
Definition: timestamp.h:54
StatusOr< T > get() const
Convert the Timestamp to the user-specified template type.
Definition: timestamp.h:114
future< StatusOr< google::spanner::admin::database::v1::Backup > > CreateBackup(std::string const &parent, google::spanner::admin::database::v1::Backup const &backup, std::string const &backup_id)
Starts creating a new Cloud Spanner Backup.
StatusOr< Timestamp > MakeTimestamp(absl::Time)
Construct a Timestamp from an absl::Time.
Definition: timestamp.cc:67

Definition at line 138 of file database_admin_client.cc.

◆ CreateDatabase()

future< StatusOr< gcsa::Database > > google::cloud::spanner::v1::DatabaseAdminClient::CreateDatabase ( Database  db,
std::vector< std::string >  extra_statements = {},
EncryptionConfig  encryption_config = DefaultEncryption() 
)

Creates a new Cloud Spanner database in the given project and instance.

This function creates a database (using the "CREATE DATABASE" DDL statement) in the given Google Cloud Project and Cloud Spanner instance. The application can provide an optional list of additional DDL statements to atomically create tables and indices as well as the new database.

Note that the database id must be between 2 and 30 characters long, it must start with a lowercase letter ([a-z]), it must end with a lowercase letter or a number ([a-z0-9]) and any characters between the beginning and ending characters must be lower case letters, numbers, underscore (_) or dashes (-), that is, they must belong to the [a-z0-9_-] character set.

encryption_config How to encrypt the database.

Returns
A google::cloud::future that becomes satisfied when the operation completes on the service. Note that this can take minutes in some cases.
Example
std::string const& project_id,
std::string const& instance_id,
std::string const& database_id) {
google::cloud::spanner::Database database(project_id, instance_id,
database_id);
google::spanner::admin::database::v1::CreateDatabaseRequest request;
request.set_parent(database.instance().FullName());
request.set_create_statement("CREATE DATABASE `" + database.database_id() +
"`");
request.add_extra_statements(R"""(
CREATE TABLE Singers (
SingerId INT64 NOT NULL,
FirstName STRING(1024),
LastName STRING(1024),
SingerInfo BYTES(MAX)
) PRIMARY KEY (SingerId))""");
request.add_extra_statements(R"""(
CREATE TABLE Albums (
SingerId INT64 NOT NULL,
AlbumId INT64 NOT NULL,
AlbumTitle STRING(MAX)
) PRIMARY KEY (SingerId, AlbumId),
INTERLEAVE IN PARENT Singers ON DELETE CASCADE)""");
auto db = client.CreateDatabase(request).get();
if (!db) throw std::runtime_error(db.status().message());
std::cout << "Database " << db->name() << " created.\n";
}
future< StatusOr< google::spanner::admin::database::v1::Database > > CreateDatabase(std::string const &parent, std::string const &create_statement)
Creates a new Cloud Spanner database and starts to prepare it for serving.
See also
https://cloud.google.com/spanner/docs/data-definition-language for a full list of the DDL operations
https://cloud.google.com/spanner/docs/data-definition-language#create_database for the regular expression that must be satisfied by the database id.

Definition at line 31 of file database_admin_client.cc.

◆ DeleteBackup() [1/2]

Status google::cloud::spanner::v1::DatabaseAdminClient::DeleteBackup ( Backup const &  backup)

Deletes a pending or completed Backup.

Idempotency
We treat this operation as idempotent. Transient failures are automatically retried.
Example
std::string const& project_id, std::string const& instance_id,
std::string const& backup_id) {
google::cloud::spanner::Instance(project_id, instance_id), backup_id);
auto status = client.DeleteBackup(backup.FullName());
if (!status.ok()) throw std::runtime_error(status.message());
std::cout << "Backup " << backup.FullName() << " was deleted.\n";
}
This class identifies a Cloud Spanner Backup.
Definition: backup.h:39
Status DeleteBackup(google::spanner::admin::database::v1::Backup const &backup)
Deletes a pending or completed Backup.
This class identifies a Cloud Spanner Instance.
Definition: instance.h:42
Status DeleteBackup(std::string const &name)
Deletes a pending or completed [Backup][google.spanner.admin.database.v1.Backup].

Definition at line 169 of file database_admin_client.cc.

◆ DeleteBackup() [2/2]

Status google::cloud::spanner::v1::DatabaseAdminClient::DeleteBackup ( google::spanner::admin::database::v1::Backup const &  backup)

Deletes a pending or completed Backup.

Idempotency
We treat this operation as idempotent. Transient failures are automatically retried.

Definition at line 164 of file database_admin_client.cc.

◆ DropDatabase()

Status google::cloud::spanner::v1::DatabaseAdminClient::DropDatabase ( Database  db)

Drops (deletes) an existing Cloud Spanner database.

Warning
Dropping a database deletes all the tables and other data in the database. This is an unrecoverable operation.
Example
std::string const& project_id, std::string const& instance_id,
std::string const& database_id) {
google::cloud::spanner::Database database(project_id, instance_id,
database_id);
auto status = client.DropDatabase(database.FullName());
if (!status.ok()) throw std::runtime_error(status.message());
std::cout << "Database " << database << " successfully dropped\n";
}
Status DropDatabase(Database db)
Drops (deletes) an existing Cloud Spanner database.
Status DropDatabase(std::string const &database)
Drops (aka deletes) a Cloud Spanner database.

Definition at line 57 of file database_admin_client.cc.

◆ GetBackup()

StatusOr< gcsa::Backup > google::cloud::spanner::v1::DatabaseAdminClient::GetBackup ( Backup const &  backup)

Retrieve metadata information about a Backup.

Idempotency
This is a read-only operation and therefore always idempotent. Transient failures are automatically retried.
Example
std::string const& project_id, std::string const& instance_id,
std::string const& backup_id) {
google::cloud::spanner::Instance(project_id, instance_id), backup_id);
auto backup = client.GetBackup(backup_name.FullName());
if (!backup) throw std::runtime_error(backup.status().message());
std::cout
<< "Backup " << backup->name() << " of size " << backup->size_bytes()
<< " bytes was created at "
<< google::cloud::spanner::MakeTimestamp(backup->create_time()).value()
<< ".\n";
}
StatusOr< google::spanner::admin::database::v1::Backup > GetBackup(Backup const &backup)
Retrieve metadata information about a Backup.
StatusOr< google::spanner::admin::database::v1::Backup > GetBackup(std::string const &name)
Gets metadata on a pending or completed [Backup][google.spanner.admin.database.v1....

Definition at line 160 of file database_admin_client.cc.

◆ GetDatabase()

StatusOr< gcsa::Database > google::cloud::spanner::v1::DatabaseAdminClient::GetDatabase ( Database  db)

Retrieve metadata information about a database.

Idempotency
This is a read-only operation and therefore always idempotent. Transient failures are automatically retried.
Example
std::string const& project_id, std::string const& instance_id,
std::string const& database_id) {
namespace spanner = ::google::cloud::spanner;
auto database = client.GetDatabase(
spanner::Database(project_id, instance_id, database_id).FullName());
if (!database) throw std::runtime_error(database.status().message());
std::cout << "Database metadata is:\n" << database->DebugString();
}
StatusOr< google::spanner::admin::database::v1::Database > GetDatabase(Database db)
Retrieve metadata information about a database.
StatusOr< google::spanner::admin::database::v1::Database > GetDatabase(std::string const &name)
Gets the state of a Cloud Spanner database.

Definition at line 38 of file database_admin_client.cc.

◆ GetDatabaseDdl()

StatusOr< gcsa::GetDatabaseDdlResponse > google::cloud::spanner::v1::DatabaseAdminClient::GetDatabaseDdl ( Database  db)

Retrieve a database schema.

Idempotency
This is a read-only operation and therefore always idempotent. Transient failures are automatically retried.
Example
std::string const& project_id,
std::string const& instance_id,
std::string const& database_id) {
namespace spanner = ::google::cloud::spanner;
auto database = client.GetDatabaseDdl(
spanner::Database(project_id, instance_id, database_id).FullName());
if (!database) throw std::runtime_error(database.status().message());
std::cout << "Database metadata is:\n" << database->DebugString();
}
StatusOr< google::spanner::admin::database::v1::GetDatabaseDdlResponse > GetDatabaseDdl(Database db)
Retrieve a database schema.
StatusOr< google::spanner::admin::database::v1::GetDatabaseDdlResponse > GetDatabaseDdl(std::string const &database)
Returns the schema of a Cloud Spanner database as a list of formatted DDL statements.

Definition at line 42 of file database_admin_client.cc.

◆ GetIamPolicy()

StatusOr< google::iam::v1::Policy > google::cloud::spanner::v1::DatabaseAdminClient::GetIamPolicy ( Database  db)

Gets the IAM policy for a database.

Idempotency
This operation is read-only and therefore always idempotent.
Example
void DatabaseGetIamPolicy(
std::string const& project_id, std::string const& instance_id,
std::string const& database_id) {
google::cloud::spanner::Database database(project_id, instance_id,
database_id);
auto actual = client.GetIamPolicy(database.FullName());
if (!actual) throw std::runtime_error(actual.status().message());
std::cout << "The IAM policy for database " << database_id << " is:\n"
<< actual->DebugString() << "\n";
}
StatusOr< google::iam::v1::Policy > GetIamPolicy(std::string const &resource)
Gets the access control policy for a database or backup resource.

Definition at line 74 of file database_admin_client.cc.

◆ ListBackupOperations()

ListBackupOperationsRange google::cloud::spanner::v1::DatabaseAdminClient::ListBackupOperations ( Instance  in,
std::string  filter = {} 
)

List all the backup operations in a given project and instance that match the filter.

Idempotency
This operation is read-only and therefore always idempotent.
Parameters
inAn instance where the backup operations belong to.
filterA filter expression that filters what operations are returned in the response. See this documentation for the syntax of the filter expression.
Example
std::string const& project_id, std::string const& instance_id,
std::string const& database_id) {
google::cloud::spanner::Instance in(project_id, instance_id);
google::spanner::admin::database::v1::ListBackupOperationsRequest request;
request.set_parent(in.FullName());
request.set_filter(std::string("(metadata.database:") + database_id +
") AND " + "(metadata.@type:type.googleapis.com/" +
"google.spanner.admin.database.v1.CreateBackupMetadata)");
for (auto const& operation : client.ListBackupOperations(request)) {
if (!operation) throw std::runtime_error(operation.status().message());
google::spanner::admin::database::v1::CreateBackupMetadata metadata;
operation->metadata().UnpackTo(&metadata);
std::cout << "Backup " << metadata.name() << " on database "
<< metadata.database()
<< " progress: " << metadata.progress().progress_percent()
<< "% complete.\n";
}
}
ListBackupOperationsRange ListBackupOperations(Instance in, std::string filter={})
List all the backup operations in a given project and instance that match the filter.
StreamRange< google::longrunning::Operation > ListBackupOperations(std::string const &parent)
Lists the backup [long-running operations][google.longrunning.Operation] in the given instance.

Definition at line 215 of file database_admin_client.cc.

◆ ListBackups()

ListBackupsRange google::cloud::spanner::v1::DatabaseAdminClient::ListBackups ( Instance  in,
std::string  filter = {} 
)

List all the backups in a given project and instance that match the filter.

Idempotency
This operation is read-only and therefore always idempotent.
Parameters
inAn instance where the backup operations belong to.
filterA filter expression that filters backups listed in the response. See this documentation for the syntax of the filter expression.
Example
std::string const& project_id,
std::string const& instance_id) {
google::cloud::spanner::Instance in(project_id, instance_id);
std::cout << "All backups:\n";
for (auto const& backup : client.ListBackups(in.FullName())) {
if (!backup) throw std::runtime_error(backup.status().message());
std::cout << "Backup " << backup->name() << " on database "
<< backup->database() << " with size : " << backup->size_bytes()
<< " bytes.\n";
}
}
ListBackupsRange ListBackups(Instance in, std::string filter={})
List all the backups in a given project and instance that match the filter.
StreamRange< google::spanner::admin::database::v1::Backup > ListBackups(std::string const &parent)
Lists completed and pending backups.

Definition at line 173 of file database_admin_client.cc.

◆ ListDatabaseOperations()

ListDatabaseOperationsRange google::cloud::spanner::v1::DatabaseAdminClient::ListDatabaseOperations ( Instance  in,
std::string  filter = {} 
)

List all the database operations in a given project and instance that match the filter.

Idempotency
This operation is read-only and therefore always idempotent.
Parameters
inAn instance where the database operations belong to.
filterA filter expression that filters what operations are returned in the response. See this documentation for the syntax of the filter expression.
Example
std::string const& project_id, std::string const& instance_id) {
google::cloud::spanner::Instance in(project_id, instance_id);
google::spanner::admin::database::v1::ListDatabaseOperationsRequest request;
request.set_parent(in.FullName());
request.set_filter(
"(metadata.@type:type.googleapis.com/"
"google.spanner.admin.database.v1.OptimizeRestoredDatabaseMetadata)");
for (auto const& operation : client.ListDatabaseOperations(request)) {
if (!operation) throw std::runtime_error(operation.status().message());
google::spanner::admin::database::v1::OptimizeRestoredDatabaseMetadata
metadata;
operation->metadata().UnpackTo(&metadata);
std::cout << "Database " << metadata.name() << " restored from backup is "
<< metadata.progress().progress_percent() << "% optimized.\n";
}
}
ListDatabaseOperationsRange ListDatabaseOperations(Instance in, std::string filter={})
List all the database operations in a given project and instance that match the filter.
StreamRange< google::longrunning::Operation > ListDatabaseOperations(std::string const &parent)
Lists database [longrunning-operations][google.longrunning.Operation].

Definition at line 220 of file database_admin_client.cc.

◆ ListDatabases()

ListDatabaseRange google::cloud::spanner::v1::DatabaseAdminClient::ListDatabases ( Instance  in)

List all the databases in a give project and instance.

Idempotency
This operation is read-only and therefore always idempotent.
Example
std::string const& project_id,
std::string const& instance_id) {
google::cloud::spanner::Instance in(project_id, instance_id);
int count = 0;
for (auto const& database : client.ListDatabases(in.FullName())) {
if (!database) throw std::runtime_error(database.status().message());
std::cout << "Database " << database->name() << " full metadata:\n"
<< database->DebugString();
++count;
}
if (count == 0) {
std::cout << "No databases found in instance " << instance_id
<< " for project << " << project_id << "\n";
}
}
ListDatabaseRange ListDatabases(Instance in)
List all the databases in a give project and instance.
StreamRange< google::spanner::admin::database::v1::Database > ListDatabases(std::string const &parent)
Lists Cloud Spanner databases.

Definition at line 53 of file database_admin_client.cc.

◆ RestoreDatabase() [1/2]

future< StatusOr< gcsa::Database > > google::cloud::spanner::v1::DatabaseAdminClient::RestoreDatabase ( Database  db,
Backup const &  backup,
EncryptionConfig  encryption_config = DefaultEncryption() 
)

Create a new database by restoring from a completed backup.

Idempotency
This is not an idempotent operation. Transient failures are not retried.

The new database must be in the same project and in an instance with the same instance configuration as the instance containing the backup.

encryption_config How to encrypt the database.

Returns
A google::cloud::future that becomes satisfied when the operation completes on the service. Note that this can take minutes in some cases.
Example
std::string const& project_id,
std::string const& instance_id,
std::string const& database_id,
std::string const& backup_id) {
google::cloud::spanner::Database database(project_id, instance_id,
database_id);
google::cloud::spanner::Backup backup(database.instance(), backup_id);
auto restored_db =
client
.RestoreDatabase(database.instance().FullName(),
database.database_id(), backup.FullName())
.get();
if (!restored_db) {
throw std::runtime_error(restored_db.status().message());
}
std::cout << "Database";
if (restored_db->restore_info().source_type() ==
google::spanner::admin::database::v1::BACKUP) {
auto const& backup_info = restored_db->restore_info().backup_info();
std::cout << " " << backup_info.source_database() << " as of "
backup_info.version_time())
.value();
}
std::cout << " restored to " << restored_db->name();
std::cout << " from backup " << backup.FullName();
std::cout << ".\n";
}
future< StatusOr< google::spanner::admin::database::v1::Database > > RestoreDatabase(Database db, Backup const &backup, EncryptionConfig encryption_config=DefaultEncryption())
Create a new database by restoring from a completed backup.
future< StatusOr< google::spanner::admin::database::v1::Database > > RestoreDatabase(std::string const &parent, std::string const &database_id, std::string const &backup)
Create a new database by restoring from a completed backup.

Definition at line 61 of file database_admin_client.cc.

◆ RestoreDatabase() [2/2]

future< StatusOr< gcsa::Database > > google::cloud::spanner::v1::DatabaseAdminClient::RestoreDatabase ( Database  db,
google::spanner::admin::database::v1::Backup const &  backup,
EncryptionConfig  encryption_config = DefaultEncryption() 
)

Create a new database by restoring from a completed backup.

Idempotency
This is not an idempotent operation. Transient failures are not retried.

The new database must be in the same project and in an instance with the same instance configuration as the instance containing the backup.

encryption_config How to encrypt the database.

Returns
A google::cloud::future that becomes satisfied when the operation completes on the service. Note that this can take minutes in some cases.

Definition at line 67 of file database_admin_client.cc.

◆ SetIamPolicy() [1/3]

StatusOr< google::iam::v1::Policy > google::cloud::spanner::v1::DatabaseAdminClient::SetIamPolicy ( Database const &  db,
IamUpdater const &  updater 
)

Updates the IAM policy for an instance using an optimistic concurrency control loop.

This function repeatedly reads the current IAM policy in db, and then calls the updater with the this policy. The updater returns an empty optional if no changes are required, or it returns the new desired value for the IAM policy. This function then updates the policy.

Updating an IAM policy can fail with retryable errors or can be aborted because there were simultaneous changes the to IAM policy. In these cases this function reruns the loop until it succeeds.

The function returns the final IAM policy, or an error if the rerun policy for the underlying connection has expired.

Idempotency
This function always sets the etag field on the policy, so the underlying RPCs are retried automatically.
Example
void AddDatabaseReaderOnDatabase(
std::string const& project_id, std::string const& instance_id,
std::string const& database_id, std::string const& new_reader) {
google::cloud::spanner::Database database(project_id, instance_id,
database_id);
auto current = client.GetIamPolicy(database.FullName());
if (!current) throw std::runtime_error(current.status().message());
// Find (or create) the binding for "roles/spanner.databaseReader".
auto& binding = [&current]() -> google::iam::v1::Binding& {
auto role_pos =
std::find_if(current->mutable_bindings()->begin(),
current->mutable_bindings()->end(),
[](google::iam::v1::Binding const& b) {
return b.role() == "roles/spanner.databaseReader" &&
!b.has_condition();
});
if (role_pos != current->mutable_bindings()->end()) {
return *role_pos;
}
auto& binding = *current->add_bindings();
binding.set_role("roles/spanner.databaseReader");
return binding;
}();
auto member_pos =
std::find(binding.members().begin(), binding.members().end(), new_reader);
if (member_pos != binding.members().end()) {
std::cout << "The entity " << new_reader
<< " is already a database reader:\n"
<< current->DebugString();
return;
}
binding.add_members(new_reader);
auto result = client.SetIamPolicy(database.FullName(), *std::move(current));
if (!result) throw std::runtime_error(result.status().message());
std::cout << "Successfully added " << new_reader
<< " to the database reader role:\n"
<< result->DebugString();
}
StatusOr< google::iam::v1::Policy > SetIamPolicy(std::string const &resource, google::iam::v1::Policy const &policy)
Sets the access control policy on a database or backup resource.
Parameters
dbthe identifier for the database where you want to change the IAM policy.
updatera callback to modify the policy. Return an unset optional to indicate that no changes to the policy are needed.

Definition at line 84 of file database_admin_client.cc.

◆ SetIamPolicy() [2/3]

StatusOr< google::iam::v1::Policy > google::cloud::spanner::v1::DatabaseAdminClient::SetIamPolicy ( Database const &  db,
IamUpdater const &  updater,
std::unique_ptr< TransactionRerunPolicy rerun_policy,
std::unique_ptr< BackoffPolicy backoff_policy 
)

Updates the IAM policy for an instance using an optimistic concurrency control loop.

This function repeatedly reads the current IAM policy in db, and then calls the updater with the this policy. The updater returns an empty optional if no changes are required, or it returns the new desired value for the IAM policy. This function then updates the policy.

Updating an IAM policy can fail with retryable errors or can be aborted because there were simultaneous changes the to IAM policy. In these cases this function reruns the loop until it succeeds.

The function returns the final IAM policy, or an error if the rerun policy for the underlying connection has expired.

Idempotency
This function always sets the etag field on the policy, so the underlying RPCs are retried automatically.
Example
void AddDatabaseReaderOnDatabase(
std::string const& project_id, std::string const& instance_id,
std::string const& database_id, std::string const& new_reader) {
google::cloud::spanner::Database database(project_id, instance_id,
database_id);
auto current = client.GetIamPolicy(database.FullName());
if (!current) throw std::runtime_error(current.status().message());
// Find (or create) the binding for "roles/spanner.databaseReader".
auto& binding = [&current]() -> google::iam::v1::Binding& {
auto role_pos =
std::find_if(current->mutable_bindings()->begin(),
current->mutable_bindings()->end(),
[](google::iam::v1::Binding const& b) {
return b.role() == "roles/spanner.databaseReader" &&
!b.has_condition();
});
if (role_pos != current->mutable_bindings()->end()) {
return *role_pos;
}
auto& binding = *current->add_bindings();
binding.set_role("roles/spanner.databaseReader");
return binding;
}();
auto member_pos =
std::find(binding.members().begin(), binding.members().end(), new_reader);
if (member_pos != binding.members().end()) {
std::cout << "The entity " << new_reader
<< " is already a database reader:\n"
<< current->DebugString();
return;
}
binding.add_members(new_reader);
auto result = client.SetIamPolicy(database.FullName(), *std::move(current));
if (!result) throw std::runtime_error(result.status().message());
std::cout << "Successfully added " << new_reader
<< " to the database reader role:\n"
<< result->DebugString();
}
Parameters
dbthe identifier for the database where you want to change the IAM policy.
updatera callback to modify the policy. Return an unset optional to indicate that no changes to the policy are needed.
rerun_policycontrols for how long (or how many times) the updater will be rerun after the IAM policy update aborts.
backoff_policycontrols how long SetIamPolicy waits between reruns.

Definition at line 102 of file database_admin_client.cc.

◆ SetIamPolicy() [3/3]

StatusOr< google::iam::v1::Policy > google::cloud::spanner::v1::DatabaseAdminClient::SetIamPolicy ( Database  db,
google::iam::v1::Policy  policy 
)

Set the IAM policy for the given database.

This function changes the IAM policy configured in the given database to the value of policy.

Idempotency
This function is only idempotent if the etag field in policy is set. Therefore, the underlying RPCs are only retried if the field is set, and the function returns the first RPC error in any other case.
See also
The Cloud Spanner documentation for a description of the roles and permissions supported by Cloud Spanner.
IAM Overview for an introduction to Identity and Access Management in Google Cloud Platform.

Definition at line 79 of file database_admin_client.cc.

◆ TestIamPermissions()

StatusOr< google::iam::v1::TestIamPermissionsResponse > google::cloud::spanner::v1::DatabaseAdminClient::TestIamPermissions ( Database  db,
std::vector< std::string >  permissions 
)

Get the subset of the permissions the caller has on the given database.

This function compares the given list of permissions against those permissions granted to the caller, and returns the subset of the list that the caller actually holds.

Note
Permission wildcards, such as spanner.* are not allowed.
Idempotency
This operation is read-only and therefore always idempotent.
Example
void DatabaseTestIamPermissions(
std::string const& project_id, std::string const& instance_id,
std::string const& database_id, std::string const& permission) {
google::cloud::spanner::Database db(project_id, instance_id, database_id);
auto actual = client.TestIamPermissions(db.FullName(), {permission});
if (!actual) throw std::runtime_error(actual.status().message());
char const* msg = actual->permissions().empty() ? "does not" : "does";
std::cout << "The caller " << msg << " have permission '" << permission
<< "' on the Cloud Spanner database " << db.database_id() << "\n";
}
StatusOr< google::iam::v1::TestIamPermissionsResponse > TestIamPermissions(std::string const &resource, std::vector< std::string > const &permissions)
Returns permissions that the caller has on the specified database or backup resource.
See also
The Cloud Spanner documentation for a description of the roles and permissions supported by Cloud Spanner.
IAM Overview for an introduction to Identity and Access Management in Google Cloud Platform.

Definition at line 133 of file database_admin_client.cc.

◆ UpdateBackupExpireTime() [1/4]

StatusOr< gcsa::Backup > google::cloud::spanner::v1::DatabaseAdminClient::UpdateBackupExpireTime ( Backup const &  backup,
std::chrono::system_clock::time_point const &  expire_time 
)

Update backup's expire_time.

Deprecated:
this overload is deprecated; use the Timestamp overload instead.
Idempotency
This operation is idempotent as its result does not depend on the previous state of the backup. Note that, as is the case with all operations, it is subject to race conditions if multiple tasks are attempting to change the expire time in the same backup.

Definition at line 207 of file database_admin_client.cc.

◆ UpdateBackupExpireTime() [2/4]

StatusOr< gcsa::Backup > google::cloud::spanner::v1::DatabaseAdminClient::UpdateBackupExpireTime ( Backup const &  backup,
Timestamp  expire_time 
)

Update backup's expire_time.

Idempotency
This operation is idempotent as its result does not depend on the previous state of the backup. Note that, as is the case with all operations, it is subject to race conditions if multiple tasks are attempting to change the expire time in the same backup.
Example
std::string const& project_id, std::string const& instance_id,
std::string const& backup_id,
google::cloud::spanner::Instance(project_id, instance_id), backup_id);
google::spanner::admin::database::v1::UpdateBackupRequest request;
request.mutable_backup()->set_name(backup_name.FullName());
*request.mutable_backup()->mutable_expire_time() =
expire_time.get<google::protobuf::Timestamp>().value();
request.mutable_update_mask()->add_paths("expire_time");
auto backup = client.UpdateBackup(request);
if (!backup) throw std::runtime_error(backup.status().message());
std::cout
<< "Backup " << backup->name() << " updated to expire at "
<< google::cloud::spanner::MakeTimestamp(backup->expire_time()).value()
<< ".\n";
}
StatusOr< google::spanner::admin::database::v1::Backup > UpdateBackup(google::spanner::admin::database::v1::Backup const &backup, google::protobuf::FieldMask const &update_mask)
Updates a pending or completed [Backup][google.spanner.admin.database.v1.Backup].

Definition at line 189 of file database_admin_client.cc.

◆ UpdateBackupExpireTime() [3/4]

StatusOr< gcsa::Backup > google::cloud::spanner::v1::DatabaseAdminClient::UpdateBackupExpireTime ( google::spanner::admin::database::v1::Backup const &  backup,
std::chrono::system_clock::time_point const &  expire_time 
)

Update backup's expire_time.

Deprecated:
this overload is deprecated; use the Timestamp overload instead.
Idempotency
This operation is idempotent as its result does not depend on the previous state of the backup. Note that, as is the case with all operations, it is subject to race conditions if multiple tasks are attempting to change the expire time in the same backup.

Definition at line 199 of file database_admin_client.cc.

◆ UpdateBackupExpireTime() [4/4]

StatusOr< gcsa::Backup > google::cloud::spanner::v1::DatabaseAdminClient::UpdateBackupExpireTime ( google::spanner::admin::database::v1::Backup const &  backup,
Timestamp  expire_time 
)

Update backup's expire_time.

Idempotency
This operation is idempotent as its result does not depend on the previous state of the backup. Note that, as is the case with all operations, it is subject to race conditions if multiple tasks are attempting to change the expire time in the same backup.

Definition at line 178 of file database_admin_client.cc.

◆ UpdateDatabase()

future< StatusOr< gcsa::UpdateDatabaseDdlMetadata > > google::cloud::spanner::v1::DatabaseAdminClient::UpdateDatabase ( Database  db,
std::vector< std::string >  statements 
)

Updates the database using a series of DDL statements.

This function schedules a series of updates to the database using a sequence of DDL statements.

Returns
A google::cloud::future that becomes satisfied when all the statements complete. Note that Cloud Spanner may fail to execute some of the statements.
Example
std::string const& project_id, std::string const& instance_id,
std::string const& database_id) {
google::cloud::spanner::Database database(project_id, instance_id,
database_id);
auto metadata =
client
database.FullName(),
{"ALTER TABLE Albums ADD COLUMN MarketingBudget INT64"})
.get();
if (!metadata) throw std::runtime_error(metadata.status().message());
std::cout << "Added MarketingBudget column\n";
}
future< StatusOr< google::spanner::admin::database::v1::UpdateDatabaseDdlMetadata > > UpdateDatabaseDdl(std::string const &database, std::vector< std::string > const &statements)
Updates the schema of a Cloud Spanner database by creating/altering/dropping tables,...
See also
https://cloud.google.com/spanner/docs/data-definition-language for a full list of the DDL operations

Definition at line 48 of file database_admin_client.cc.