Skip to content

doc(v3): migration guide edits #15950

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
scotthart merged 4 commits into from
Feb 10, 2026
+79 −70
Merged

doc(v3): migration guide edits #15950

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
bcfc2a0
doc(v3): migration guide edits
scotthart Feb 9, 2026
1b1ffc4
address review comments
scotthart Feb 10, 2026
fbeb6a7
edits to change from passive voice to active
scotthart Feb 10, 2026
9778333
remove repetition
scotthart Feb 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
149 changes: 79 additions & 70 deletions doc/v3-migration-guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,29 +1,21 @@
# `google-cloud-cpp` v3 Migration Guide

This document is intended for users of previous major versions (v1.x.y, v2.x.y)
of the `google-cloud-cpp` SDK who are moving to a release on the v3.x.y series.
This document helps users of previous major versions (v1.x.y, v2.x.y) of the
`google-cloud-cpp` SDK migrate to a release on the v3.x.y series.

While this repository does not strictly follow semver, it does use the major
version number to indicate large breaking changes. We strive to balance the
frequency in which we introduce breaking changes with improvements to the SDK.
Since our most recent major version increment, about 3 years ago, we have added
new API surfaces that supersede the previous deprecated types and functions. As
part of the v3 release series, we are decommissioning those deprecated API
surfaces. This guide serves a central location to document how to migrate from
the decommissioned API surfaces to their replacements.
surfaces.

## C++17

Depending on your build system of choice, you should set the appropriate flag
for your compiler if it does not already default to `--std=c++17` or higher.

