Google.Cloud.Spanner.Data - Class SpannerConnectionStringBuilder (5.0.0-beta02)

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

Reference documentation and code samples for the Google.Cloud.Spanner.Data 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

Constructors

SpannerConnectionStringBuilder()

public SpannerConnectionStringBuilder()

Creates a new SpannerConnectionStringBuilder.

SpannerConnectionStringBuilder(string, GoogleCredential)

public SpannerConnectionStringBuilder(string connectionString, GoogleCredential googleCredential)

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

Parameters
Name	Description
`connectionString`	`string` 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)

public SpannerConnectionStringBuilder(string connectionString, ChannelCredentials credentials = null)

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

Parameters
Name	Description
`connectionString`	`string` A connection string of the form Data Source=projects/{project}/instances/{instance}/databases/{database};[Host={hostname};][Port={portnumber}]. Must not be null.
`credentials`	`ChannelCredentials` 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.

SpannerConnectionStringBuilder(string, ChannelCredentials, SessionPoolManager)

[Obsolete("Use overloads accepting credentials, then set the SessionPoolManager property", false)]
public SpannerConnectionStringBuilder(string connectionString, ChannelCredentials credentials, SessionPoolManager sessionPoolManager)

Creates a new SpannerConnectionStringBuilder with the given connection string, optional credential, and session pool manager.

Parameters
Name	Description
`connectionString`	`string` A connection string of the form Data Source=projects/{project}/instances/{instance}/databases/{database};[Host={hostname};][Port={portnumber}]. Must not be null.
`credentials`	`ChannelCredentials` The credential to use for the connection. May be null.
`sessionPoolManager`	`SessionPoolManager` The session pool manager to use. Must not be null.

Properties

AllowImmediateTimeouts

public bool AllowImmediateTimeouts { get; set; }

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

Property Value
Type	Description
`bool`

ClrToSpannerTypeDefaultMappings

public string ClrToSpannerTypeDefaultMappings { get; set; }

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.

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

public string CredentialFile { get; set; }

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

Property Value
Type	Description
`string`

DataSource

public string DataSource { get; set; }

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

Property Value
Type	Description
`string`

DatabaseName

public DatabaseName DatabaseName { get; set; }

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.

Property Value
Type	Description
`Google.Cloud.Spanner.Common.V1.DatabaseName`

DatabaseRole

public string DatabaseRole { get; set; }

The database role for the sessions created by this connection.

Property Value
Type	Description
`string`

DirectedReadOptions

public DirectedReadOptions DirectedReadOptions { get; set; }

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.

Property Value
Type	Description
`Google.Cloud.Spanner.V1.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

public EmulatorDetection EmulatorDetection { get; set; }

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

Property Value
Type	Description
`EmulatorDetection`

Remarks

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

EnableGetSchemaTable

public bool EnableGetSchemaTable { get; set; }

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.

Property Value
Type	Description
`bool`

EnableLeaderRouting

public bool EnableLeaderRouting { get; set; }

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

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

public string EndPoint { get; }

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

Property Value
Type	Description
`string`

Host

public string Host { get; set; }

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

Property Value
Type	Description
`string`

this[string]

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

Gets or sets the value associated with the specified key.

Parameter
Name	Description
`keyword`	`string` 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	Description
`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

public bool LogCommitStats { get; set; }

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

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

public int MaxConcurrentStreamsLowWatermark { get; set; }

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.

Property Value
Type	Description
`int`

MaximumGrpcChannels

public int MaximumGrpcChannels { get; set; }

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

Property Value
Type	Description
`int`

Port

public int Port { get; set; }

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

Property Value
Type	Description
`int`

Project

public string Project { get; }

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

Property Value
Type	Description
`string`

SessionPoolManager

public SessionPoolManager SessionPoolManager { get; set; }

The SessionPoolManager to use for server interactions.

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

public string SpannerDatabase { get; }

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.

Property Value
Type	Description
`string`

SpannerInstance

public string SpannerInstance { get; }

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

Property Value
Type	Description
`string`

SpannerToClrTypeDefaultMappings

public string SpannerToClrTypeDefaultMappings { get; set; }

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.

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

public int Timeout { get; set; }

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

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

public bool UseClrDefaultForNull { get; set; }

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

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

public override void Clear()

Clears the contents of the DbConnectionStringBuilder instance.

Overrides

DbConnectionStringBuilder.Clear()

Exceptions
Type	Description
`NotSupportedException`	The DbConnectionStringBuilder is read-only.

WithDatabase(string)

public SpannerConnectionStringBuilder WithDatabase(string database)

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

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

Returns
Type	Description
`SpannerConnectionStringBuilder`	A new instance of SpannerConnectionStringBuilder