Database API

User friendly container for Cloud Spanner Database.

class google.cloud.spanner_v1.database.BatchCheckout(database, request_options=None)

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.

_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, query_options=None, *, retry=<_MethodDefault._DEFAULT_VALUE:

Start a partitioned query operation.

Uses the PartitionQuery API request to start a partitioned query operation. Returns a list of batch information needed to perform 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](spanner_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.

    • query_options (QueryOptions or dict) – (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

    • retry (Retry) – (Optional) The retry settings for this request.

    • timeout (float) – (Optional) The timeout for this request.

  • Return type

    iterable of dict

  • Returns

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

generate_read_batches(table, columns, keyset, index='', partition_size_bytes=None, max_partitions=None, *, retry=<_MethodDefault._DEFAULT_VALUE:

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.

    • retry (Retry) – (Optional) The retry settings for this request.

    • timeout (float) – (Optional) The timeout for this request.

  • Return type

    iterable of dict

  • Returns

    mappings of information used perform 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, *, retry=<_MethodDefault._DEFAULT_VALUE:

Process a single, partitioned query.

  • Parameters

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

    • retry (Retry) – (Optional) The retry settings for this request.

    • timeout (float) – (Optional) The timeout for this request.

  • Return type

    StreamedResultSet

  • Returns

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

process_read_batch(batch, *, retry=<_MethodDefault._DEFAULT_VALUE:

Process a single, partitioned read.

  • Parameters

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

    • retry (Retry) – (Optional) The retry settings for this request.

    • timeout (float) – (Optional) The timeout for this request.

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

class google.cloud.spanner_v1.database.Database(database_id, instance, ddl_statements=(), pool=None, logger=None, encryption_config=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.

    • logger (logging.Logger) – (Optional) a custom logger that is used if log_commit_stats is True to log commit statistics. If not passed, a logger will be created when needed that will log the commit statistics to stdout.

    • encryption_config (EncryptionConfig or RestoreDatabaseEncryptionConfig or dict) – (Optional) Encryption configuration for the database. If a dict is provided, it must be of the same form as either of the protobuf messages