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

Performs instance administration operations on Cloud Spanner. More...

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

Public Member Functions

 InstanceAdminClient (std::shared_ptr< InstanceAdminConnection > conn)
 
 InstanceAdminClient ()=delete
 No default construction. More...
 
 InstanceAdminClient (InstanceAdminClient const &)=default
 
InstanceAdminClientoperator= (InstanceAdminClient const &)=default
 
 InstanceAdminClient (InstanceAdminClient &&)=default
 
InstanceAdminClientoperator= (InstanceAdminClient &&)=default
 
StatusOr< google::spanner::admin::instance::v1::Instance > GetInstance (Instance const &in)
 Retrieve metadata information about a Cloud Spanner Instance. More...
 
future< StatusOr< google::spanner::admin::instance::v1::Instance > > CreateInstance (google::spanner::admin::instance::v1::CreateInstanceRequest const &)
 Creates a new Cloud Spanner instance in the given project. More...
 
future< StatusOr< google::spanner::admin::instance::v1::Instance > > UpdateInstance (google::spanner::admin::instance::v1::UpdateInstanceRequest const &)
 Updates a Cloud Spanner instance. More...
 
Status DeleteInstance (Instance const &in)
 Deletes an existing Cloud Spanner instance. More...
 
StatusOr< google::spanner::admin::instance::v1::InstanceConfig > GetInstanceConfig (std::string const &name)
 Retrieve information about a Cloud Spanner Instance Config. More...
 
ListInstanceConfigsRange ListInstanceConfigs (std::string project_id)
 Retrieve a list of instance configs for a given project. More...
 
ListInstancesRange ListInstances (std::string project_id, std::string filter)
 Retrieve a list of instances for a given project. More...
 
StatusOr< google::iam::v1::Policy > GetIamPolicy (Instance const &in)
 Get the IAM policy in effect for the given instance. More...
 
StatusOr< google::iam::v1::Policy > SetIamPolicy (Instance const &in, google::iam::v1::Policy policy)
 Set the IAM policy for the given instance. More...
 
StatusOr< google::iam::v1::Policy > SetIamPolicy (Instance const &in, IamUpdater const &updater)
 Updates the IAM policy for an instance using an optimistic concurrency control loop. More...
 
StatusOr< google::iam::v1::Policy > SetIamPolicy (Instance const &in, 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 (Instance const &in, std::vector< std::string > permissions)
 Get the subset of the permissions the caller has on the given instance. More...
 

Friends

bool operator== (InstanceAdminClient const &a, InstanceAdminClient const &b)
 
bool operator!= (InstanceAdminClient const &a, InstanceAdminClient const &b)
 

Detailed Description

Performs instance administration operations on Cloud Spanner.

Applications use this class to perform operations on Spanner Databases.

Performance

InstanceAdminClient objects are cheap to create, copy, and move. However, each InstanceAdminClient object must be created with a std::shared_ptr<InstanceAdminConnection>, which itself is relatively expensive to create. Therefore, connection instances should be shared when possible. See the MakeInstanceAdminConnection() method and the InstanceAdminConnection interface for more details.

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.

Definition at line 64 of file instance_admin_client.h.

Constructor & Destructor Documentation

◆ InstanceAdminClient() [1/4]

google::cloud::spanner::v1::InstanceAdminClient::InstanceAdminClient ( std::shared_ptr< InstanceAdminConnection conn)
inlineexplicit

Definition at line 67 of file instance_admin_client.h.

◆ InstanceAdminClient() [2/4]

google::cloud::spanner::v1::InstanceAdminClient::InstanceAdminClient ( )
delete

No default construction.

Use InstanceAdminClient(std::shared_ptr<InstanceAdminConnection>)

◆ InstanceAdminClient() [3/4]

google::cloud::spanner::v1::InstanceAdminClient::InstanceAdminClient ( InstanceAdminClient const &  )
default

◆ InstanceAdminClient() [4/4]

google::cloud::spanner::v1::InstanceAdminClient::InstanceAdminClient ( InstanceAdminClient &&  )
default

Member Function Documentation

◆ CreateInstance()

future< StatusOr< google::spanner::admin::instance::v1::Instance > > google::cloud::spanner::v1::InstanceAdminClient::CreateInstance ( google::spanner::admin::instance::v1::CreateInstanceRequest const &  request)

Creates a new Cloud Spanner instance in the given project.

Use CreateInstanceRequestBuilder to build the google::spanner::admin::instance::v1::CreateInstanceRequest object.

Note that the instance id must be between 2 and 64 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, or dashes (-), that is, they must belong to the [-a-z0-9] character set.

Example
std::string const& project_id,
std::string const& instance_id,
std::string const& display_name,
std::string const& config) {
namespace spanner = ::google::cloud::spanner;
spanner::Instance in(project_id, instance_id);
auto project = google::cloud::Project(project_id);
std::string instance_config =
project.FullName() + "/instanceConfigs/" + config;
auto instance =
client
.SetDisplayName(display_name)
.SetNodeCount(1)
.SetLabels({{"cloud_spanner_samples", "true"}})
.Build())
.get();
if (!instance) throw std::runtime_error(instance.status().message());
std::cout << "Created instance [" << in << "]:\n" << instance->DebugString();
}
CreateInstanceRequestBuilder is a builder class for google::spanner::admin::instance::v1::CreateInsta...
future< StatusOr< google::spanner::admin::instance::v1::Instance > > CreateInstance(google::spanner::admin::instance::v1::CreateInstanceRequest const &)
Creates a new Cloud Spanner instance in the given project.
This class identifies a Cloud Spanner Instance.
Definition: instance.h:42
future< StatusOr< google::spanner::admin::instance::v1::Instance > > CreateInstance(std::string const &parent, std::string const &instance_id, google::spanner::admin::instance::v1::Instance const &instance)
Creates an instance and begins preparing it to begin serving.
Contains all the Cloud Spanner C++ client types and functions.
Definition: backup.cc:21

