Class DatabaseAdminClient (1.10.0) 

DatabaseAdminClient(
    transport=None,
    channel=None,
    credentials=None,
    client_config=None,
    client_info=None,
    client_options=None,
)

Cloud Spanner Database Admin API

The Cloud Spanner Database Admin API can be used to create, drop, and list databases. It also enables updating the schema of pre-existing databases.

Methods

DatabaseAdminClient

DatabaseAdminClient(
    transport=None,
    channel=None,
    credentials=None,
    client_config=None,
    client_info=None,
    client_options=None,
)

Constructor.

Parameters
NameDescription
channel grpc.Channel

DEPRECATED. A Channel instance through which to make calls. This argument is mutually exclusive with credentials; providing both will raise an exception.

credentials google.auth.credentials.Credentials

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. This argument is mutually exclusive with providing a transport instance to transport; doing so will raise an exception.

client_config dict

DEPRECATED. A dictionary of call options for each method. If not specified, the default configuration is used.

client_info google.api_core.gapic_v1.client_info.ClientInfo

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 client library.

client_options Union[dict, google.api_core.client_options.ClientOptions]

Client options used to set user options on the client. API Endpoint should be set through client_options.

create_database

create_database(parent, create_statement, extra_statements=None, retry=<_MethodDefault._DEFAULT_VALUE: <object object>>, timeout=<_MethodDefault._DEFAULT_VALUE: <object object>>, metadata=None)

Creates a new Cloud Spanner database and starts to prepare it for serving. The returned long-running operation will have a name of the format <database_name>/operations/<operation_id> and can be used to track preparation of the database. The metadata field type is CreateDatabaseMetadata. The response field type is Database, if successful.

.. rubric:: Example

from google.cloud import spanner_admin_database_v1

client = spanner_admin_database_v1.DatabaseAdminClient()

parent = client.instance_path('[PROJECT]', '[INSTANCE]')

TODO: Initialize create_statement:

create_statement = ''

response = client.create_database(parent, create_statement)

def callback(operation_future): ... # Handle result. ... result = operation_future.result()

response.add_done_callback(callback)

Handle metadata.

metadata = response.metadata()

Parameters
NameDescription
parent str

Required. The name of the instance that will serve the new database. Values are of the form projects/.

create_statement str

