Spanner Admin Database Client API#
-
class
google.cloud.spanner_admin_database_v1.
DatabaseAdminClient
(transport=None, channel=None, credentials=None, client_config=None, client_info=None, client_options=None)[source]# 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.
Constructor.
- Parameters
(Union[DatabaseAdminGrpcTransport, (transport) – Callable[[~.Credentials, type], ~.DatabaseAdminGrpcTransport]): A transport instance, responsible for actually making the API calls. The default transport uses the gRPC protocol. This argument may also be a callable which returns a transport instance. Callables will be sent the credentials as the first argument and the default transport class as the second argument.
channel (grpc.Channel) – DEPRECATED. A
Channel
instance through which to make calls. This argument is mutually exclusive withcredentials
; 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
(parent, create_statement, extra_statements=None, retry=<object object>, timeout=<object object>, metadata=None)[source]# 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. Themetadata
field type isCreateDatabaseMetadata
. Theresponse
field type isDatabase
, if successful.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
parent (str) – Required. The name of the instance that will serve the new database. Values are of the form
projects/<project>/instances/<instance>
.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.
- Returns
A
_OperationFuture
instance.- Raises
google.api_core.exceptions.GoogleAPICallError – If the request failed for any reason.
google.api_core.exceptions.RetryError – If the request failed due to a retryable error and retry attempts failed.
ValueError – If the parameters are invalid.
-
classmethod
database_path
(project, instance, database)[source]# Return a fully-qualified database string.
-
drop_database
(database, retry=<object object>, timeout=<object object>, metadata=None)[source]# Drops (aka deletes) a Cloud Spanner database.
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
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.
- Raises
google.api_core.exceptions.GoogleAPICallError – If the request failed for any reason.
google.api_core.exceptions.RetryError – If the request failed due to a retryable error and retry attempts failed.
ValueError – If the parameters are invalid.
-
enums
= <module 'google.cloud.spanner_admin_database_v1.gapic.enums' from '/usr/local/lib/python3.7/site-packages/google/cloud/spanner_admin_database_v1/gapic/enums.py'>#
-
classmethod
from_service_account_file
(filename, *args, **kwargs)[source]# Creates an instance of this client using the provided credentials file.
- Parameters
filename (str) – The path to the service account private key json file.
args – Additional arguments to pass to the constructor.
kwargs – Additional arguments to pass to the constructor.
- Returns
The constructed client.
- Return type
-
classmethod
from_service_account_json
(filename, *args, **kwargs)# Creates an instance of this client using the provided credentials file.
- Parameters
filename (str) – The path to the service account private key json file.
args – Additional arguments to pass to the constructor.
kwargs – Additional arguments to pass to the constructor.
- Returns
The constructed client.
- Return type
-
get_database
(name, retry=<object object>, timeout=<object object>, metadata=None)[source]# Gets the state of a Cloud Spanner database.
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
name (str) – Required. The name of the requested database. Values are of the form
projects/<project>/instances/<instance>/databases/<database>
.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.
- Returns
A
Database
instance.- Raises
google.api_core.exceptions.GoogleAPICallError – If the request failed for any reason.
google.api_core.exceptions.RetryError – If the request failed due to a retryable error and retry attempts failed.
ValueError – If the parameters are invalid.
-
get_database_ddl
(database, retry=<object object>, timeout=<object object>, metadata=None)[source]# 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.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
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.
- Returns
A
GetDatabaseDdlResponse
instance.- Raises
google.api_core.exceptions.GoogleAPICallError – If the request failed for any reason.
google.api_core.exceptions.RetryError – If the request failed due to a retryable error and retry attempts failed.
ValueError – If the parameters are invalid.
-
get_iam_policy
(resource, options_=None, retry=<object object>, timeout=<object object>, metadata=None)[source]# 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 onresource
.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
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 toGetIamPolicy
. 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.
- Returns
A
Policy
instance.- Raises
google.api_core.exceptions.GoogleAPICallError – If the request failed for any reason.
google.api_core.exceptions.RetryError – If the request failed due to a retryable error and retry attempts failed.
ValueError – If the parameters are invalid.
-
list_databases
(parent, page_size=None, retry=<object object>, timeout=<object object>, metadata=None)[source]# Lists Cloud Spanner databases.
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
parent (str) – Required. The instance whose databases should be listed. Values are of the form
projects/<project>/instances/<instance>
.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.
- Returns
A
PageIterator
instance. An iterable ofDatabase
instances. You can also iterate over the pages of the response using its pages property.- Raises
google.api_core.exceptions.GoogleAPICallError – If the request failed for any reason.
google.api_core.exceptions.RetryError – If the request failed due to a retryable error and retry attempts failed.
ValueError – If the parameters are invalid.
-
set_iam_policy
(resource, policy, retry=<object object>, timeout=<object object>, metadata=None)[source]# Sets the access control policy on a database resource. Replaces any existing policy.
Authorization requires
spanner.databases.setIamPolicy
permission onresource
.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
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.
- Returns
A
Policy
instance.- Raises
google.api_core.exceptions.GoogleAPICallError – If the request failed for any reason.
google.api_core.exceptions.RetryError – If the request failed due to a retryable error and retry attempts failed.
ValueError – If the parameters are invalid.
-
test_iam_permissions
(resource, permissions, retry=<object object>, timeout=<object object>, metadata=None)[source]# 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.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
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.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.
- Returns
A
TestIamPermissionsResponse
instance.- Raises
google.api_core.exceptions.GoogleAPICallError – If the request failed for any reason.
google.api_core.exceptions.RetryError – If the request failed due to a retryable error and retry attempts failed.
ValueError – If the parameters are invalid.
-
update_database_ddl
(database, statements, operation_id=None, retry=<object object>, timeout=<object object>, metadata=None)[source]# 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). Themetadata
field type isUpdateDatabaseDdlMetadata
. The operation has no response.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
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 resultingOperation
.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: thedatabase
andoperation_id
fields can be combined to form thename
of the resultinglongrunning.Operation
:<database>/operations/<operation_id>
.operation_id
should be unique within the database, and must be a valid identifier:[a-z][a-z0-9_]*
. Note that automatically-generated operation IDs always begin with an underscore. If the named operation already exists,UpdateDatabaseDdl
returnsALREADY_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.
- Returns
A
_OperationFuture
instance.- Raises
google.api_core.exceptions.GoogleAPICallError – If the request failed for any reason.
google.api_core.exceptions.RetryError – If the request failed due to a retryable error and retry attempts failed.
ValueError – If the parameters are invalid.