Skip to content

docs: Added UPGRADING.md with admin client migration #1201

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

Open
wants to merge 2 commits into
base: v3_staging
Choose a base branch
from
Open

docs: Added UPGRADING.md with admin client migration #1201

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3ddfb0c
docs: Added UPGRADING.md with admin client migration
gkevinzheng Aug 26, 2025
80223f9
added recommended way
gkevinzheng Aug 27, 2025
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
50 changes: 50 additions & 0 deletions UPGRADING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,50 @@
# 3.0.0 Migration Guide

The v3.0.0 release of `google-cloud-bigtable` deprecates the previous `google.cloud.bigtable.Client` class in favor of distinct clients for the two API surfaces, supporting both sync and async calls:
- Data API:
- `google.cloud.bigtable.data.BigtableDataClient`
- `google.cloud.bigtable.data.BigtableDataClientAsync`
- Admin API:
- `google.cloud.bigtable.admin.BigtableInstanceAdminClient`
- `google.cloud.bigtable.admin.BigtableInstanceAdminAsyncClient`
- `google.cloud.bigtable.admin.BigtableTableAdminClient`
- `google.cloud.bigtable.admin.BigtableTableAdminAsyncClient`

The deprecated client will remain available as an alternative API surface, which internally delegates calls to the respective new clients. For most users, existing code will continue to work as before. But there may be some breaking changes associated with this update, which are detailed in this document.

### Admin Client Migration
Copy link

@iam-ethan-huang iam-ethan-huang Sep 3, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

Currently it is more like a quick-start guide, instead of the migration guide.

For migration, we should start from the code users have from legacy client and suggest what to do from there.

For example:
Path A (if you have time) - Add new import, remove old import, and convert all methods to new style, rebuild, test.
Path B (if you don't have time, but want to get new features) - Get new client via legacy client and use it.

And indicate the path B is only for backward compatible phase and will be eventually deprecated.


We recommend that you instantiate the new admin API clients directly:

```
from google.cloud.bigtable.admin import (
BigtableInstanceAdminClient,
BigtableInstanceAdminAsyncClient,
BigtableTableAdminClient,
BigtableTableAdminAsyncClient,
)

instance_admin_client = BigtableInstanceAdminClient()
instance_admin_async_client = BigtableInstanceAdminAsyncClient()
table_admin_client = BigtableTableAdminClient()
table_admin_async_client = BigtableTableAdminAsyncClient()
```

Access to the new admin API sync clients via the `google.cloud.bigtable.Client` class is also supported for backwards compatibility:

```
from google.cloud.bigtable import Client

client = Client()

# google.cloud.bigtable.admin.BigtableInstanceAdminClient
instance_admin_client = client.instance_admin_client()

# google.cloud.bigtable.admin.BigtableTableAdminClient
table_admin_client = client.table_admin_client()
```
Comment on lines +15 to +45
Copy link

Choose a reason for hiding this comment

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

What if user add new client with the future-proof import, in addition to existing client like the following?

i.e.

# User's existing code

from google.cloud.bigtable import Client
client = Client()
instance_admin_client = client.instance_admin_client()

# Added new code to try out the "correct way" of importing new client"
from google.cloud.bigtable.admin import BigtableInstanceAdminClient
instance_admin_client_new = BigtableInstanceAdminClient()

I guess this technically would create two clients which we don't want?


## Breaking Changes
- **[MutationBatcher](https://github.com/googleapis/python-bigtable/blob/main/google/cloud/bigtable/data/_sync_autogen/mutations_batcher.py#L151)and [MutationBatcherAsync](https://github.com/googleapis/python-bigtable/blob/main/google/cloud/bigtable/data/_async/mutations_batcher.py#L182)'s `table` argument was renamed to `target`**, since it also supports [Authorized View](https://github.com/googleapis/python-bigtable/pull/1034) instances. This matches the naming used in other classes (PR: https://github.com/googleapis/python-bigtable/pull/1153)
<!-- TODO: Replace Github link once the feature branch is merged -->
- **[`BigtableTableAdminClient`/`BigtableTableAdminAsyncClient`](https://github.com/googleapis/python-bigtable/blob/main/google/cloud/bigtable_admin_v2/overlay/services/bigtable_table_admin)'s location was changed from `google.cloud.bigtable_admin_v2.services.bigtable_table_admin` to `google.cloud.bigtable_admin_v2.overlay.services.bigtable_table_admin`**. This should not affect you if you are importing these clients via `import google.cloud.bigtable_admin_v2` due to import aliasing, but will affect you if you are importing these clients via `import google.cloud.bigtable_admin_v2.services.bigtable_table_admin`.
Loading