- 3.46.0 (latest)
- 3.45.0
- 3.44.0
- 3.43.0
- 3.42.0
- 3.41.0
- 3.40.1
- 3.39.0
- 3.38.0
- 3.37.0
- 3.36.0
- 3.35.1
- 3.34.0
- 3.33.0
- 3.32.0
- 3.31.0
- 3.30.0
- 3.29.0
- 3.28.0
- 3.27.1
- 3.26.0
- 3.25.0
- 3.24.0
- 3.23.0
- 3.22.2
- 3.21.0
- 3.20.0
- 3.19.0
- 3.18.0
- 3.17.0
- 3.16.0
- 3.15.1
- 3.14.1
- 3.13.0
- 3.12.1
- 3.11.1
- 3.10.0
- 3.9.0
- 3.8.0
- 3.7.0
- 3.6.0
- 3.5.0
- 3.4.0
- 3.3.0
- 3.2.0
- 3.1.0
- 3.0.0
- 2.1.1
- 2.0.0
- 1.19.3
- 1.18.0
- 1.17.1
- 1.16.0
- 1.15.1
- 1.14.0
- 1.13.0
- 1.12.0
- 1.11.0
- 1.10.0
Database(
database_id,
instance,
ddl_statements=(),
pool=None,
logger=None,
encryption_config=None,
database_dialect=DatabaseDialect.DATABASE_DIALECT_UNSPECIFIED,
database_role=None,
enable_drop_protection=False,
)
Representation of a Cloud Spanner Database.
We can use a Database
to:
create
the databasereload
the databaseupdate
the databasedrop
the database
Parameters | |
---|---|
Name | Description |
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. |
logger |
(Optional) a custom logger that is used if |
encryption_config |
EncryptionConfig or RestoreDatabaseEncryptionConfig or
(Optional) Encryption configuration for the database. If a dict is provided, it must be of the same form as either of the protobuf messages EncryptionConfig or RestoreDatabaseEncryptionConfig |
database_dialect |
DatabaseDialect
(Optional) database dialect for the database |
database_role |
str or None
(Optional) user-assigned database_role for the session. |
enable_drop_protection |
boolean
(Optional) Represents whether the database has drop protection enabled or not. |
Properties
create_time
Create time of this database.
Returns | |
---|---|
Type | Description |
| a datetime object representing the create time of this database |
database_dialect
DDL Statements used to define database schema.
See cloud.google.com/spanner/docs/data-definition-language
Returns | |
---|---|
Type | Description |
DatabaseDialect | the dialect of the database |
database_role
User-assigned database_role for sessions created by the pool.
Returns | |
---|---|
Type | Description |
str | a str with the name of the database role. |
ddl_statements
DDL Statements used to define database schema.
See cloud.google.com/spanner/docs/data-definition-language
Returns | |
---|---|
Type | Description |
sequence of string | the statements |
default_leader
The read-write region which contains the database's leader replicas.
Returns | |
---|---|
Type | Description |
str | a string representing the read-write region |
earliest_version_time
The earliest time at which older versions of the data can be read.
Returns | |
---|---|
Type | Description |
| a datetime object representing the earliest version time |
enable_drop_protection
Whether the database has drop protection enabled.
Returns | |
---|---|
Type | Description |
boolean | a boolean representing whether the database has drop protection enabled |
encryption_config
Encryption config for this database.
Returns | |
---|---|
Type | Description |
EncryptionConfig | an object representing the encryption config for this database |
encryption_info
Encryption info for this database.
Returns | |
---|---|
Type | Description |
a list of EncryptionInfo | a list of objects representing encryption info for this database |
logger
Logger used by the database.
The default logger will log commit stats at the log level INFO using
sys.stderr
.
Returns | |
---|---|
Type | Description |
| the logger |
name
Database name used in requests.
"projects/../instances/../databases/{database_id}"
Returns | |
---|---|
Type | Description |
str | The database name. |
reconciling
Whether the database is currently reconciling.
Returns | |
---|---|
Type | Description |
boolean | a boolean representing whether the database is reconciling |
restore_info
Restore info for this database.
Returns | |
---|---|
Type | Description |
RestoreInfo | an object representing the restore info for this database |
spanner_api
Helper for session-related API calls.
state
State of this database.
Returns | |
---|---|
Type | Description |
State | an enum describing the state of the database |
version_retention_period
The period in which Cloud Spanner retains all versions of data for the database.
Returns | |
---|---|
Type | Description |
str | a string representing the duration of the version retention period |
Methods
batch
batch(request_options=None)
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.
Parameter | |
---|---|
Name | Description |
request_options |
RequestOptions
(Optional) Common options for the commit request. If a dict is provided, it must be of the same form as the protobuf message RequestOptions. |
Returns | |
---|---|
Type | Description |
BatchCheckout | new wrapper |
batch_snapshot
batch_snapshot(read_timestamp=None, exact_staleness=None)
Return an object which wraps a batch read / query.
Parameters | |
---|---|
Name | Description |
read_timestamp |
Execute all reads at the given timestamp. |
exact_staleness |
Execute all reads at a timestamp that is |
Returns | |
---|---|
Type | Description |
BatchSnapshot | new wrapper |
create
create()
Create this database within its instance
Includes any configured schema assigned to ddl_statements
.
Exceptions | |
---|---|
Type | Description |
Conflict | if the database already exists |
NotFound | if the instance owning the database does not exist |
Returns | |
---|---|
Type | Description |
| a future used to poll the status of the create request |
drop
drop()
Drop this database.
execute_partitioned_dml
execute_partitioned_dml(
dml, params=None, param_types=None, query_options=None, request_options=None
)
Execute a partitionable DML statement.
Parameters | |
---|---|
Name | Description |
dml |
str
DML statement |
params |
dict, {str -> column value}
values for parameter replacement. Keys must match the names used in |
param_types |
dict[str -> Union[dict, .types.Type]]
(Optional) maps explicit types for one or more param values; required if parameters are passed. |
query_options |
QueryOptions or
(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 |
request_options |
RequestOptions
(Optional) Common options for this request. If a dict is provided, it must be of the same form as the protobuf message RequestOptions. Please note, the |
Returns | |
---|---|
Type | Description |
int | Count of rows affected by the DML statement. |
exists
exists()
Test whether this database exists.
Returns | |
---|---|
Type | Description |
bool | True 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 | |
---|---|
Name | Description |
database_pb |
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 | |
---|---|
Type | Description |
ValueError | if 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 | |
---|---|
Type | Description |
| The database parsed from the protobuf response. |
get_iam_policy
get_iam_policy(policy_version=None)
Gets the access control policy for a database resource.
Parameter | |
---|---|
Name | Description |
policy_version |
int
(Optional) the maximum policy version that will be used to format the policy. Valid values are 0, 1 ,3. |
Returns | |
---|---|
Type | Description |
| returns an Identity and Access Management (IAM) policy. It is used to specify access control policies for Cloud Platform resources. |
is_optimized
is_optimized()
Test whether this database has finished optimizing.
Returns | |
---|---|
Type | Description |
bool | True if the database state is READY, else False. |
is_ready
is_ready()
Test whether this database is ready for use.
Returns | |
---|---|
Type | Description |
bool | True if the database state is READY_OPTIMIZING or READY, else False. |
list_database_operations
list_database_operations(filter_="", page_size=None)
List database operations for the database.
Parameters | |
---|---|
Name | Description |
filter_ |
str
Optional. A string specifying a filter for which database operations to list. |
page_size |
int
Optional. The maximum number of operations in each page of results from this request. Non-positive values are ignored. Defaults to a sensible value set by the API. :type: |
list_database_roles
list_database_roles(page_size=None)
Lists Cloud Spanner database roles.
Parameter | |
---|---|
Name | Description |
page_size |
int
Optional. The maximum number of database roles in each page of results from this request. Non-positive values are ignored. Defaults to a sensible value set by the API. :type: Iterable |
list_tables
list_tables()
List tables within the database.
:type: Iterable
reload
reload()
Reload this database.
Refresh any configured schema into ddl_statements
.
Exceptions | |
---|---|
Type | Description |
NotFound | if the database does not exist |
restore
restore(source)
Restore from a backup to this database.
Parameter | |
---|---|
Name | Description |
source |
Backup
the path of the source being restored from. |
Exceptions | |
---|---|
Type | Description |
Conflict | if the database already exists |
NotFound | if the instance owning the database does not exist, or if the backup being restored from does not exist |
ValueError | if backup is not set |
Returns | |
---|---|
Type | Description |
| a future used to poll the status of the create request |
run_in_transaction
run_in_transaction(func, *args, **kw)
Perform a unit of work in a transaction, retrying on abort.
Parameters | |
---|---|
Name | Description |
args |
tuple
additional positional arguments to be passed to |
kw |
dict
(Optional) keyword arguments to be passed to |
func |
callable
takes a required positional argument, the transaction, and additional positional / keyword arguments as supplied by the caller. |
Exceptions | |
---|---|
Type | Description |
Exception | reraises any non-ABORT exceptions raised by func . |
Returns | |
---|---|
Type | Description |
Any | The return value of func . |
session
session(labels=None, database_role=None)
Factory to create a session for this database.
Parameters | |
---|---|
Name | Description |
labels |
dict (str -> str) or None
(Optional) user-assigned labels for the session. |
database_role |
str
(Optional) user-assigned database_role for the session. |
Returns | |
---|---|
Type | Description |
Session | a session bound to this database. |
set_iam_policy
set_iam_policy(policy)
Sets the access control policy on a database resource. Replaces any existing policy.
Returns | |
---|---|
Type | Description |
| returns the new Identity and Access Management (IAM) policy. |
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.
Parameter | |
---|---|
Name | Description |
kw |
dict
Passed through to Snapshot constructor. |
Returns | |
---|---|
Type | Description |
SnapshotCheckout | new wrapper |
table
table(table_id)
Factory to create a table object within this database.
Note: This method does not create a table in Cloud Spanner, but it can be used to check if a table exists.
my_table = database.table("my_table")
if my_table.exists():
print("Table with ID 'my_table' exists.")
else:
print("Table with ID 'my_table' does not exist.")
Parameter | |
---|---|
Name | Description |
table_id |
str
The ID of the table. |
Returns | |
---|---|
Type | Description |
Table | a table owned by this database. |
update
update(fields)
Update this database.
Parameter | |
---|---|
Name | Description |
fields |
Sequence[str]
a list of fields to update |
Exceptions | |
---|---|
Type | Description |
NotFound | if the database does not exist |
Returns | |
---|---|
Type | Description |
| an operation instance |
update_ddl
update_ddl(ddl_statements, operation_id="")
Update DDL for this database.
Apply any configured schema from ddl_statements
.
Parameters | |
---|---|
Name | Description |
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 | |
---|---|
Type | Description |
NotFound | if the database does not exist |
Returns | |
---|---|
Type | Description |
| an operation instance |