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:

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:

Google Cloud Spanner

Field Summary

Fields

Modifier and Type	Field and Description
static String	DEFAULT_DATABASE_ID Default database ID: "permazen".
static String	DEFAULT_TABLE_NAME Default table name: "KV".
static int	DEFAULT_THREAD_POOL_SIZE Default background task thread pool size.
protected Logger	log
static String	OPTION_TIMESTAMP_BOUND Option key for createTransaction(Map).

Constructor Summary

Constructors

Constructor and Description
SpannerKVDatabase()

Method Summary

Modifier and Type	Method and Description
SpannerKVTransaction	createTransaction() Create a new transaction.
SpannerKVTransaction	createTransaction(Map<String,?> options) Create a new transaction with the specified options.
protected SpannerKVTransaction	createTransaction(TimestampBound consistency)
protected ExecutorService	getExecutorService()
double	getRttEstimate() Get the current round trip time estimate.
int	getThreadPoolSize() Get the number of threads in the background task thread pool.
void	setDatabaseId(String databaseId) Set Spanner database ID.
void	setInstanceId(String instanceId) Set Spanner instance ID.
void	setSpannerOptions(SpannerOptions spannerOptions) Configure SpannerOptions.
void	setTableName(String tableName) Set Spanner table name.
void	setThreadPoolSize(int threadPoolSize) Set the number of threads in the background task thread pool.
ReadOnlySpannerView	snapshot(TimestampBound consistency) Create a read-only snapshot of the database with the given timestamp bound.
void	start() Start this instance.
void	stop() Stop this instance.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

OPTION_TIMESTAMP_BOUND

public static final String OPTION_TIMESTAMP_BOUND

Option key for createTransaction(Map). Value should be a TimestampBound instance.

See Also:

Constant Field Values

DEFAULT_DATABASE_ID

public static final String DEFAULT_DATABASE_ID

Default database ID: "permazen".

See Also:

Constant Field Values

DEFAULT_TABLE_NAME

public static final String DEFAULT_TABLE_NAME

Default table name: "KV".

See Also:

Constant Field Values

DEFAULT_THREAD_POOL_SIZE

public static final int DEFAULT_THREAD_POOL_SIZE

Default background task thread pool size.

See Also:

Constant Field Values

log

protected final Logger log

Constructor Detail

SpannerKVDatabase

public SpannerKVDatabase()

Method Detail

setSpannerOptions

public void setSpannerOptions(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(TimestampBound consistency)

getExecutorService

protected ExecutorService getExecutorService()

snapshot

public ReadOnlySpannerView snapshot(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