## Bazel Central Registry

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](https://registry.bazel.build/modules/google_cloud_cpp) Bazel
module which can be added to your `MODULE.bazel` file as a dependency.

## Dependencies

### Previously Optional Dependencies that are now Required
Expand All @@ -34,20 +26,35 @@ module which can be added to your `MODULE.bazel` file as a dependency.

### Relocated Dependencies

- `crc32c`
- `crc32c` google-cloud-cpp now uses the crc32c implementation in Abseil.

## Decommissioned API Surfaces
## Build system changes

### Bazel

<details>
<summary>google-cloud-cpp module in Bazel Central Registry</summary>
Copy link
Contributor

@coryan coryan Feb 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Are you still supporting customers with workspaces? If not, just say that?

Copy link
Member Author

@scotthart scotthart Feb 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Updated to describe WORKSPACE support going forward.


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](https://registry.bazel.build/modules/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.

</details>

### CMake

<details>
<summary>Removed backward compatible proto interface libraries.</summary>

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

| Library | Decommissioned Proto Library | Preferred Proto Library |
| -------------------------- | ------------------------------------- | -------------------------------------- |
Expand All @@ -61,13 +68,15 @@ name.

</details>

## Decommissioned API Surfaces

### Common

<details>
<summary>Removed <code>v1</code> inline namespace alias.
</summary>

The `v1` namespace should be omitted for libraries that are unversioned:
Omit the `v1` namespace for unversioned libraries:

- Bigtable
- PubSub
Expand Down Expand Up @@ -97,8 +106,8 @@ google::cloud::pubsub::Publisher publisher;
<summary>Removed <code>gcpcxxV1</code> inline namespace alias.
</summary>

The `gcpcxxV1` namespace should be omitted from versioned libraries. The version
is now part of the service namespace.
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:

Expand Down Expand Up @@ -152,9 +161,9 @@ google::cloud::CompletionQueue cq;
<summary>Removed unversioned forwarding headers.
</summary>

Some early libraries were created 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:
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
Expand Down Expand Up @@ -276,8 +285,8 @@ file. It only contained internal symbols.
<summary>Removed <code>bigtable::RowReader</code> constructors
</summary>

The `bigtable::RowReader` constructors that accept `DataClient` as an argument
have been removed.
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(...)`.
Expand Down Expand Up @@ -335,7 +344,7 @@ for (auto& row : table.ReadRows(
</summary>
#### `bigtable::ClientOptions`

The deprecated `bigtable::ClientOptions` has been removed. Please use
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
Expand Down Expand Up @@ -384,7 +393,7 @@ auto client = bigtable::Client(

#### `bigtable::CreateDefaultDataClient`

The deprecated `bigtable::CreateDefaultDataClient` function has been removed.
We have removed the deprecated `bigtable::CreateDefaultDataClient` function.
Please use `bigtable::MakeDataClient` instead.

**Before:**
Expand Down Expand Up @@ -467,9 +476,9 @@ auto limit = google::cloud::bigtable::RowReader::NO_ROWS_LIMIT;
<summary>Removed Endpoint Options
</summary>

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

**Before:**

Expand All @@ -488,11 +497,10 @@ auto options = google::cloud::Options{}.set<google::cloud::EndpointOption>("..."
<details>
<summary>Removed <code>bigtable::DataClient</code> and related functions</summary>

The `bigtable::DataClient` class and its associated factory functions (e.g.,
`MakeDataClient`) have been removed. Applications should now use
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 official migration
guide:
detailed migration steps and examples, please refer to the migration guide:

[Migrating from DataClient to DataConnection](https://docs.cloud.google.com/cpp/docs/reference/bigtable/latest/migrating-from-dataclient)

Expand All @@ -501,16 +509,16 @@ guide:
<details>
<summary>Removed <code>bigtable::MetadataUpdatePolicy</code></summary>

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

</details>

<details>
<summary>Removed <code>bigtable::AdminClient</code> and <code>bigtable::TableAdmin</code></summary>

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

**Before:**

Expand Down Expand Up @@ -554,8 +562,9 @@ result = table_admin.DropRowRange(drop_all_rows);

<details><summary><code>WaitForConsistency</code> is now a free function</summary>

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

**Before:**

Expand Down Expand Up @@ -594,8 +603,9 @@ auto wait_response = table_admin.WaitForConsistency(wait_request).get();
<details>
<summary>Removed <code>bigtable::InstanceAdminClient</code> and <code>bigtable::InstanceAdmin</code></summary>

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

**Before:**

Expand All @@ -622,14 +632,25 @@ auto clusters = instance_admin->ListClusters(

</details>

### IAM

<details>

<summary>Removed <code>iam/retry_traits.h</code> file</summary>

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

</details>

### Pubsub

<details>
<summary>Removed <code>pubsub::PublisherOptions</code>
</summary>
#### `pubsub::PublisherOptions`

The deprecated `pubsub::PublisherOptions` has been removed. Please use
We have removed the deprecated `pubsub::PublisherOptions`. Please use
`google::cloud::Options` instead.

The following table shows the mapping from `pubsub::PublisherOptions` methods to
Expand Down Expand Up @@ -687,7 +708,7 @@ auto publisher = pubsub::Publisher(pubsub::MakePublisherConnection(
</summary>
#### `pubsub::SubscriberOptions`

The deprecated `pubsub::SubscriberOptions` has been removed. Please use
We have removed the deprecated `pubsub::SubscriberOptions`. Please use
`google::cloud::Options` instead.

The following table shows the mapping from `pubsub::SubscriberOptions` methods
Expand Down Expand Up @@ -740,8 +761,8 @@ auto subscriber = pubsub::Subscriber(pubsub::MakeSubscriberConnection(
<details>
<summary>All sessions are now Multiplexed Sessions</summary>

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

- `EnableMultiplexedSessionOption`
- `SessionPoolMinSessionsOption`
Expand All @@ -756,7 +777,7 @@ Spanner library and will be removed in the future:
<summary>Removed <code>spanner::MakeTestRow</code>
</summary>

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

**Before:**
Expand Down Expand Up @@ -788,8 +809,8 @@ auto row2 = google::cloud::spanner_mocks::MakeRow(1, "foo", true);
<details>
<summary>Removed <code>spanner::ClientOptions</code> class</summary>

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

- `spanner::QueryOptimizerVersionOption`
- `spanner::QueryOptimizerStatisticsPackageOption`
Expand Down Expand Up @@ -838,8 +859,8 @@ file. It only contained internal symbols.
<details>
<summary>Removed Admin Clients from <code>spanner</code> namespace</summary>

The `DatabaseAdminClient` and `InstanceAdminClient` classes (and their
associated connection classes and factory functions) have been removed from the
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`.

Expand Down Expand Up @@ -990,7 +1011,7 @@ Use the following table to map `ChannelOptions` setters to
<details>
<summary><code>Client</code> Constructor removal</summary>

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

Expand Down Expand Up @@ -1024,8 +1045,8 @@ void CreateClient() {
<details>
<summary>Removed <code>Client(Connection, NoDecorations)</code> constructor</summary>

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

**Before:**

Expand Down Expand Up @@ -1059,7 +1080,7 @@ void TestClient() {
<details>
<summary>Removed <code>Client::raw_client()</code></summary>

The `Client::raw_client()` method has been removed. This was intended only for
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`.

Expand Down Expand Up @@ -1127,10 +1148,10 @@ Bazel should now depend on `@google_cloud_cpp//:storage_grpc`
<details>
<summary>Removed deprecated <code>Oauth2CredentialsOption</code></summary>

The `google::cloud::UnifiedCredentialsOption` and the unified credentials API
documented at
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
should be used instead.
instead.

**Before:**

Expand Down Expand Up @@ -1168,9 +1189,9 @@ auto client = gcs::Client(options);
<details>
<summary>Removed deprecated <code>CreateServiceAccountCredentialsFromFilePath</code></summary>

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

**Before:**

Expand Down Expand Up @@ -1212,15 +1233,3 @@ auto client = gcs::Client(options);
```

</details>

### IAM

<details>

<summary>Removed <code>iam/retry_traits.h</code> file</summary>

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

</details>