google-cloud-cpp v3 Migration Guide

Bazel is moving away from WORKSPACE file support to using modules from the Bazel Central Registry. Part of the v3.x.y release series includes supporting the new google-cloud-cpp Bazel module which can be added to your MODULE.bazel file as a dependency.

google-cloud-cpp will support WORKSPACE files until Bazel 8 reaches end of support (2027/12). However, some dependencies may stop supporting WORKSPACE files before then which will limit what dependency versions can be used via WORKSPACE.

If your application links directly to one of these decommissioned proto libraries, you should update your CMakeLists.txt with the preferred proto library name.

Omit the v1 namespace for unversioned libraries:

• Bigtable
• PubSub
• Spanner
• Storage

For example, code that used to look like this:

Before:

google::cloud::v1::pubsub::Publisher publisher;

Should be changed to this:

After:

google::cloud::pubsub::Publisher publisher;

Omit the gcpcxxV1 namespace from versioned libraries. The version is now part of the service namespace.

For example, code that used to look like this:

Before:

google::cloud::bigquery_storage_v1::gcpcxxV1::BigQueryReadClient client;

Should be changed to this:

After:

google::cloud::bigquery_storage_v1::BigQueryReadClient client;

Types that were previously defined in both google::cloud::grpc_utils and google::cloud now only exist in google::cloud.

For example, code that used to look like this:

Before:

#include "google/cloud/grpc_utils/completion_queue.h

google::cloud::grpc_utils::CompletionQueue cq;

Should be changed to this:

After:

#include "google/cloud/completion_queue.h

google::cloud::CompletionQueue cq;

We created some early libraries without version and/or service directories. For backwards compatibility, forwarding headers were left at parent directory that pointed at the first version of the library:

• google/cloud/accessapproval
• google/cloud/accesscontextmanager
• google/cloud/apigateway
• google/cloud/apigeeconnect
• google/cloud/apikeys
• google/cloud/appengine
• google/cloud/artifactregistry
• google/cloud/asset
• google/cloud/assuredworkloads
• google/cloud/automl
• google/cloud/baremetalsolution
• google/cloud/batch
• google/cloud/beyondcorp
• google/cloud/bigquery
• google/cloud/billing
• google/cloud/binaryauthorization
• google/cloud/certificatemanager
• google/cloud/channel
• google/cloud/cloudbuild
• google/cloud/composer
• google/cloud/connectors
• google/cloud/contactcenterinsights
• google/cloud/container
• google/cloud/containeranalysis
• google/cloud/datacatalog
• google/cloud/datamigration
• google/cloud/dataplex
• google/cloud/dataproc
• google/cloud/datastream
• google/cloud/deploy
• google/cloud/dlp
• google/cloud/documentai
• google/cloud/edgecontainer
• google/cloud/eventarc
• google/cloud/filestore
• google/cloud/functions
• google/cloud/gkehub
• google/cloud/iam
• google/cloud/iap
• google/cloud/ids
• google/cloud/kms
• google/cloud/language
• google/cloud/logging
• google/cloud/managedidentities
• google/cloud/memcache
• google/cloud/monitoring
• google/cloud/networkconnectivity
• google/cloud/networkmanagement
• google/cloud/notebooks
• google/cloud/optimization
• google/cloud/orgpolicy
• google/cloud/osconfig
• google/cloud/oslogin
• google/cloud/policytroubleshooter
• google/cloud/privateca
• google/cloud/profiler
• google/cloud/recommender
• google/cloud/redis
• google/cloud/resourcemanager
• google/cloud/retail
• google/cloud/run
• google/cloud/scheduler
• google/cloud/secretmanager
• google/cloud/securitycenter
• google/cloud/servicecontrol
• google/cloud/servicedirectory
• google/cloud/servicemanagement
• google/cloud/serviceusage
• google/cloud/shell
• google/cloud/speech
• google/cloud/storagetransfer
• google/cloud/talent
• google/cloud/tasks
• google/cloud/texttospeech
• google/cloud/tpu
• google/cloud/trace
• google/cloud/translate
• google/cloud/video
• google/cloud/videointelligence
• google/cloud/vision
• google/cloud/vmmigration
• google/cloud/vpcaccess
• google/cloud/webrisk
• google/cloud/websecurityscanner
• google/cloud/workflows

