Class SpannerConnectionStringBuilder

A connection string builder for Spanner connection strings. The connection string should be of the form: Data Source=projects/{project}/instances/{instance}/databases/{database};[Host={hostname};][Port={portnumber}]

Inheritance

object

DbConnectionStringBuilder

SpannerConnectionStringBuilder

Implements

IDictionary

ICollection

IEnumerable

ICustomTypeDescriptor

Inherited Members

DbConnectionStringBuilder.Add(string, object)

DbConnectionStringBuilder.AppendKeyValuePair(StringBuilder, string, string)

DbConnectionStringBuilder.AppendKeyValuePair(StringBuilder, string, string, bool)

DbConnectionStringBuilder.ContainsKey(string)

DbConnectionStringBuilder.EquivalentTo(DbConnectionStringBuilder)

DbConnectionStringBuilder.Remove(string)

DbConnectionStringBuilder.ShouldSerialize(string)

DbConnectionStringBuilder.ToString()

DbConnectionStringBuilder.TryGetValue(string, out object)

DbConnectionStringBuilder.ConnectionString

DbConnectionStringBuilder.Count

DbConnectionStringBuilder.IsFixedSize

DbConnectionStringBuilder.IsReadOnly

DbConnectionStringBuilder.Keys

DbConnectionStringBuilder.Values

object.GetHashCode()

object.GetType()

Namespace: Google.Cloud.Spanner.Data

Assembly: Google.Cloud.Spanner.Data.dll

Syntax

public sealed class SpannerConnectionStringBuilder : DbConnectionStringBuilder, IDictionary, ICollection, IEnumerable, ICustomTypeDescriptor

Constructors

SpannerConnectionStringBuilder()

Creates a new SpannerConnectionStringBuilder.

Declaration

public SpannerConnectionStringBuilder()

SpannerConnectionStringBuilder(string, GoogleCredential)

Creates a new SpannerConnectionStringBuilder with the given connection string and optional credential.

Declaration

public SpannerConnectionStringBuilder(string connectionString, GoogleCredential googleCredential)

Parameters

Type	Name	Description
string	connectionString	A connection string of the form Data Source=projects/{project}/instances/{instance}/databases/{database};[Host={hostname};][Port={portnumber}].
GoogleCredential	googleCredential	The credential to use for the connection. If this is null, then default application credentials will be used. Credentials can be retrieved from a file or obtained interactively. See Google Cloud documentation for more information. May be null.

SpannerConnectionStringBuilder(string, ChannelCredentials)

Creates a new SpannerConnectionStringBuilder with the given connection string and optional credential.

Declaration

public SpannerConnectionStringBuilder(string connectionString, ChannelCredentials credentials = null)

Parameters

Type	Name	Description
string	connectionString	A connection string of the form Data Source=projects/{project}/instances/{instance}/databases/{database};[Host={hostname};][Port={portnumber}]. Must not be null.
ChannelCredentials	credentials	Optionally supplied credential to use for the connection. If this is null (the default parameter value), then default application credentials will be used. Credentials can be retrieved from a file or obtained interactively. See Google Cloud documentation for more information.

Properties

AllowImmediateTimeouts

Option to allow a timeout of 0 to mean "fail immediately" rather than "continue indefinitely". This is primarily used for testing.

Declaration

public bool AllowImmediateTimeouts { get; set; }

Property Value

Type	Description
bool

ClrToSpannerTypeDefaultMappings

Option to configure the default CLR type to SpannerDbType mapping. This option comes into picture only if SpannerDbType and DbType of the SpannerParameter are not explicitly provided. Currently only decimal and DateTime CLR types are supported.

Declaration

public string ClrToSpannerTypeDefaultMappings { get; set; }

Property Value

Type	Description
string

Remarks

The valid type mappings for decimal are:

DecimalToFloat64 - decimal CLR type will map to Float64, if SpannerDbType and DbType is not explicitly provided for the SpannerParameter.

DecimalToNumeric - decimal CLR type will map to Numeric, if SpannerDbType and DbType is not explicitly provided for the SpannerParameter. This should be used while working with Google Standard SQL dialect only.

DecimalToPgNumeric - decimal CLR type will map to PgNumeric, if SpannerDbType and DbType is not explicitly provided for the SpannerParameter. This should be used while working with PostgreSQL dialect only.

The valid type mappings for DateTime are:

DateTimeToDate - DateTime CLR type will map to Date, if SpannerDbType and DbType is not explicitly provided for the SpannerParameter.

DateTimeToTimestamp - DateTime CLR type will map to Timestamp, if SpannerDbType and DbType is not explicitly provided for the SpannerParameter.

The mapping can be provided as comma separated values. Only one mapping for a type must be provided. Providing mutiple mapping for a type, or providing invalid mapping or providing whitespaces will result in ArgumentException. Few examples of valid values are:

