Database API

User friendly container for Cloud Spanner Database.

class google.cloud.spanner_v1.database.BatchCheckout(database)

Bases: object

Context manager for using a batch from a database.

Inside the context manager, checks out a session from the database, creates a batch from it, making the batch available.

Caller must not use the batch to perform API requests outside the scope of the context manager.

• Parameters

  database( Database ) – database to use

_ enter_ ()

Begin with block.

_ exit_ (exc_type, exc_val, exc_tb)

End with block.

class google.cloud.spanner_v1.database.BatchSnapshot(database, read_timestamp=None, exact_staleness=None)

Bases: object

Wrapper for generating and processing read / query batches.

• Parameters

  • database( Database ) – database to use

  • 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.

close()

Clean up underlying session.

NOTE: If the transaction has been shared across multiple machines, calling this on any machine would invalidate the transaction everywhere. Ideally this would be called when data has been read from all the partitions.

execute_sql(*args, **kw)

Convenience method: perform query operation via snapshot.

See execute_sql() .

classmethod from_dict(database, mapping)

Reconstruct an instance from a mapping.

• Parameters

  • database( Database ) – database to use

  • mapping( mapping ) – serialized state of the instance

• Return type

  BatchSnapshot

generate_query_batches(sql, params=None, param_types=None, partition_size_bytes=None, max_partitions=None)

Start a partitioned query operation.

Uses the PartitionQuery API request to start a partitioned query operation. Returns a list of batch information needed to peform the actual queries.

• Parameters

  • sql( str ) – SQL query statement

  • params( dict , **{str -> column value} ) – values for parameter replacement. Keys must match the names used in sql .

  • param_types( dict [ str -> Union [ dict , *[ types.Type ](gapic/v1/types.md#google.cloud.spanner_v1.types.Type) ] *] ) – (Optional) maps explicit types for one or more param values; required if parameters are passed.

  • partition_size_bytes( int ) – (Optional) desired size for each partition generated. The service uses this as a hint, the actual partition size may differ.

  • partition_size_bytes– (Optional) desired size for each partition generated. The service uses this as a hint, the actual partition size may differ.

  • max_partitions( int ) – (Optional) desired maximum number of partitions generated. The service uses this as a hint, the actual number of partitions may differ.

• Return type

  iterable of dict

• Returns

  mappings of information used peform actual partitioned reads via process_read_batch() .

generate_read_batches(table, columns, keyset, index='', partition_size_bytes=None, max_partitions=None)

Start a partitioned batch read operation.

Uses the PartitionRead API request to initiate the partitioned read. Returns a list of batch information needed to perform the actual reads.

• Parameters

  • table( str ) – name of the table from which to fetch data

  • columns( list of str ) – names of columns to be retrieved

  • keyset( KeySet ) – keys / ranges identifying rows to be retrieved

  • index( str ) – (Optional) name of index to use, rather than the table’s primary key

  • partition_size_bytes( int ) – (Optional) desired size for each partition generated. The service uses this as a hint, the actual partition size may differ.

  • max_partitions( int ) – (Optional) desired maximum number of partitions generated. The service uses this as a hint, the actual number of partitions may differ.

• Return type

  iterable of dict

• Returns

  mappings of information used peform actual partitioned reads via process_read_batch() .

process(batch)

Process a single, partitioned query or read.

• Parameters

  batch( mapping ) – one of the mappings returned from an earlier call to generate_query_batches() .

• Return type

  StreamedResultSet

• Returns

  a result set instance which can be used to consume rows.

• Raises

  ValueError – if batch does not contain either ‘read’ or ‘query’

process_query_batch(batch)

Process a single, partitioned query.

• Parameters

  batch( mapping ) – one of the mappings returned from an earlier call to generate_query_batches() .

• Return type

  StreamedResultSet

• Returns

  a result set instance which can be used to consume rows.

process_read_batch(batch)

Process a single, partitioned read.

• Parameters

  batch( mapping ) – one of the mappings returned from an earlier call to generate_read_batches() .

• Return type

  StreamedResultSet

• Returns

  a result set instance which can be used to consume rows.

read(*args, **kw)

Convenience method: perform read operation via snapshot.

See read() .

to_dict()

Return state as a dictionary.

Result can be used to serialize the instance and reconstitute it later using from_dict() .

• Return type

  dict

class google.cloud.spanner_v1.database.Database(database_id, instance, ddl_statements=(), pool=None)

Bases: object

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

  • 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 .

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.

• Return type

  BatchCheckout

• Returns

  new wrapper

batch_snapshot(read_timestamp=None, exact_staleness=None)

Return an object which wraps a batch read / query.

• Parameters

  • 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.

• Return type

  BatchSnapshot

• Returns

  new wrapper

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

• Return type

  Operation

• Returns

  a future used to poll the status of the create request

• Raises

  • Conflict– if the database already exists

  • NotFound– if the instance owning the database does not exist

property ddl_statements()

DDL Statements used to define database schema.

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

• Return type

  sequence of string

• Returns

  the statements

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(dml, params=None, param_types=None)

Execute a partitionable DML statement.

• Parameters

  • 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 ](gapic/v1/types.md#google.cloud.spanner_v1.types.Type) ] *] ) – (Optional) maps explicit types for one or more param values; required if parameters are passed.

• Return type

  int

• Returns

  Count of rows affected by the DML statement.

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

• Return type

  bool

• Returns

  True if the database exists, else false.

classmethod from_pb(database_pb, instance, pool=None)

Creates an instance of this class from a protobuf.

• Parameters

  • 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.

• Return type

  Database

• Returns

  The database parsed from the protobuf response.

• Raises

  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.

property name()

Database name used in requests.

NOTE: This property will not change if database_id does not, but the return value is not cached.

The database name is of the form

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

• Return type

  str

• Returns

  The database name.

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

• Raises

  NotFound– if the database does not exist

run_in_transaction(func, *args, **kw)

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

• Parameters

  • func( callable ) – takes a required positional argument, the transaction, and additional positional / keyword arguments as supplied by the caller.

  • 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.

• Return type

  datetime.datetime

• Returns

  timestamp of committed transaction

session(labels=None)

Factory to create a session for this database.

• Parameters

  labels( dict * ( str -> str) or [ None*]( https://python.readthedocs.io/en/latest/library/constants.html#None )) – (Optional) user-assigned labels for the session.

• Return type

  Session

• Returns

  a session bound to this database.

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

• Parameters

  kw( dict ) – Passed through to Snapshot constructor.

• Return type

  SnapshotCheckout

• Returns

  new wrapper

property spanner_api()

Helper for session-related API calls.

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

  • 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

• Return type

  google.api_core.operation.Operation

• Returns

  an operation instance

• Raises

  NotFound– if the database does not exist

class google.cloud.spanner_v1.database.SnapshotCheckout(database, **kw)

Bases: object

Context manager for using a snapshot from a database.

Inside the context manager, checks out a session from the database, creates a snapshot from it, making the snapshot available.

Caller must not use the snapshot to perform API requests outside the scope of the context manager.

• Parameters

  • database( Database ) – database to use

  • kw( dict ) – Passed through to Snapshot constructor.

_ enter_ ()

Begin with block.

_ exit_ (exc_type, exc_val, exc_tb)

End with block.