For example, code that used to look like this:

Before:

#include "google/cloud/bigquery/bigquery_read_client.h"

Should be changed to this:

After:

#include "google/cloud/bigquery/storage/v1/bigquery_read_client.h"

The library no longer exposes the google/cloud/bigquery/retry_traits.h header file. It only contained internal symbols.

We have removed the bigtable::RowReader constructors that accept DataClient as an argument.

Developers that read rows by directly constructing a RowReader object should instead construct a Table object and call Table::ReadRows(...).

For example, code that used to look like this:

Before:

#include "google/cloud/bigtable/data_client.h"
#include "google/cloud/bigtable/row_reader.h"
#include "google/cloud/bigtable/table.h"

// ...

auto client = google::cloud::bigtable::MakeDataClient(
    "my-project", "my-instance", creds);
auto reader = google::cloud::bigtable::RowReader(
    client, "my-table-id", google::cloud::bigtable::RowSet("r1", "r2"),
    google::cloud::bigtable::RowReader::NO_ROWS_LIMIT,
    google::cloud::bigtable::Filter::PassAllFilter(),
    /*...retry and backoff policies...*/);

for (auto& row : reader) {
  if (!row) throw std::move(row).status();
  // ...
}

Should be changed to this:

After:

#include "google/cloud/bigtable/table.h"

// ...

namespace cbt = google::cloud::bigtable;
cbt::Table table(cbt::MakeDataConnection(),
                 cbt::TableResource("my-project", "my-instance", "my-table-id"));

for (auto& row : table.ReadRows(
         cbt::RowSet("r1", "r2"),
         cbt::Filter::PassAllFilter())) {
  if (!row) throw std::move(row).status();
  // ...
}

We have removed the deprecated bigtable::ClientOptions class. Please use google::cloud::Options instead.

The following table shows the mapping from bigtable::ClientOptions methods to their google::cloud::Options equivalents:

Example usage of the replacements can be found below.

Before:

auto client = bigtable::Client(
    bigtable::ClientOptions().set_connection_pool_size(4));

After:

auto client = bigtable::Client(
    google::cloud::Options{}.set<google::cloud::GrpcNumChannelsOption>(4));

bigtable::CreateDefaultDataClient

We have removed the deprecated bigtable::CreateDefaultDataClient function. Please use bigtable::MakeDataClient instead.

Before:

auto client = bigtable::CreateDefaultDataClient(
    "my-project", "my-instance",
    bigtable::ClientOptions().set_connection_pool_size(4));

After:

auto client = bigtable::MakeDataClient(
    "my-project", "my-instance",
    google::cloud::Options{}.set<google::cloud::GrpcNumChannelsOption>(4));

bigtable::CreateDefaultAdminClient

The deprecated bigtable::CreateDefaultAdminClient function has been removed. Please use bigtable::MakeAdminClient instead.

Before:

auto client = bigtable::CreateDefaultAdminClient(
    "my-project", bigtable::ClientOptions().set_connection_pool_size(4));

After:

auto client = bigtable::MakeAdminClient(
    "my-project",
    google::cloud::Options{}.set<google::cloud::GrpcNumChannelsOption>(4));

bigtable::CreateDefaultInstanceAdminClient

The deprecated bigtable::CreateDefaultInstanceAdminClient function has been removed. Please use bigtable::MakeInstanceAdminClient instead.

Before:

auto client = bigtable::CreateDefaultInstanceAdminClient(
    "my-project", bigtable::ClientOptions().set_connection_pool_size(4));

After:

auto client = bigtable::MakeInstanceAdminClient(
    "my-project",
    google::cloud::Options{}.set<google::cloud::GrpcNumChannelsOption>(4));

AsyncRowReader::NO_ROWS_LIMIT has been removed. Please use google::cloud::bigtable::RowReader::NO_ROWS_LIMIT instead.

// Before
auto limit = google::cloud::bigtable::AsyncRowReader<>::NO_ROWS_LIMIT;

