Package io.permazen.kv.spanner

Class SpannerKVDatabase

java.lang.Object
io.permazen.kv.spanner.SpannerKVDatabase
All Implemented Interfaces:
KVDatabase
@ThreadSafe public class SpannerKVDatabase extends Object implements KVDatabase
KVDatabase implementation based on Google Cloud Spanner.

Configuration

A SpannerKVDatabase must be configured with a Spanner instance ID. You can create a Spanner instance using the Google Cloud Console or the gcloud command line utility.

Configure a SpannerOptions to override the default project ID associated with your environment. The default database ID ("permazen") and table name ("KV") may also be overridden.

Caching

Because Spanner has relatively high latency vs. throughput, instances utilize a CachingKVStore for caching and batch loading read-ahead.

Consistency Levels

Transactions may either have strong consistency (the default), or have some amount of staleness. Transactions that are not strongly consistent must be read-only.

A TimestampBound may be passed as an option to createTransaction() under the "TimestampBound" key. Transactions that are not strongly consistent must be read-only.

In Spring applications, the transaction consistency level may be configured through the Spring PermazenTransactionManager by (ab)using the transaction isolation level setting, for example, via the @Transactional annotation's isolation() property:

Isolation Level Mapping
Spring isolation level SpannerKVDatabase consistency level
DEFAULT Strong consistency
SERIALIZABLE Strong consistency
READ_COMMITTED Exact staleness of ten seconds
REPEATABLE_READ Exact staleness of three seconds
READ_UNCOMMITTED N/A

Key Watches

Key watches are not supported.

See Also:

  • Field Details

  • Constructor Details

    • SpannerKVDatabase

      public SpannerKVDatabase()

  • Method Details

    • setSpannerOptions

      public void setSpannerOptions(com.google.cloud.spanner.SpannerOptions spannerOptions)
      Configure SpannerOptions.
      Parameters:
      spannerOptions - Google spanner configuration options
      Throws:
      IllegalStateException - if this instance is already started
      IllegalArgumentException - if spannerOptions is null

    • setInstanceId

      public void setInstanceId(String instanceId)
      Set Spanner instance ID.

      Required property.

      Parameters:
      instanceId - Spanner instance ID
      Throws:
      IllegalStateException - if this instance is already started
      IllegalArgumentException - if instanceId is null

    • setDatabaseId

      public void setDatabaseId(String databaseId)
      Set Spanner database ID.

      Default is "permazen".

      Parameters:
      databaseId - Spanner instance ID
      Throws:
      IllegalStateException - if this instance is already started
      IllegalArgumentException - if databaseId is null

    • setTableName

      public void setTableName(String tableName)
      Set Spanner table name.

      Default is "KV".

      Parameters:
      tableName - Spanner database table name
      Throws:
      IllegalStateException - if this instance is already started
      IllegalArgumentException - if tableName is invalid
      IllegalArgumentException - if tableName is null

    • start

      @PostConstruct public void start()
      Start this instance.

      The configured Spanner instance, database, and table will be created automatically as needed.

      Specified by:
      start in interface KVDatabase

    • stop

      @PreDestroy public void stop()
      Description copied from interface: KVDatabase
      Stop this instance.

      This method is idempotent: if this instance has not been started, or is already stopped, nothing happens.

      Specified by:
      stop in interface KVDatabase

    • getThreadPoolSize

      public int getThreadPoolSize()
      Get the number of threads in the background task thread pool.

      Default value is 10.

      Returns:
      number of threads in thread pool

    • setThreadPoolSize

      public void setThreadPoolSize(int threadPoolSize)
      Set the number of threads in the background task thread pool.

      Default value is 10.

      Parameters:
      threadPoolSize - number of threads in thread pool
      Throws:
      IllegalStateException - if this instance is already started
      IllegalArgumentException - if threadPoolSize <= 0

    • getRttEstimate

      public double getRttEstimate()
      Get the current round trip time estimate.
      Returns:
      current RTT estimate in nanoseconds
      Throws:
      IllegalStateException - if this instance has never start()ed

    • createTransaction

      public SpannerKVTransaction createTransaction()
      Description copied from interface: KVDatabase
      Create a new transaction.
      Specified by:
      createTransaction in interface KVDatabase
      Returns:
      newly created transaction

    • createTransaction

      public SpannerKVTransaction createTransaction(Map<String,?> options)
      Description copied from interface: KVDatabase
      Create a new transaction with the specified options.
      Specified by:
      createTransaction in interface KVDatabase
      Parameters:
      options - optional transaction options; may be null
      Returns:
      newly created transaction

    • createTransaction

      protected SpannerKVTransaction createTransaction(com.google.cloud.spanner.TimestampBound consistency)

    • getExecutorService

      protected ExecutorService getExecutorService()

    • snapshot

      public ReadOnlySpannerView snapshot(com.google.cloud.spanner.TimestampBound consistency)
      Create a read-only snapshot of the database with the given timestamp bound.
      Parameters:
      consistency - consistency for the snapshot
      Returns:
      read-only view of database
      Throws:
      IllegalArgumentException - if consistency is null
      IllegalStateException - if this instance is not start()ed