Class InstanceAdminClient (2.24.0)

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. For more information, see the Error Handling Guide.

Use InstanceAdminClient(std::shared_ptr<InstanceAdminConnection>)

Idempotency

This is a read-only operation and therefore it is always treated as idempotent.

Example

void GetInstance(google::cloud::spanner_admin::InstanceAdminClient client,
                 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::move(instance).status();

  std::cout << "The instance " << instance->name()
            << " exists and its metadata is:\n"
            << instance->DebugString();
}

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

void CreateInstance(google::cloud::spanner_admin::InstanceAdminClient client,
                    std::string const& project_id,
                    std::string const& instance_id,
                    std::string const& display_name,
                    std::string const& config_id) {
  namespace spanner = ::google::cloud::spanner;
  spanner::Instance in(project_id, instance_id);

  auto project = google::cloud::Project(project_id);
  std::string config_name =
      project.FullName() + "/instanceConfigs/" + config_id;
  auto instance =
      client
          .CreateInstance(spanner::CreateInstanceRequestBuilder(in, config_name)
                              .SetDisplayName(display_name)
                              .SetNodeCount(1)
                              .SetLabels({{"cloud_spanner_samples", "true"}})
                              .Build())
          .get();
  if (!instance) throw std::move(instance).status();
  std::cout << "Created instance [" << in << "]:\n" << instance->DebugString();
}

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

void UpdateInstance(google::cloud::spanner_admin::InstanceAdminClient client,
                    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(
      google::cloud::spanner::UpdateInstanceRequestBuilder(in)
          .SetDisplayName(new_display_name)
          .Build());
  auto instance = f.get();
  if (!instance) throw std::move(instance).status();
  std::cout << "Updated instance [" << in << "]\n";
}

Example

void DeleteInstance(google::cloud::spanner_admin::InstanceAdminClient client,
                    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::move(status);
  std::cout << "Deleted instance [" << in << "]\n";
}

Idempotency

This is a read-only operation and therefore it is always treated as idempotent.

Example

void GetInstanceConfig(google::cloud::spanner_admin::InstanceAdminClient client,
                       std::string const& project_id,
                       std::string const& config_id) {
  auto project = google::cloud::Project(project_id);
  auto config = client.GetInstanceConfig(project.FullName() +
                                         "/instanceConfigs/" + config_id);
  if (!config) throw std::move(config).status();
  std::cout << "The instanceConfig " << config->name()
            << " exists and its metadata is:\n"
            << config->DebugString();
}

Idempotency

This is a read-only operation and therefore it is always treated as idempotent.

Example

void ListInstanceConfigs(
    google::cloud::spanner_admin::InstanceAdminClient client,
    std::string const& project_id) {
  int count = 0;
  auto project = google::cloud::Project(project_id);
  for (auto& config : client.ListInstanceConfigs(project.FullName())) {
    if (!config) throw std::move(config).status();
    ++count;
    std::cout << "Instance config [" << count << "]:\n"
              << config->DebugString();
  }
  if (count == 0) {
    std::cout << "No instance configs found in project " << project_id << "\n";
  }
}

Idempotency

This is a read-only operation and therefore it is always treated as idempotent.

Example

void ListInstances(google::cloud::spanner_admin::InstanceAdminClient client,
                   std::string const& project_id) {
  int count = 0;
  auto project = google::cloud::Project(project_id);
  for (auto& instance : client.ListInstances(project.FullName())) {
    if (!instance) throw std::move(instance).status();
    ++count;
    std::cout << "Instance [" << count << "]:\n" << instance->DebugString();
  }
  if (count == 0) {
    std::cout << "No instances found in project " << project_id << "\n";
  }
}

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(
    google::cloud::spanner_admin::InstanceAdminClient client,
    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::move(actual).status();

  std::cout << "The IAM policy for instance " << instance_id << " is:\n"
            << actual->DebugString();
}

See Also

The Cloud Spanner documentation for a description of the roles and permissions supported by Cloud Spanner.

See Also

IAM Overview for an introduction to Identity and Access Management in Google Cloud Platform.

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

void AddDatabaseReader(google::cloud::spanner_admin::InstanceAdminClient client,
                       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::move(result).status();
  std::cout << "Successfully added " << new_reader
            << " to the database reader role:\n"
            << result->DebugString();
}

See Also

The Cloud Spanner documentation for a description of the roles and permissions supported by Cloud Spanner.

See Also

IAM Overview for an introduction to Identity and Access Management in Google Cloud Platform.

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.

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.

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.

Example

void InstanceTestIamPermissions(
    google::cloud::spanner_admin::InstanceAdminClient client,
    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::move(actual).status();

  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";
}

See Also

The Cloud Spanner documentation for a description of the roles and permissions supported by Cloud Spanner.

See Also

IAM Overview for an introduction to Identity and Access Management in Google Cloud Platform.