Definition at line 30 of file instance_admin_client.cc.

◆ DeleteInstance()

Status google::cloud::spanner::v1::InstanceAdminClient::DeleteInstance ( Instance const &  in)

Deletes an existing Cloud Spanner instance.

Warning
Deleting an instance deletes all the databases in the instance. This is an unrecoverable operation.
Example
std::string const& project_id,
std::string const& instance_id) {
google::cloud::spanner::Instance in(project_id, instance_id);
auto status = client.DeleteInstance(in.FullName());
if (!status.ok()) throw std::runtime_error(status.message());
std::cout << "Deleted instance [" << in << "]\n";
}
Status DeleteInstance(Instance const &in)
Deletes an existing Cloud Spanner instance.
Status DeleteInstance(std::string const &name)
Deletes an instance.

Definition at line 43 of file instance_admin_client.cc.

◆ GetIamPolicy()

StatusOr< google::iam::v1::Policy > google::cloud::spanner::v1::InstanceAdminClient::GetIamPolicy ( Instance const &  in)

Get the IAM policy in effect for the given instance.

This function retrieves the IAM policy configured in the given instance, that is, which roles are enabled in the instance, and what entities are members of each role.

Idempotency
This is a read-only operation and therefore it is always treated as idempotent.
Example
void InstanceGetIamPolicy(
std::string const& project_id, std::string const& instance_id) {
google::cloud::spanner::Instance in(project_id, instance_id);
auto actual = client.GetIamPolicy(in.FullName());
if (!actual) throw std::runtime_error(actual.status().message());
std::cout << "The IAM policy for instance " << instance_id << " is:\n"
<< actual->DebugString();
}
StatusOr< google::iam::v1::Policy > GetIamPolicy(std::string const &resource)
Gets the access control policy for an instance 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 62 of file instance_admin_client.cc.

◆ GetInstance()

StatusOr< google::spanner::admin::instance::v1::Instance > google::cloud::spanner::v1::InstanceAdminClient::GetInstance ( Instance const &  in)

Retrieve metadata information about a Cloud Spanner Instance.