Required. A CREATE DATABASE statement, which specifies the ID of the new database. The database ID must conform to the regular expression [a-z][a-z0-9_-]*[a-z0-9] and be between 2 and 30 characters in length. If the database ID is a reserved word or if it contains a hyphen, the database ID must be enclosed in backticks (`````).

extra_statements list[str]

An optional list of DDL statements to run inside the newly created database. Statements can create tables, indexes, etc. These statements execute atomically with the creation of the database: if there is an error in any statement, the database is not created.

retry Optional[google.api_core.retry.Retry]

A retry object used to retry requests. If None is specified, requests will not be retried.

timeout Optional[float]

The amount of time, in seconds, to wait for the request to complete. Note that if retry is specified, the timeout applies to each individual attempt.

metadata Optional[Sequence[Tuple[str, str]]]

Additional metadata that is provided to the method.

Exceptions
TypeDescription
google.api_core.exceptions.GoogleAPICallErrorIf the request failed for any reason.
google.api_core.exceptions.RetryErrorIf the request failed due to a retryable error and retry attempts failed.
ValueErrorIf the parameters are invalid.

database_path

database_path(project, instance, database)

Return a fully-qualified database string.

drop_database

drop_database(database, retry=<_MethodDefault._DEFAULT_VALUE: <object object>>, timeout=<_MethodDefault._DEFAULT_VALUE: <object object>>, metadata=None)

Drops (aka deletes) a Cloud Spanner database.

.. rubric:: Example

from google.cloud import spanner_admin_database_v1

client = spanner_admin_database_v1.DatabaseAdminClient()

database = client.database_path('[PROJECT]', '[INSTANCE]', '[DATABASE]')

client.drop_database(database)

Parameters
NameDescription
database str

Required. The database to be dropped.

retry Optional[google.api_core.retry.Retry]

A retry object used to retry requests. If None is specified, requests will not be retried.

timeout Optional[float]

The amount of time, in seconds, to wait for the request to complete. Note that if retry is specified, the timeout applies to each individual attempt.

metadata Optional[Sequence[Tuple[str, str]]]

Additional metadata that is provided to the method.

Exceptions
TypeDescription
google.api_core.exceptions.GoogleAPICallErrorIf the request failed for any reason.
google.api_core.exceptions.RetryErrorIf the request failed due to a retryable error and retry attempts failed.
ValueErrorIf the parameters are invalid.

from_service_account_file

from_service_account_file(filename, *args, **kwargs)

Creates an instance of this client using the provided credentials file.

Parameter
NameDescription
filename str

The path to the service account private key json file.

Returns
TypeDescription
DatabaseAdminClientThe constructed client.

from_service_account_json

from_service_account_json(filename, *args, **kwargs)

Creates an instance of this client using the provided credentials file.

Parameter
NameDescription
filename str

The path to the service account private key json file.

Returns
TypeDescription
DatabaseAdminClientThe constructed client.

get_database

get_database(name, retry=<_MethodDefault._DEFAULT_VALUE: <object object>>, timeout=<_MethodDefault._DEFAULT_VALUE: <object object>>, metadata=None)

Gets the state of a Cloud Spanner database.

.. rubric:: Example

from google.cloud import spanner_admin_database_v1

client = spanner_admin_database_v1.DatabaseAdminClient()

name = client.database_path('[PROJECT]', '[INSTANCE]', '[DATABASE]')

response = client.get_database(name)

Parameters
NameDescription
name str

Required. The name of the requested database. Values are of the form projects/.

retry Optional[google.api_core.retry.Retry]

A retry object used to retry requests. If None is specified, requests will not be retried.

timeout Optional[float]

The amount of time, in seconds, to wait for the request to complete. Note that if retry is specified, the timeout applies to each individual attempt.

metadata Optional[Sequence[Tuple[str, str]]]

Additional metadata that is provided to the method.

Exceptions
TypeDescription
google.api_core.exceptions.GoogleAPICallErrorIf the request failed for any reason.
google.api_core.exceptions.RetryErrorIf the request failed due to a retryable error and retry attempts failed.
ValueErrorIf the parameters are invalid.

get_database_ddl

get_database_ddl(database, retry=<_MethodDefault._DEFAULT_VALUE: <object object>>, timeout=<_MethodDefault._DEFAULT_VALUE: <object object>>, metadata=None)

Returns the schema of a Cloud Spanner database as a list of formatted DDL statements. This method does not show pending schema updates, those may be queried using the Operations API.

.. rubric:: Example

from google.cloud import spanner_admin_database_v1

client = spanner_admin_database_v1.DatabaseAdminClient()

database = client.database_path('[PROJECT]', '[INSTANCE]', '[DATABASE]')

response = client.get_database_ddl(database)

Parameters
NameDescription
database str

Required. The database whose schema we wish to get.

retry Optional[google.api_core.retry.Retry]

A retry object used to retry requests. If None is specified, requests will not be retried.

timeout Optional[float]

The amount of time, in seconds, to wait for the request to complete. Note that if retry is specified, the timeout applies to each individual attempt.

metadata Optional[Sequence[Tuple[str, str]]]

Additional metadata that is provided to the method.

Exceptions
TypeDescription
google.api_core.exceptions.GoogleAPICallErrorIf the request failed for any reason.
google.api_core.exceptions.RetryErrorIf the request failed due to a retryable error and retry attempts failed.
ValueErrorIf the parameters are invalid.

get_iam_policy

get_iam_policy(resource, options_=None, retry=<_MethodDefault._DEFAULT_VALUE: <object object>>, timeout=<_MethodDefault._DEFAULT_VALUE: <object object>>, metadata=None)

Gets the access control policy for a database resource. Returns an empty policy if a database exists but does not have a policy set.

Authorization requires spanner.databases.getIamPolicy permission on resource.

.. rubric:: Example

from google.cloud import spanner_admin_database_v1

client = spanner_admin_database_v1.DatabaseAdminClient()

resource = client.database_path('[PROJECT]', '[INSTANCE]', '[DATABASE]')

response = client.get_iam_policy(resource)

Parameters
NameDescription
resource str

REQUIRED: The resource for which the policy is being requested. See the operation documentation for the appropriate value for this field.

options_ Union[dict, GetPolicyOptions]

OPTIONAL: A GetPolicyOptions object for specifying options to GetIamPolicy. This field is only used by Cloud IAM. If a dict is provided, it must be of the same form as the protobuf message GetPolicyOptions

retry Optional[google.api_core.retry.Retry]

A retry object used to retry requests. If None is specified, requests will not be retried.

timeout Optional[float]

The amount of time, in seconds, to wait for the request to complete. Note that if retry is specified, the timeout applies to each individual attempt.

metadata Optional[Sequence[Tuple[str, str]]]

Additional metadata that is provided to the method.

Exceptions
TypeDescription
google.api_core.exceptions.GoogleAPICallErrorIf the request failed for any reason.
google.api_core.exceptions.RetryErrorIf the request failed due to a retryable error and retry attempts failed.
ValueErrorIf the parameters are invalid.

instance_path

instance_path(project, instance)

Return a fully-qualified instance string.

list_databases

list_databases(parent, page_size=None, retry=<_MethodDefault._DEFAULT_VALUE: <object object>>, timeout=<_MethodDefault._DEFAULT_VALUE: <object object>>, metadata=None)

Lists Cloud Spanner databases.

.. rubric:: Example

from google.cloud import spanner_admin_database_v1

client = spanner_admin_database_v1.DatabaseAdminClient()

parent = client.instance_path('[PROJECT]', '[INSTANCE]')

Iterate over all results

for element in client.list_databases(parent): ... # process element ... pass

Alternatively:

Iterate over results one page at a time

for page in client.list_databases(parent).pages: ... for element in page: ... # process element ... pass

Parameters
NameDescription
parent str

Required. The instance whose databases should be listed. Values are of the form projects/.

page_size int

The maximum number of resources contained in the underlying API response. If page streaming is performed per- resource, this parameter does not affect the return value. If page streaming is performed per-page, this determines the maximum number of resources in a page.

retry Optional[google.api_core.retry.Retry]

A retry object used to retry requests. If None is specified, requests will not be retried.

timeout Optional[float]

The amount of time, in seconds, to wait for the request to complete. Note that if retry is specified, the timeout applies to each individual attempt.

metadata Optional[Sequence[Tuple[str, str]]]

Additional metadata that is provided to the method.

Exceptions
TypeDescription
google.api_core.exceptions.GoogleAPICallErrorIf the request failed for any reason.
google.api_core.exceptions.RetryErrorIf the request failed due to a retryable error and retry attempts failed.
ValueErrorIf the parameters are invalid.

set_iam_policy

set_iam_policy(resource, policy, retry=<_MethodDefault._DEFAULT_VALUE: <object object>>, timeout=<_MethodDefault._DEFAULT_VALUE: <object object>>, metadata=None)

Sets the access control policy on a database resource. Replaces any existing policy.

Authorization requires spanner.databases.setIamPolicy permission on resource.

.. rubric:: Example

from google.cloud import spanner_admin_database_v1

client = spanner_admin_database_v1.DatabaseAdminClient()

resource = client.database_path('[PROJECT]', '[INSTANCE]', '[DATABASE]')

TODO: Initialize policy:

policy = {}

response = client.set_iam_policy(resource, policy)

Parameters
NameDescription
resource str

REQUIRED: The resource for which the policy is being specified. See the operation documentation for the appropriate value for this field.

policy Union[dict, Policy]

REQUIRED: The complete policy to be applied to the resource. The size of the policy is limited to a few 10s of KB. An empty policy is a valid policy but certain Cloud Platform services (such as Projects) might reject them. If a dict is provided, it must be of the same form as the protobuf message Policy

retry Optional[google.api_core.retry.Retry]

A retry object used to retry requests. If None is specified, requests will not be retried.

timeout Optional[float]

The amount of time, in seconds, to wait for the request to complete. Note that if retry is specified, the timeout applies to each individual attempt.

metadata Optional[Sequence[Tuple[str, str]]]

Additional metadata that is provided to the method.

Exceptions
TypeDescription
google.api_core.exceptions.GoogleAPICallErrorIf the request failed for any reason.
google.api_core.exceptions.RetryErrorIf the request failed due to a retryable error and retry attempts failed.
ValueErrorIf the parameters are invalid.

test_iam_permissions

test_iam_permissions(resource, permissions, retry=<_MethodDefault._DEFAULT_VALUE: <object object>>, timeout=<_MethodDefault._DEFAULT_VALUE: <object object>>, metadata=None)

Returns permissions that the caller has on the specified database resource.

Attempting this RPC on a non-existent Cloud Spanner database will result in a NOT_FOUND error if the user has spanner.databases.list permission on the containing Cloud Spanner instance. Otherwise returns an empty set of permissions.

.. rubric:: Example

from google.cloud import spanner_admin_database_v1

client = spanner_admin_database_v1.DatabaseAdminClient()

resource = client.database_path('[PROJECT]', '[INSTANCE]', '[DATABASE]')

TODO: Initialize permissions:

permissions = []

response = client.test_iam_permissions(resource, permissions)

Parameters
NameDescription
resource str

REQUIRED: The resource for which the policy detail is being requested. See the operation documentation for the appropriate value for this field.

permissions list[str]

The set of permissions to check for the resource. Permissions with wildcards (such as '' or 'storage.') are not allowed. For more information see IAM Overview https://cloud.google.com/iam/docs/overview#permissions__.

retry Optional[google.api_core.retry.Retry]

A retry object used to retry requests. If None is specified, requests will not be retried.

timeout Optional[float]

The amount of time, in seconds, to wait for the request to complete. Note that if retry is specified, the timeout applies to each individual attempt.

metadata Optional[Sequence[Tuple[str, str]]]

Additional metadata that is provided to the method.

Exceptions
TypeDescription
google.api_core.exceptions.GoogleAPICallErrorIf the request failed for any reason.
google.api_core.exceptions.RetryErrorIf the request failed due to a retryable error and retry attempts failed.
ValueErrorIf the parameters are invalid.

update_database_ddl

update_database_ddl(database, statements, operation_id=None, retry=<_MethodDefault._DEFAULT_VALUE: <object object>>, timeout=<_MethodDefault._DEFAULT_VALUE: <object object>>, metadata=None)

Updates the schema of a Cloud Spanner database by creating/altering/dropping tables, columns, indexes, etc. The returned long-running operation will have a name of the format <database_name>/operations/<operation_id> and can be used to track execution of the schema change(s). The metadata field type is UpdateDatabaseDdlMetadata. The operation has no response.

.. rubric:: Example

from google.cloud import spanner_admin_database_v1

client = spanner_admin_database_v1.DatabaseAdminClient()

database = client.database_path('[PROJECT]', '[INSTANCE]', '[DATABASE]')

TODO: Initialize statements:

statements = []

response = client.update_database_ddl(database, statements)

def callback(operation_future): ... # Handle result. ... result = operation_future.result()

response.add_done_callback(callback)

Handle metadata.

metadata = response.metadata()

Parameters
NameDescription
database str

Required. The database to update.

statements list[str]

DDL statements to be applied to the database.

operation_id str

If empty, the new update request is assigned an automatically-generated operation ID. Otherwise, operation_id is used to construct the name of the resulting Operation. Specifying an explicit operation ID simplifies determining whether the statements were executed in the event that the UpdateDatabaseDdl call is replayed, or the return value is otherwise lost: the database and operation_id fields can be combined to form the name of the resulting longrunning.Operation: . operation_id should be unique within the database, and must be a valid identifier: `<code>a-z][a-z0-9_]</code>*. Note that automatically-generated operation IDs always begin with an underscore. If the named operation already exists, UpdateDatabaseDdl returns ALREADY_EXISTS`.

retry Optional[google.api_core.retry.Retry]

A retry object used to retry requests. If None is specified, requests will not be retried.

timeout Optional[float]

The amount of time, in seconds, to wait for the request to complete. Note that if retry is specified, the timeout applies to each individual attempt.

metadata Optional[Sequence[Tuple[str, str]]]

Additional metadata that is provided to the method.

Exceptions
TypeDescription
google.api_core.exceptions.GoogleAPICallErrorIf the request failed for any reason.
google.api_core.exceptions.RetryErrorIf the request failed due to a retryable error and retry attempts failed.
ValueErrorIf the parameters are invalid.