Connection string options
Spanner connection strings support the following options:
Data Source
The project, instance and optionally database to use. The format is
projects/{project}/instances/{instance}/databases/{database}
, with
the databases/{database}
part being optional.
Examples:
- Data Source=projects/my_project/instances/my_instance
- Data Source=projects/my_project/instances/my_instance/databases/my_database
CredentialFile
A path to a JSON service account credential file to use. If this is
not specified, the application default credentials will be used.
(These are provided automatically when running on Google Cloud
Platform, or a JSON service account credential file can be specified
with the GOOGLE_APPLICATION_CREDENTIALS
environment variable.)
Example:
- CredentialFile=/path/to/credentials.json
EnableGetSchemaTable
When set to true (and when targeting .NET 4.5 or .NET Standard 2.0;
the method doesn't exist in .NET Standard 1.x),
SpannerDataReader.GetSchemaTable()
will return available schema information for the query in the form
of a DataTable
. See the method documentation for details of the columns
returned.
Example:
- EnableGetSchemaTable=true
UseClrDefaultForNull
By default, null values returned by Spanner are handled in the following manner:
"Top-level" fields are always converted to DBNull.Value
. This
means that calling reader.GetString(0)
for example will throw an
InvalidCastException
if the value is null. This is compatible
with other ADO.NET providers.
Array and structure elements use the null value for the target type
where possible (reference types and nullable value types), or throw
an InvalidCastException
if the target type is a non-nullable value
type. For example, if an array field has values [1, NULL, 2]
in Spanner,
then requesting that field with reader.GetFieldValue<int[]>("field")
will
throw an exception, whereas reader.GetFieldValue<int?[]>("field")
will return a nullable integer array where the second element is a
null value.
When UseClrDefaultForNull
is set to true, null values returned by
Spanner will be converted into the default CLR value for the
requested type. This was the behavior for Google.Cloud.Spanner.Data
v1.0.
Example:
- UseClrDefaultForNull=true
Timeout
The default timeout used for SpannerCommand.CommandTimeout
,
SpannerTransaction.CommitTimeout
, and other Spanner network
operations. Defaults to 60 seconds.
Example:
- Timeout=30
AllowImmediateTimeouts
When set to False, a timeout of 0 means an indefinite timeout. When set to True, a timeout of 0 means an immediate timeout. Defaults to False.
Example:
- AllowImmediateTimeouts=true
MaximumGrpcChannels
The maximum number of gRPC channels to use per connection using the same settings. Defaults to 4. This setting rarely needs to be modified.
Example:
- MaximumGrpcChannels=8
MaxConcurrentStreamsLowWatermark
The maximum number of concurrent streams per gRPC channel before using a new channel. Defaults to 20. This setting rarely needs to be modified.
Example:
- MaxConcurrentStreamsLowWatermark=30
Host and Port
These control the Spanner service to connect to. These are primarily available for testing purposes.
Examples:
- Host=alternative-spanner.googleapis.com; Port=1443
EmulatorDetection
Controls the effect of the SPANNER_EMULATOR_HOST
environment
variable on which Spanner service the client connects to.
Possible values:
- None (the default)
- ProductionOnly
- EmulatorOnly
- EmulatorOrProduction
The effects of these values are described in detail in the EmulatorDetection enum documentation.
Example:
- EmulatorDetection=EmulatorOrProduction
ClrToSpannerTypeDefaultMappings
Option to configure the default CLR type to SpannerDbType
mapping.
This option is only used if the SpannerDbType
and DbType
of the SpannerParameter
are not explicitly provided. Currently only decimal
and DateTime
CLR types are supported.
The valid type mappings for decimal
are:
- DecimalToFloat64 -
decimal
CLR type will map toSpannerDbType.Float64
. - DecimalToNumeric -
decimal
CLR type will map toSpannerDbType.Numeric
. This should be used while working with Google Standard SQL dialect only. - DecimalToPgNumeric -
decimal
CLR type will map toSpannerDbType.PgNumeric
. This should be used while working with PostgreSQL dialect only.
The valid type mappings for DateTime
are:
- DateTimeToDate -
DateTime
CLR type will map toSpannerDbType.Date
. - DateTimeToTimestamp -
DateTime
CLR type will map toSpannerDbType.Timestamp
.
The mapping can be provided as comma separated values. For each CLR type, at most one mapping may be provided.
Examples:
- ClrToSpannerTypeDefaultMappings=DecimalToFloat64
- ClrToSpannerTypeDefaultMappings=DecimalToNumeric,DateTimeToTimestamp
SpannerToClrTypeDefaultMappings
Option to configure the default SpannerDbType
to CLR type mappings. This option is only used if the
CLR type of the value being read is not explicitly provided while reading the data from the database,
for example using an indexer: reader["fieldName"]
. Currently only SpannerDbType.Date
is supported.
The valid type mappings for SpannerDbType.Date
are:
- DateToDateTime -
SpannerDbType.Date
will map toDateTime
. - DateToSpannerDate -
SpannerDbType.Date
will map toSpannerDate
.
Examples:
- SpannerToClrTypeDefaultMappings=DateToDateTime
- SpannerToClrTypeDefaultMappings=DateToSpannerDate
DatabaseRole
The database role associated with this connection string. This option is only used if Fine Grained Access Control is enabled for the Spanner instance. If Fine Grained Access Control is enabled for this Spanner instance, and a database role is not provided the default (public) role will be used.
Example (given you have created the "read" role):
- DatabaseRole=read