Idempotency
This is a read-only operation and therefore it is always treated as idempotent.
Example
std::string const& project_id,
std::string const& instance_id) {
google::cloud::spanner::Instance in(project_id, instance_id);
auto instance = client.GetInstance(in.FullName());
if (!instance) throw std::runtime_error(instance.status().message());
std::cout << "The instance " << instance->name()
<< " exists and its metadata is:\n"
<< instance->DebugString();
}
StatusOr< google::spanner::admin::instance::v1::Instance > GetInstance(Instance const &in)
Retrieve metadata information about a Cloud Spanner Instance.
StatusOr< google::spanner::admin::instance::v1::Instance > GetInstance(std::string const &name)
Gets information about a particular instance.

Definition at line 25 of file instance_admin_client.cc.

◆ GetInstanceConfig()

StatusOr< google::spanner::admin::instance::v1::InstanceConfig > google::cloud::spanner::v1::InstanceAdminClient::GetInstanceConfig ( std::string const &  name)

Retrieve information about a Cloud Spanner Instance Config.

Idempotency
This is a read-only operation and therefore it is always treated as idempotent.
Example
std::string const& project_id,
std::string const& instance_config_name) {
auto project = google::cloud::Project(project_id);
auto instance_config = client.GetInstanceConfig(
project.FullName() + "/instanceConfigs/" + instance_config_name);
if (!instance_config) {
throw std::runtime_error(instance_config.status().message());
}
std::cout << "The instanceConfig " << instance_config->name()
<< " exists and its metadata is:\n"
<< instance_config->DebugString();
}
StatusOr< google::spanner::admin::instance::v1::InstanceConfig > GetInstanceConfig(std::string const &name)
Retrieve information about a Cloud Spanner Instance Config.
StatusOr< google::spanner::admin::instance::v1::InstanceConfig > GetInstanceConfig(std::string const &name)
Gets information about a particular instance configuration.

Definition at line 48 of file instance_admin_client.cc.

◆ ListInstanceConfigs()

ListInstanceConfigsRange google::cloud::spanner::v1::InstanceAdminClient::ListInstanceConfigs ( std::string  project_id)

Retrieve a list of instance configs for a given project.

Idempotency
This is a read-only operation and therefore it is always treated as idempotent.
Example
std::string const& project_id) {
int count = 0;
auto project = google::cloud::Project(project_id);
for (auto const& instance_config :
client.ListInstanceConfigs(project.FullName())) {
if (!instance_config) {
throw std::runtime_error(instance_config.status().message());
}
++count;
std::cout << "Instance config [" << count << "]:\n"
<< instance_config->DebugString();
}
if (count == 0) {
std::cout << "No instance configs found in project " << project_id << "\n";
}
}
ListInstanceConfigsRange ListInstanceConfigs(std::string project_id)
Retrieve a list of instance configs for a given project.
StreamRange< google::spanner::admin::instance::v1::InstanceConfig > ListInstanceConfigs(std::string const &parent)
Lists the supported instance configurations for a given project.

Definition at line 52 of file instance_admin_client.cc.

◆ ListInstances()

ListInstancesRange google::cloud::spanner::v1::InstanceAdminClient::ListInstances ( std::string  project_id,
std::string  filter 
)

Retrieve a list of instances for a given project.

Idempotency
This is a read-only operation and therefore it is always treated as idempotent.
Example
std::string const& project_id) {
int count = 0;
auto project = google::cloud::Project(project_id);
for (auto const& instance : client.ListInstances(project.FullName())) {
if (!instance) throw std::runtime_error(instance.status().message());
++count;
std::cout << "Instance [" << count << "]:\n" << instance->DebugString();
}
if (count == 0) {
std::cout << "No instances found in project " << project_id << "\n";
}
}
ListInstancesRange ListInstances(std::string project_id, std::string filter)
Retrieve a list of instances for a given project.
StreamRange< google::spanner::admin::instance::v1::Instance > ListInstances(std::string const &parent)
Lists all instances in the given project.

Definition at line 57 of file instance_admin_client.cc.

◆ operator=() [1/2]

InstanceAdminClient& google::cloud::spanner::v1::InstanceAdminClient::operator= ( InstanceAdminClient &&  )
default

◆ operator=() [2/2]