// After
auto limit = google::cloud::bigtable::RowReader::NO_ROWS_LIMIT;

We have removed the bigtable::DataEndpointOption, bigtable::AdminEndpointOption, and bigtable::InstanceAdminEndpointOption classes. Applications should use google::cloud::EndpointOption instead.

Before:

auto options = google::cloud::Options{}.set<google::cloud::bigtable::DataEndpointOption>("...");

After:

auto options = google::cloud::Options{}.set<google::cloud::EndpointOption>("...");

We have removed the bigtable::DataClient class and its associated factory functions (e.g., MakeDataClient). Applications should now use bigtable::DataConnection and bigtable::MakeDataConnection() instead. For detailed migration steps and examples, please refer to the migration guide:

Migrating from DataClient to DataConnection

We have removed the bigtable::MetadataUpdatePolicy class. It was only used in internal legacy files.

We have replaced the bigtable::AdminClient class and bigtable::TableAdmin class with bigtable_admin::BigtableTableAdminClient.

Before:

std::shared_ptr<bigtable::AdminClient> admin_client = 
    bigtable::MakeAdminClient("project-id");
auto table_admin = std::make_unique<bigtable::TableAdmin>(
    admin_client, "instance-id");

// Drop a selection of rows by key prefix.
auto result = table_admin.DropRowByPrefix("table-id", "row-key-prefix");

// Drop all rows.
result = table_admin.DropAllRows("table-id");

After:

#include "google/cloud/bigtable/admin/bigtable_table_admin_client.h"

auto table_admin = bigtable_admin::BigtableTableAdminClient(
    bigtable_admin::MakeBigtableAdminConnection());
auto table_name = bigtable::TableName("project-id", "instance-id", "table-id");

// Drop a selection of rows by key prefix.
google::bigtable::admin::v2::DropRowRangeRequest drop_rows_by_prefix;
drop_rows_by_prefix.set_name(table_name);
drop_rows_by_prefix.set_row_key_prefix("row-key-prefix");
auto result = table_admin.DropRowRange(drop_rows_by_prefix);

// Drop all rows.
google::bigtable::admin::v2::DropRowRangeRequest drop_all_rows;
drop_all_rows.set_name(table_name);
drop_all_rows.set_delete_all_data_from_table(true);
result = table_admin.DropRowRange(drop_all_rows);

With the removal of the bigtable::TableAdmin class, we have moved WaitForConsistency to bigtable_admin::BigtableTableAdminClient::WaitForConsistency.

Before:

std::shared_ptr<bigtable::AdminClient> admin_client = 
    bigtable::MakeAdminClient("project-id");
auto table_admin = std::make_unique<bigtable::TableAdmin>(
    admin_client, "instance-id");

auto token = table_admin.GenerateConsistencyToken("table-id");
if (!token) throw std::runtime_error(token.status().message());
auto result = table_admin.WaitForConsistency("table-id", *token);

After:

#include "google/cloud/bigtable/admin/bigtable_table_admin_client.h"

auto connection = bigtable_admin::MakeBigtableAdminConnection();
auto table_admin = bigtable_admin::BigtableTableAdminClient(connection);
auto table_name = bigtable::TableName("project-id", "instance-id", "table-id");

auto token = table_admin.GenerateConsistencyToken(table_name);
if (!token) throw std::runtime_error(token.status().message());

google::bigtable::admin::v2::CheckConsistencyRequest wait_request;
wait_request.set_name(table_name);
wait_request.set_consistency_token(token->consistency_token());
auto wait_response = table_admin.WaitForConsistency(wait_request).get();

We have replaced the bigtable::InstanceAdminClient class and bigtable::InstanceAdmin class with bigtable_admin::BigtableInstanceAdminClient.

Before:

auto instance_admin_client = bigtable::MakeInstanceAdminClient("project-id");
auto instance_admin =
    std::make_unique<bigtable::InstanceAdmin>(instance_admin_client);

auto clusters = instance_admin->ListClusters();

After:

#include "google/cloud/bigtable/admin/bigtable_instance_admin_client.h"

auto instance_admin =
        std::make_unique<bigtable_admin::BigtableInstanceAdminClient>(
            bigtable_admin::MakeBigtableInstanceAdminConnection());