DecimalToFloat64,DateTimeToDate

DecimalToNumeric,DateTimeToTimestamp

This property corresponds with the value of the "ClrToSpannerTypeDefaultMappings" part of the connection string.

CredentialFile

Optional path to a JSON Credential file. If a Credential is not supplied, Cloud Spanner will use Default Application Credentials.

Declaration

public string CredentialFile { get; set; }

Property Value

Type	Description
string

DataSource

DataSource of the Spanner database in the form of 'projects/{project}/instances/{instance}/databases/{database}' or 'projects/{project}/instances/{instance}'.

Declaration

public string DataSource { get; set; }

Property Value

Type	Description
string

DatabaseName

The fully-qualified database name parsed from DataSource. May be null, if the data source isn't set, or is invalid, or doesn't contain a database name.

Declaration

public DatabaseName DatabaseName { get; set; }

Property Value

Type	Description
DatabaseName

DatabaseRole

The database role for the sessions created by this connection.

Declaration

public string DatabaseRole { get; set; }

Property Value

Type	Description
string

DirectedReadOptions

Specifies which replicas or regions should be used for non-transactional reads or queries. May be null. When set, all queries and reads executed on this connection within a read-only or single-use transaction will include these options. If a query or read command specifies directed read options itself then those have precedence over these. For other operations or for non read-only or single-use transactions, these options are ignored.

Declaration

public DirectedReadOptions DirectedReadOptions { get; set; }

Property Value

Type	Description
DirectedReadOptions

Remarks

These options are not settable through the connection string actual string value. Instead they are only settable via code on SpannerConnectionStringBuilder instances. This may change in the future and directed read options may be made available through the actual string value of the connection string.

EmulatorDetection

Specifies whether to allow the connection to check for the presence of the emulator environment variable.

Declaration

public EmulatorDetection EmulatorDetection { get; set; }

Property Value

Type	Description
EmulatorDetection

Remarks

This property defaults to None, meaning that the environment variable is ignored.

EnableGetSchemaTable

Option to allow SpannerDataReader to return a schema from GetSchemaTable, on supported platforms. Only partial information is available, and when this option is enabled, DbDataAdapter may be overly eager to use the information to create and manage datasets.

Declaration

public bool EnableGetSchemaTable { get; set; }

Property Value

Type	Description
bool

EnableLeaderRouting

Options to control leader routing. This is true by default.

Declaration

public bool EnableLeaderRouting { get; set; }

Property Value

Type	Description
bool

Remarks

If this value is true some operations will always be explicitly routed to the leader, some operations will never be explicitly routed to the leader, and some operations will be routed to the leader depending on the transaction type they are using.

EndPoint

The endpoint to use to connect to Spanner. If not supplied in the connection string, the default endpoint will be used.

Declaration

public string EndPoint { get; }

Property Value

Type	Description
string

Host

The TCP Host name to connect to Spanner. If not supplied in the connection string, the default host will be used.

Declaration

public string Host { get; set; }

Property Value

Type	Description
string

this[string]

Gets or sets the value associated with the specified key.

Declaration

public override object this[string keyword] { get; set; }

Parameters

Type	Name	Description
string	keyword	The key of the item to get or set.

Property Value

Type	Description
object	The value associated with the specified key. If the specified key is not found, trying to get it returns a null reference (Nothing in Visual Basic), and trying to set it creates a new element using the specified key. Passing a null (Nothing in Visual Basic) key throws an ArgumentNullException. Assigning a null value removes the key/value pair.

Overrides

DbConnectionStringBuilder.this[string]

Exceptions

Type	Condition
ArgumentNullException	keyword is a null reference (Nothing in Visual Basic).
NotSupportedException	The property is set, and the DbConnectionStringBuilder is read-only. -or- The property is set, keyword does not exist in the collection, and the DbConnectionStringBuilder has a fixed size.

LogCommitStats

Request commit statistics for all read/write transactions throughout the lifetime of the connection and log these.

Declaration

public bool LogCommitStats { get; set; }

Property Value

Type	Description
bool

Remarks

Commit statistics that are returned for a transaction are logged using the logger of the connection. Applications can set a custom logger on the connection to log the output to a different destination. Google.Cloud.Spanner.V1.Internal.Logging.Logger.LogCommitStats(Google.Cloud.Spanner.V1.CommitRequest, Google.Cloud.Spanner.V1.CommitResponse)

MaxConcurrentStreamsLowWatermark

The low watermark of max number of concurrent streams in a channel. A new channel will be created once this is reached, until the maximum size of the channel pool is reached. This rarely needs to be modified.

Declaration

public int MaxConcurrentStreamsLowWatermark { get; set; }