InstanceAdminClient& google::cloud::spanner::v1::InstanceAdminClient::operator= ( InstanceAdminClient const &  )
default

◆ SetIamPolicy() [1/3]

StatusOr< google::iam::v1::Policy > google::cloud::spanner::v1::InstanceAdminClient::SetIamPolicy ( Instance const &  in,
google::iam::v1::Policy  policy 
)

Set the IAM policy for the given instance.

This function changes the IAM policy configured in the given instance 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.
Example
std::string const& project_id,
std::string const& instance_id,
std::string const& new_reader) {
google::cloud::spanner::Instance in(project_id, instance_id);
auto result = client.SetIamPolicy(
in.FullName(),
[&new_reader](google::iam::v1::Policy current)
-> absl::optional<google::iam::v1::Policy> {
// 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);
return 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 an instance 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 67 of file instance_admin_client.cc.

◆ SetIamPolicy() [2/3]

StatusOr< google::iam::v1::Policy > google::cloud::spanner::v1::InstanceAdminClient::SetIamPolicy ( Instance const &  in,
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 in, 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.
Parameters
inthe identifier for the instance 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 72 of file instance_admin_client.cc.

◆ SetIamPolicy() [3/3]

StatusOr< google::iam::v1::Policy > google::cloud::spanner::v1::InstanceAdminClient::SetIamPolicy ( Instance const &  in,
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 in, 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.
Parameters
inthe identifier for the instance 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 90 of file instance_admin_client.cc.

◆ TestIamPermissions()

StatusOr< google::iam::v1::TestIamPermissionsResponse > google::cloud::spanner::v1::InstanceAdminClient::TestIamPermissions ( Instance const &  in,
std::vector< std::string >  permissions 
)

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

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.
Example
void InstanceTestIamPermissions(
std::string const& project_id, std::string const& instance_id) {
google::cloud::spanner::Instance in(project_id, instance_id);
auto actual =
client.TestIamPermissions(in.FullName(), {"spanner.databases.list"});
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 to list databases on the Cloud Spanner instance "
<< in.instance_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 instance 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 121 of file instance_admin_client.cc.

◆ UpdateInstance()

future< StatusOr< google::spanner::admin::instance::v1::Instance > > google::cloud::spanner::v1::InstanceAdminClient::UpdateInstance ( google::spanner::admin::instance::v1::UpdateInstanceRequest const &  request)

Updates a Cloud Spanner instance.

Use google::cloud::spanner::UpdateInstanceRequestBuilder to build the google::spanner::admin::instance::v1::UpdateInstanceRequest object.

Idempotency
This operation is idempotent as its result does not depend on the previous state of the instance. Note that, as is the case with all operations, it is subject to race conditions if multiple tasks are attempting to change the same fields in the same instance.
Example
std::string const& project_id,
std::string const& instance_id,
std::string const& new_display_name) {
google::cloud::spanner::Instance in(project_id, instance_id);
auto f = client.UpdateInstance(
.SetDisplayName(new_display_name)
.Build());
auto instance = f.get();
if (!instance) throw std::runtime_error(instance.status().message());
std::cout << "Updated instance [" << in << "]\n";
}
future< StatusOr< google::spanner::admin::instance::v1::Instance > > UpdateInstance(google::spanner::admin::instance::v1::UpdateInstanceRequest const &)
Updates a Cloud Spanner instance.
UpdateInstanceRequestBuilder is a builder class for google::spanner::admin::instance::v1::UpdateInsta...
future< StatusOr< google::spanner::admin::instance::v1::Instance > > UpdateInstance(google::spanner::admin::instance::v1::Instance const &instance, google::protobuf::FieldMask const &field_mask)
Updates an instance, and begins allocating or releasing resources as requested.

Definition at line 37 of file instance_admin_client.cc.

Friends And Related Function Documentation

◆ operator!=

bool operator!= ( InstanceAdminClient const &  a,
InstanceAdminClient const &  b 
)
friend

Definition at line 88 of file instance_admin_client.h.

◆ operator==

bool operator== ( InstanceAdminClient const &  a,
InstanceAdminClient const &  b 
)
friend

Definition at line 84 of file instance_admin_client.h.