As of January 1, 2020 this library no longer supports Python 2 on the latest released version. Library versions released prior to that date will continue to be available. For more information please visit Python 2 support on Google Cloud.

Spanner Client

Parent client for calling the Cloud Spanner API.

This is the base from which all interactions with the API occur.

In the hierarchy of API concepts

class google.cloud.spanner_v1.client.Client(project=None, credentials=None, client_info=<google.api_core.gapic_v1.client_info.ClientInfo object>, client_options=None, query_options=None, route_to_leader_enabled=True, directed_read_options=None)[source]

Bases: google.cloud.client.ClientWithProject

Client for interacting with Cloud Spanner API.

Note

Since the Cloud Spanner API requires the gRPC transport, no _http argument is accepted by this class.

Parameters

  • project (str or unicode) – (Optional) The ID of the project which owns the instances, tables and data. If not provided, will attempt to determine from the environment.

  • credentials (Credentials or NoneType) – (Optional) The authorization credentials to attach to requests. These credentials identify this application to the service. If none are specified, the client will attempt to ascertain the credentials from the environment.

  • client_info (ClientInfo) – (Optional) The client info used to send a user-agent string along with API requests. If None, then default info will be used. Generally, you only need to set this if you’re developing your own library or partner tool.

  • client_options (ClientOptions or dict) – (Optional) Client options used to set user options on the client. API Endpoint should be set through client_options.

  • query_options (QueryOptions or dict) – (Optional) Query optimizer configuration to use for the given query. If a dict is provided, it must be of the same form as the protobuf message QueryOptions

  • route_to_leader_enabled (boolean) – (Optional) Default True. Set route_to_leader_enabled as False to disable leader aware routing. Disabling leader aware routing would route all requests in RW/PDML transactions to the closest region.

  • directed_read_options (DirectedReadOptions or dict) – (Optional) Client options used to set the directed_read_options for all ReadRequests and ExecuteSqlRequests that indicates which replicas or regions should be used for non-transactional reads or queries.

Raises

ValueError if both read_only and admin are True

SCOPE: Union[Tuple[str, ...], None] = ('https://www.googleapis.com/auth/spanner.admin',)

The scopes required for Google Cloud Spanner.

copy()[source]

Make a copy of this client.

Copies the local data stored as simple types but does not copy the current state of any open connections with the Cloud Bigtable API.

Return type

Client

Returns

A copy of the current client.

property credentials

Getter for client’s credentials.

Return type

Credentials

Returns

The credentials stored on the client.

property database_admin_api

Helper for session-related API calls.

property directed_read_options

Getter for directed_read_options.

Return type

DirectedReadOptions or dict

Returns

The directed_read_options for the client.

instance(instance_id, configuration_name=None, display_name=None, node_count=None, labels=None, processing_units=None)[source]

Factory to create a instance associated with this client.

Parameters

  • instance_id (str) – The ID of the instance.

  • configuration_name (string) – (Optional) Name of the instance configuration used to set up the instance’s cluster, in the form: projects/<project>/instanceConfigs/ <config>. Required for instances which do not yet exist.

  • display_name (str) – (Optional) The display name for the instance in the Cloud Console UI. (Must be between 4 and 30 characters.) If this value is not set in the constructor, will fall back to the instance ID.

  • node_count (int) – (Optional) The number of nodes in the instance’s cluster; used to set up the instance’s cluster.

  • processing_units (int) – (Optional) The number of processing units allocated to this instance.

  • labels (dict (str -> str) or None) – (Optional) User-assigned labels for this instance.

Return type

Instance

Returns

an instance owned by this client.

property instance_admin_api

Helper for session-related API calls.

list_instance_configs(page_size=None)[source]

List available instance configurations for the client’s project.

See RPC docs.

Parameters

page_size (int) – Optional. The maximum number of configs in each page of results from this request. Non-positive values are ignored. Defaults to a sensible value set by the API.

Return type

Iterator

Returns

Iterator of InstanceConfig resources within the client’s project.

list_instances(filter_='', page_size=None)[source]

List instances for the client’s project.

See https://cloud.google.com/spanner/reference/rpc/google.spanner.admin.database.v1#google.spanner.admin.database.v1.InstanceAdmin.ListInstances

Parameters

  • filter (string) – (Optional) Filter to select instances listed. See the ListInstancesRequest docs above for examples.

  • page_size (int) – Optional. The maximum number of instances in each page of results from this request. Non-positive values are ignored. Defaults to a sensible value set by the API.

Return type

Iterator

Returns

Iterator of Instance resources within the client’s project.

property project_name

Project name to be used with Spanner APIs.

Note

This property will not change if project does not, but the return value is not cached.

The project name is of the form

"projects/{project}"

Return type

str

Returns

The project name to be used with the Cloud Spanner Admin API RPC service.

property route_to_leader_enabled

Getter for if read-write or pdml requests will be routed to leader.

Return type

boolean

Returns

If read-write requests will be routed to leader.