Class Database (1.11.0)

Database(database_id, instance, ddl_statements=(), pool=None)

Representation of a Cloud Spanner Database.

We can use a Database to:

  • create the database
  • reload the database
  • update the database
  • drop the database

Parameters

NameDescription
database_id str

The ID of the database.

instance Instance

The instance that owns the database.

ddl_statements list of string

(Optional) DDL statements, excluding the CREATE DATABASE statement.

pool concrete subclass of AbstractSessionPool.

(Optional) session pool to be used by database. If not passed, the database will construct an instance of BurstyPool.

Properties

ddl_statements

DDL Statements used to define database schema.

See cloud.google.com/spanner/docs/data-definition-language

Returns
TypeDescription
sequence of stringthe statements

name

Database name used in requests.

"projects/../instances/../databases/{database_id}"

Returns
TypeDescription
strThe database name.

spanner_api

Helper for session-related API calls.

Methods

batch

batch()

Return an object which wraps a batch.

The wrapper must be used as a context manager, with the batch as the value returned by the wrapper.

Returns
TypeDescription
BatchCheckoutnew wrapper

batch_snapshot

batch_snapshot(read_timestamp=None, exact_staleness=None)

Return an object which wraps a batch read / query.

Parameters
NameDescription
read_timestamp datetime.datetime

Execute all reads at the given timestamp.

exact_staleness datetime.timedelta

Execute all reads at a timestamp that is exact_staleness old.

Returns
TypeDescription
BatchSnapshotnew wrapper

create

create()

Create this database within its instance

Inclues any configured schema assigned to ddl_statements.

See https://cloud.google.com/spanner/reference/rpc/google.spanner.admin.database.v1#google.spanner.admin.database.v1.DatabaseAdmin.CreateDatabase

Exceptions
TypeDescription
Conflictif the database already exists
NotFoundif the instance owning the database does not exist
Returns
TypeDescription
google.api_core.operation.Operationa future used to poll the status of the create request

drop

drop()

Drop this database.

See https://cloud.google.com/spanner/reference/rpc/google.spanner.admin.database.v1#google.spanner.admin.database.v1.DatabaseAdmin.DropDatabase

execute_partitioned_dml

execute_partitioned_dml(dml, params=None, param_types=None)

Execute a partitionable DML statement.

Parameters
NameDescription
dml str

DML statement

params dict, {str -> column value}

values for parameter replacement. Keys must match the names used in dml.

param_types dict[str -> Union[dict, .types.Type]]

(Optional) maps explicit types for one or more param values; required if parameters are passed.

Returns
TypeDescription
intCount of rows affected by the DML statement.

exists

exists()

Test whether this database exists.

See https://cloud.google.com/spanner/reference/rpc/google.spanner.admin.database.v1#google.spanner.admin.database.v1.DatabaseAdmin.GetDatabaseDDL

Returns
TypeDescription
boolTrue if the database exists, else false.

from_pb

from_pb(database_pb, instance, pool=None)

Creates an instance of this class from a protobuf.

Parameters
NameDescription
database_pb google.spanner.v2.spanner_instance_admin_pb2.Instance

A instance protobuf object.

instance Instance

The instance that owns the database.

pool concrete subclass of AbstractSessionPool.

(Optional) session pool to be used by database.

Exceptions
TypeDescription
ValueErrorif the instance name does not match the expected format or if the parsed project ID does not match the project ID on the instance's client, or if the parsed instance ID does not match the instance's ID.
Returns
TypeDescription
DatabaseThe database parsed from the protobuf response.

reload

reload()

Reload this database.

Refresh any configured schema into ddl_statements.

See https://cloud.google.com/spanner/reference/rpc/google.spanner.admin.database.v1#google.spanner.admin.database.v1.DatabaseAdmin.GetDatabaseDDL

Exceptions
TypeDescription
NotFoundif the database does not exist

run_in_transaction

run_in_transaction(func, *args, **kw)

Perform a unit of work in a transaction, retrying on abort.

Parameters
NameDescription
args tuple

additional positional arguments to be passed to func.

kw dict

optional keyword arguments to be passed to func. If passed, "timeout_secs" will be removed and used to override the default timeout.

func callable

takes a required positional argument, the transaction, and additional positional / keyword arguments as supplied by the caller.

Exceptions
TypeDescription
Exceptionreraises any non-ABORT execptions raised by func.
Returns
TypeDescription
AnyThe return value of func.

session

session(labels=None)

Factory to create a session for this database.

Parameter
NameDescription
labels dict (str -> str) or None

(Optional) user-assigned labels for the session.

Returns
TypeDescription
Sessiona session bound to this database.

snapshot

snapshot(**kw)

Return an object which wraps a snapshot.

The wrapper must be used as a context manager, with the snapshot as the value returned by the wrapper.

See https://cloud.google.com/spanner/reference/rpc/google.spanner.v1#google.spanner.v1.TransactionOptions.ReadOnly

Parameter
NameDescription
kw dict

Passed through to Snapshot constructor.

Returns
TypeDescription
SnapshotCheckoutnew wrapper

update_ddl

update_ddl(ddl_statements, operation_id="")

Update DDL for this database.

Apply any configured schema from ddl_statements.

See https://cloud.google.com/spanner/reference/rpc/google.spanner.admin.database.v1#google.spanner.admin.database.v1.DatabaseAdmin.UpdateDatabase

Parameters
NameDescription
ddl_statements Sequence[str]

a list of DDL statements to use on this database

operation_id str

(optional) a string ID for the long-running operation

Exceptions
TypeDescription
NotFoundif the database does not exist
Returns
TypeDescription
google.api_core.operation.Operationan operation instance