auto clusters = instance_admin->ListClusters(
    InstanceName("project-id", "instance-id"));

The library no longer exposes google/cloud/iam/retry_traits.h header file. It only contained internal symbols.

We have removed the deprecated pubsub::PublisherOptions. Please use google::cloud::Options instead.

The following table shows the mapping from pubsub::PublisherOptions methods to their google::cloud::Options equivalents:

Example usage of the replacements can be found below.

Before:

namespace gc = ::google::cloud;
namespace pubsub = ::google::cloud::pubsub;

auto publisher_options = pubsub::PublisherOptions{}
    .enable_message_ordering()
    .set_full_publisher_ignored();

auto publisher = pubsub::Publisher(pubsub::MakePublisherConnection(
    topic, publisher_options);

After:

namespace gc = ::google::cloud;
namespace pubsub = ::google::cloud::pubsub;

auto options = gc::Options{}
    .set<pubsub::MessageOrderingOption>(true)
    .set<pubsub::FullPublisherActionOption>(
        pubsub::FullPublisherAction::kIgnored);

auto publisher = pubsub::Publisher(pubsub::MakePublisherConnection(
    topic, options));

We have removed the deprecated pubsub::SubscriberOptions. Please use google::cloud::Options instead.

The following table shows the mapping from pubsub::SubscriberOptions methods to their google::cloud::Options equivalents:

Example usage of the replacements can be found below.

Before:

namespace gc = ::google::cloud;
namespace pubsub = ::google::cloud::pubsub;

auto subscriber_options = pubsub::SubscriberOptions{}
    .set_max_deadline_time(std::chrono::seconds(10))
    .set_max_outstanding_messages(42);

auto subscriber = pubsub::Subscriber(pubsub::MakeSubscriberConnection(
    subscription, subscriber_options);

After:

namespace gc = ::google::cloud;
namespace pubsub = ::google::cloud::pubsub;

auto options = gc::Options{}
    .set<pubsub::MaxDeadlineTimeOption>(std::chrono::seconds(10))
    .set<pubsub::MaxOutstandingMessagesOption>(42);

auto subscriber = pubsub::Subscriber(pubsub::MakeSubscriberConnection(
    subscription, options));

The Spanner library now ignores all SessionPool related options, which are marked as deprecated and will be removed in the future:

• EnableMultiplexedSessionOption
• SessionPoolMinSessionsOption
• SessionPoolMaxSessionsPerChannelOption
• SessionPoolMaxIdleSessionsOption
• SessionPoolActionOnExhaustionOption
• SessionPoolKeepAliveIntervalOption

We have removed the spanner::MakeTestRow functions. Please use spanner_mocks::MakeRow instead.

Before:

#include "google/cloud/spanner/row.h"

// ...

auto row = google::cloud::spanner::MakeTestRow(
    {{"c0", google::cloud::spanner::Value(42)}});
auto row2 = google::cloud::spanner::MakeTestRow(1, "foo", true);

After:

#include "google/cloud/spanner/mocks/row.h"

// ...

auto row = google::cloud::spanner_mocks::MakeRow(
    {{"c0", google::cloud::spanner::Value(42)}});
auto row2 = google::cloud::spanner_mocks::MakeRow(1, "foo", true);

We have removed the spanner::ClientOptions class. Use google::cloud::Options instead to set the following as needed:

• spanner::QueryOptimizerVersionOption
• spanner::QueryOptimizerStatisticsPackageOption
• spanner::RequestPriorityOption
• spanner::RequestTagOption

Before:

#include "google/cloud/spanner/client.h"

// ...

namespace spanner = ::google::cloud::spanner;
auto client_options = spanner::ClientOptions().set_query_options(
    spanner::QueryOptions().set_optimizer_version("1"));

auto client = spanner::Client(connection, client_options);

After:

#include "google/cloud/spanner/client.h"
#include "google/cloud/spanner/options.h"

// ...

namespace spanner = ::google::cloud::spanner;
auto options = google::cloud::Options{}.set<spanner::QueryOptimizerVersionOption>("1");

auto client = spanner::Client(connection, options);

The library no longer exposes google/cloud/spanner/admin/retry_traits.h header file. It only contained internal symbols.

We have removed the DatabaseAdminClient and InstanceAdminClient classes (and their associated connection classes and factory functions) from the google::cloud::spanner namespace. Please use the replacements in google::cloud::spanner_admin.

Before:

#include "google/cloud/spanner/database_admin_client.h"
#include "google/cloud/spanner/instance_admin_client.h"

namespace spanner = ::google::cloud::spanner;

void Function(spanner::DatabaseAdminClient db_admin,
              spanner::InstanceAdminClient in_admin) {
  // ...
}

After:

#include "google/cloud/spanner/admin/database_admin_client.h"
#include "google/cloud/spanner/admin/instance_admin_client.h"

namespace spanner_admin = ::google::cloud::spanner_admin;

void Function(spanner_admin::DatabaseAdminClient db_admin,
              spanner_admin::InstanceAdminClient in_admin) {
  // ...
}

The ClientOptions class is no longer available. You should now use google::cloud::Options to configure the Client.

Before:

#include "google/cloud/storage/client.h"

void CreateClient() {
  auto credentials = google::cloud::storage::oauth2::GoogleDefaultCredentials().value();
  auto options = google::cloud::storage::ClientOptions(credentials);
  options.set_project_id("my-project");
  options.set_upload_buffer_size(1024 * 1024);

  google::cloud::storage::Client client(options);
}

After:

#include "google/cloud/storage/client.h"
#include "google/cloud/storage/options.h" // For option structs

void CreateClient() {
  auto credentials = google::cloud::MakeGoogleDefaultCredentials();
  auto client = google::cloud::storage::Client(
      google::cloud::Options{}
          .set<google::cloud::Oauth2CredentialsOption>(credentials)
          .set<google::cloud::storage::ProjectIdOption>("my-project")
          .set<google::cloud::storage::UploadBufferSizeOption>(1024 * 1024));
}

Use the following table to map ClientOptions setters to google::cloud::Options:

Example for Tracing:

// Before
options.set_enable_http_tracing(true);

// After
auto opts = Options{}.lookup<LoggingComponentsOption>().insert("raw-client");

The ChannelOptions class is no longer available. You should now use google::cloud::Options to configure the transport channel.

Before:

#include "google/cloud/storage/grpc_plugin.h"

void CreateClient() {
  auto options = google::cloud::storage::ChannelOptions()
      .set_ssl_root_path("path/to/roots.pem");

  auto client = google::cloud::storage::MakeGrpcClient(
      google::cloud::storage::ClientOptions(), options);
}

After:

#include "google/cloud/storage/grpc_plugin.h"
#include "google/cloud/grpc_options.h"
#include "google/cloud/common_options.h"

void CreateClient() {
  auto client = google::cloud::storage::MakeGrpcClient(
      google::cloud::Options{}.set<google::cloud::CARootsFilePathOption>(
          "path/to/roots.pem"));
}

Use the following table to map ChannelOptions setters to google::cloud::Options:

We have removed the Client(ClientOptions) constructor. The default constructor Client() generally uses default options and default credentials. To customize, use Client(Options).

Before:

#include "google/cloud/storage/client.h"

void CreateClient() {
  auto credentials = google::cloud::storage::oauth2::GoogleDefaultCredentials().value();
  auto options = google::cloud::storage::ClientOptions(credentials);
  auto client = google::cloud::storage::Client(options);
}

After:

#include "google/cloud/storage/client.h"
#include "google/cloud/storage/options.h"

void CreateClient() {
  auto credentials = google::cloud::MakeGoogleDefaultCredentials();
  auto client = google::cloud::storage::Client(
      google::cloud::Options{}.set<google::cloud::storage::Oauth2CredentialsOption>(credentials));
}

We have removed the Client constructor that accepted a StorageConnection and the NoDecorations tag. This was intended only for test code.

Before:

#include "google/cloud/storage/client.h"
#include "google/cloud/storage/testing/mock_storage_connection.h"

void TestClient() {
  auto mock = std::make_shared<google::cloud::storage::testing::MockStorageConnection>();
  // ...
  auto client = google::cloud::storage::Client(
      mock, google::cloud::storage::Client::NoDecorations{});
}

After:

#include "google/cloud/storage/client.h"
#include "google/cloud/storage/testing/mock_storage_connection.h"

void TestClient() {
  auto mock = std::make_shared<google::cloud::storage::testing::MockStorageConnection>();
  // ...
  auto client = google::cloud::storage::internal::ClientImplDetails::CreateWithoutDecorations(mock);
}

We have removed the Client::raw_client() method. This was intended only for internal use or testing. If you need access to the underlying connection for testing purposes, use google::cloud::storage::internal::ClientImplDetails.

Before:

#include "google/cloud/storage/client.h"

void UseRawClient(google::cloud::storage::Client client) {
  auto connection = client.raw_client();
}

After:

#include "google/cloud/storage/client.h"

void UseRawClient(google::cloud::storage::Client client) {
  auto connection =
      google::cloud::storage::internal::ClientImplDetails::GetConnection(client);
}

The storage_experimental::GrpcPluginOption is no longer necessary. Instead of calling storage_experimental::DefaultGrpcClient now call storage::MakeGrpcClient

Before:

#include "google/cloud/storage/grpc_plugin.h"
namespace gc = ::google::cloud;

auto options = gc::Options{}
    .set<gc::storage_experimental::GrpcPluginOption>("media");
auto client = gc::storage_experimental::DefaultGrpcClient(options);

After:

#include "google/cloud/storage/grpc_plugin.h"
namespace gc = ::google::cloud;

auto client = gc::storage::MakeGrpcClient();

CMake should now link to google-cloud-cpp::storage_grpc.

Bazel should now depend on @google_cloud_cpp//:storage_grpc

You should use the google::cloud::UnifiedCredentialsOption and the unified credentials API documented at https://docs.cloud.google.com/cpp/docs/reference/common/latest/group__guac instead.

Before:

#include "google/cloud/options.h"
#include "google/cloud/storage/client.h"
#include "google/cloud/storage/oauth2/google_credentials.h"

namespace gc = ::google::cloud;
namespace gcs = ::google::cloud::storage;
namespace oauth2 = ::google::cloud::storage::oauth2;

auto options = gc::Options{}
    .set<gcs::Oauth2CredentialsOption>(oauth2::CreateAnonymousCredentials());
auto client = gcs::Client(options);

After:

#include "google/cloud/options.h"
#include "google/cloud/storage/client.h"
#include "google/cloud/credentials.h"

namespace gc = ::google::cloud;
namespace gcs = ::google::cloud::storage;

auto options = gc::Options{}
    .set<gc::UnifiedCredentialsOption>(gc::MakeInsecureCredentials());
auto client = gcs::Client(options);

You should use the google::cloud::MakeServiceAccountCredentialsFromFile factory function and associated override options google::cloud::ScopesOption and google::cloud::subjectOption instead.

Before:

#include "google/cloud/options.h"
#include "google/cloud/storage/client.h"
#include "google/cloud/storage/oauth2/google_credentials.h"

namespace gc = ::google::cloud;
namespace gcs = ::google::cloud::storage;
namespace oauth2 = ::google::cloud::storage::oauth2;

std::set<std::string> scopes = {"scope1", "scope2"};
auto credentials = CreateServiceAccountCredentialsFromFilePath(
    "path-to-file", scopes, "my-subject");

auto options = gc::Options{}
    .set<gcs::Oauth2CredentialsOption>(credentials);
auto client = gcs::Client(options);

After:

#include "google/cloud/options.h"
#include "google/cloud/storage/client.h"
#include "google/cloud/credentials.h"

namespace gc = ::google::cloud;
namespace gcs = ::google::cloud::storage;

auto options = gc::Options{}
    .set<gc::ScopesOption>(std::vector<std::string>({"scope1", "scope2"}))
    .set<gc::SubjectOption>("my-subject");

options = options.set<gc::UnifiedCredentialsOption>(
    gc::MakeServiceAccountCredentialsFromFile("path-to-file", options));
auto client = gcs::Client(options);