Property Value

Type	Description
int

MaximumGrpcChannels

The maximum number of gRPC channels used for connections with the same settings. Defaults to 4.

Declaration

public int MaximumGrpcChannels { get; set; }

Property Value

Type	Description
int

Port

The TCP port number to connect to Spanner. If not supplied in the connection string, the default port will be used.

Declaration

public int Port { get; set; }

Property Value

Type	Description
int

Project

The Spanner Project name parsed from DataSource May be null, if the data source isn't set, or is invalid.

Declaration

public string Project { get; }

Property Value

Type	Description
string

SessionPoolManager

The SessionPoolManager to use for server interactions.

Declaration

public SessionPoolManager SessionPoolManager { get; set; }

Property Value

Type	Description
SessionPoolManager

Remarks

This property defaults to Default, and most code will not need to change this. It can be convenient for isolation purposes, particularly in testing.

SpannerDatabase

The Spanner Database name parsed from DataSource. May be null, if the data source isn't set, or is invalid, or doesn't contain a database name.

Declaration

public string SpannerDatabase { get; }

Property Value

Type	Description
string

SpannerInstance

The Spanner Instance name parsed from DataSource May be null, if the data source isn't set, or is invalid.

Declaration

public string SpannerInstance { get; }

Property Value

Type	Description
string

SpannerToClrTypeDefaultMappings

Option to configure the default SpannerDbType to CLR type mappings. This option comes into picture only if CLR type of the value being read is not explicitly provided while reading the data from the database. Currently only Date is supported.

Declaration

public string SpannerToClrTypeDefaultMappings { get; set; }

Property Value

Type	Description
string

Remarks

The valid type mappings for Date are:

DateToDateTime - Date will map to DateTime, if CLR type of the value being read is not explicitly provided.

DateToSpannerDate - Date will map to Google.Cloud.Spanner.V1.SpannerDate, if CLR type of the value being read is not explicitly provided.

The mapping can be provided as comma separated values. Only one mapping for a SpannerDbType must be provided. Providing mutiple mapping for a type, or providing invalid mapping or providing whitespaces will result in ArgumentException. Few examples of valid values are:

DateToDateTime

DateToSpannerDate

This property corresponds with the value of the "SpannerToClrTypeDefaultMappings" part of the connection string.

Timeout

Defines the default values for CommandTimeout and CommitTimeout along with all network operations to a Cloud Spanner database. Defaults to 60 seconds.

Declaration

public int Timeout { get; set; }

Property Value

Type	Description
int

Remarks

Operations sent to the server that take greater than this duration will fail with a SpannerException and error code DeadlineExceeded. A value of '0' normally indicates that no timeout should be used (it waits an infinite amount of time). However, if you specify AllowImmediateTimeouts=true in the connection string, '0' will cause a timeout that expires immediately. This is normally used only for testing purposes.

UseClrDefaultForNull

Option to change between the default handling of null database values (return DBNull.Value) or the non-standard handling (return the default value for whatever type is requested).

Declaration

public bool UseClrDefaultForNull { get; set; }

Property Value

Type	Description
bool

Remarks

If this is false (the default), requesting a value from a SpannerDataReader that is null in the database will return DBNull.Value, which may cause an InvalidCastException if the requested type is not compatible with that value. For arrays and structs, the behavior is slightly different. A null value is used for an array or struct value where the target type permits such a value. Attempting to convert an array value that contains a null element into a .NET array type with a non-nullable element type will cause an InvalidCastException to be thrown. To avoid this, where array elements may be null for value types, use an array with a nullable element type. This allows code to distinguish between a null element in the original data and a value of 0, false etc.

If this is true, requesting a value from a SpannerDataReader that is null in the database will return the default value of the requested type (e.g. 0 or a null reference). That conversion is also used for array elements. For example, converting a Spanner array consisting of 1, null, and 2 into an Int32 array will result in an array containing 1, 0 and 2. This is the behavior from release 1.0 of this package.

This property corresponds with the value of the "UseClrDefaultForNull" part of the connection string.

Methods

Clear()

Clears the contents of the DbConnectionStringBuilder instance.

Declaration

public override void Clear()

Overrides

DbConnectionStringBuilder.Clear()

Exceptions

Type	Condition
NotSupportedException	The DbConnectionStringBuilder is read-only.

WithDatabase(string)

Returns a new instance of a SpannerConnectionStringBuilder with the database portion of the DataSource replaced with a new value.

Declaration

public SpannerConnectionStringBuilder WithDatabase(string database)

Parameters

Type	Name	Description
string	database	The new database name. Can be null to open a connection for Ddl commands.

Returns

Type	Description
SpannerConnectionStringBuilder	A new instance of SpannerConnectionStringBuilder