docs: Added UPGRADING.md with admin client migration #1201
Conversation
UPGRADING.md
Outdated
|
|
||
| ### Admin Client Migration | ||
|
|
||
| While we do recommend you instantiate the new admin API clients directly, you can access the new admin API |
There was a problem hiding this comment.
We should show how to do it the recommended way first. Maybe something like:
The TableAdminClient can now be imported directly from google.cloud.bigtable.admin. This is the new recommended approach:
from google.cloud.bigtable.admin import TableAdminClient
...
Access to the admin clients throughgoogle.cloud.bigtable.Clientis also supported for backward compatibility:
...
| ### Admin Client Migration | ||
|
|
||
| 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() | ||
| ``` |
There was a problem hiding this comment.
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?
|
|
||
| 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 |
There was a problem hiding this comment.
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.
The changes to
UPGRADING.mdhere builds upon some of the changes toUPGRADING.mdin #1169 with additions for admin client migration.