Migration to Google.Cloud.Spanner.Data 2.0
Google.Cloud.Spanner.Data version 2.0 includes a number of breaking changes compared with version 1.0. We expect that most users will not be affected by these changes, particularly when default settings are used. For users who are affected, this document should help you to migrate your application to the 2.0 version of the libraries.
If you have any problems with the breaking changes and they're not covered in this document, please file an issue so we can help you further.
Configuration changes
SpannerOptions
has been removed completely. See the configuration guide for more details, but for migration purposes:KeepAliveInterval
is replaced bySessionPoolOptions.IdleSessionRefreshDelay
MaximumPooledSessions
has no direct equivalent in 2.0; once a session is part of the pool, it will be refreshed as necessary until it is evicted.MaximumActiveSessions
is now only present inSessionPoolOptions
MaximumGrpcChannels
is specified in the connection stringLogLevel
is controlled on a per-logger basis; this property onSpannerOptions
was equivalent to changingLogger.DefaultLogger.LogLevel
.PoolEvictionDelay
is now only present inSessionPoolOptions
ResourcesExhaustedBehavior
has moved toSessionPoolOptions
Timeout
is specified in the connection stringMaximumConcurrentSessionCreates
is now only present inSessionPoolOptions
ClientPool
has been removed in 2.0. Its functionality has largely been replaced bySessionPoolManager
. It is expected that the default session pool manager will be appropriate for most use cases, but you can associate aSessionPoolManager
with theSpannerConnectionStringBuilder
used to build a connection for more advanced situations.ResourcesExhaustedBehavior
has moved to Google.Cloud.Spanner.V1, as it is now configured inSessionPoolOptions
.- Loggers are configured on a
SessionPoolManager
basis
Breaking changes in connection, command and transaction types
- The
SpannerCommandTextBuilder(string)
constructor has been removed. The equivalent functionality is available via the staticSpannerCommandTextBuilder.FromCommandText
method. SpannerTransaction.CommitAsync
returns aTask<DateTime>
rather than aTask<DateTime?>
. The server will always return a commit timestamp, so the task's result would never have been null in 1.0 anyway. Client code should be able to use the resultingTask<DateTime>
more easily in most cases.SpannerConnection
andSpannerConnectionStringBuilder
no longer exposeGetCredentials
method. There is no direct equivalent in 2.0; please file an issue if you rely on this functionality.SpannerConnection.ClearPooledResourcesAsync
is replaced bySpannerConnection.ShutdownSessionPoolAsync
. After this is called, no further sessions can be created with the associated session pool. If you need to control sessions in a more fine-grained way (for example, shutting down one session pool but then creating new sessions) you can associate a newSessionPoolManager
instance with theSpannerConnectionStringBuilder
used to build a connection. See the configuration guide for an example of this.SpannerTransaction.CommitAsync
now accepts a cancellation token. This defaults toCancellationToken.None
, so existing source code should still compile, but this is a binary-incompatible change.
Miscellaneous breaking changes
SpannerDbType.StructOf
has been replaced bySpannerDbType.ForStruct
, using the newSpannerStruct
type.- .NET Standard 1.5 is no longer supported; only .NET 4.5 and .NET Standard 2.0 are supported targets.
Breaking changes in Google.Cloud.Spanner.V1
Users of the ADO.NET implementation in Google.Cloud.Spanner.Data will rarely need to directly refer to the types in Google.Cloud.Spanner.V1, but some low-level users may wish to do so.
The previous Google.Cloud.Spanner.V1.SessionPool
class has been
replaced by a completely new implementation, with a new API and some
changes to the corresponding SessionPoolOptions
class. The new
SessionPool
manages transactions as well as sessions, so the
TransactionPool
class from 1.0 has been removed. PooledSession
instances are acquired from the session pool (and must be released
appropriately). These are automatically refreshed (and eventually
evicted) by the session pool.
The ExecuteSqlStream
and GetSqlStreamReader
methods on
SpannerClient
have been removed, along with
SpannerClientSettings.ExecuteSqlStreamSettings
. The
SpannerClient.ExecuteStreamingSql
method is responsible for
executing SQL and returning the results in a stream;
the PooledSession.ExecuteSqlStreamReader
method returns a
ReliableStreamReader
.
SpannerSettings.AllowImmediateTimeouts
has been removed; this is
now solely in the ADO.NET provider.
Changes in Google.Cloud.Spanner.V1.Internal
The Google.Cloud.Spanner.V1 package exposes some types in the Google.Cloud.Spanner.V1.Internal namespace, for use by Google.Cloud.Spanner.Data. These types were not intended for use by third-party code, so this document does not go into detail around the changes in this namespace.
Execution-time behavior changes
- Null values are returned as
DBNull.Value
by default rather than the CLR default value for the type. Array and struct elements use a null value where feasible, but throwInvalidCastException
when requested to be converted to a non-nullable value type. The 1.0 behavior can be requested using theUseClrDefaultForNull
connection string option. Hashtable
is no longer used as a default type for struct values. It can still be specified explicitly. The new default isDictionary<string, object>
.