From 3ddfb0cb285d5a2e2483af697867332f5331f788 Mon Sep 17 00:00:00 2001 From: Kevin Zheng Date: Tue, 26 Aug 2025 20:40:36 +0000 Subject: [PATCH 1/2] docs: Added UPGRADING.md with admin client migration --- UPGRADING.md | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) create mode 100644 UPGRADING.md diff --git a/UPGRADING.md b/UPGRADING.md new file mode 100644 index 000000000..22ad48c14 --- /dev/null +++ b/UPGRADING.md @@ -0,0 +1,36 @@ +# 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.BigtableInstanceAdminClientAsync` + - `google.cloud.bigtable.admin.BigtableTableAdminClient` + - `google.cloud.bigtable.admin.BigtableTableAdminClientAsync` + +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 + +While we do recommend you instantiate the new admin API clients directly, you can access the new admin API +clients via the `google.cloud.bigtable.Client` class: + +``` +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() +``` + +## 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) + +- **[`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`. From 80223f960f0cd34aa656520c980569ba65650ca8 Mon Sep 17 00:00:00 2001 From: Kevin Zheng Date: Wed, 27 Aug 2025 14:23:07 +0000 Subject: [PATCH 2/2] added recommended way --- UPGRADING.md | 24 +++++++++++++++++++----- 1 file changed, 19 insertions(+), 5 deletions(-) diff --git a/UPGRADING.md b/UPGRADING.md index 22ad48c14..35d7343b1 100644 --- a/UPGRADING.md +++ b/UPGRADING.md @@ -6,23 +6,37 @@ The v3.0.0 release of `google-cloud-bigtable` deprecates the previous `google.cl - `google.cloud.bigtable.data.BigtableDataClientAsync` - Admin API: - `google.cloud.bigtable.admin.BigtableInstanceAdminClient` - - `google.cloud.bigtable.admin.BigtableInstanceAdminClientAsync` + - `google.cloud.bigtable.admin.BigtableInstanceAdminAsyncClient` - `google.cloud.bigtable.admin.BigtableTableAdminClient` - - `google.cloud.bigtable.admin.BigtableTableAdminClientAsync` + - `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 -While we do recommend you instantiate the new admin API clients directly, you can access the new admin API -clients via the `google.cloud.bigtable.Client` class: +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()