Version history

Version 5.0.0, released 2025-04-16

New features

Note: V5.0.0 contains all the new features added in previous beta versions V5.0.0-beta0x. Here, we highlight those that introduced breaking changes with respect to previous stable versions V4.x.x.

  • Transactions support SpannerTransactionCreationOptions and SpannerTransactionOptions. BREAKING CHANGE: SpannerConection methods that open a transaction, like BeginTransacion, Open and RunWithRetriableTransaction sets of methods now accept both option types as parameter, while some of the previously existing methods have been deprecated and will be removed on the next major version.
  • After a successfull commit or rollback, the transaction is disposed. BREAKING CHANGE: Attempting to use a disposed transaction will result in a client side error. See the Google.Cloud.Spanner.Data.SpannerTransaction.DisposeBehavior documentation for more information.
  • Add support for FLOAT32 BREAKING CHANGE: The default mapping for values of CLR type decimal was FLOAT64 and it is now Numeric. The default mapping for values of CLR type float was FLOAT64 and it is now FLOAT32.
  • Support inline transactions. BREAKING CHANGE: In supporting inline transactions the main breaking change is behavioral: transactions are not prewarmed, instead they are acquired as needed, mainly through inlining transaction creation in the first command that attempts to use a transaction. The method Google.Cloud.Spanner.V1.PooledSession.WithFreshTransactionOrNewAsync has been removed, as a transaction is not created by the session until command execution. Use instead Google.Cloud.Spanner.V1.PooledSession.RefreshedOrNewAsync which returns a new PooledSession instance that either represents the same session but with no transaction associated to it or a newly acquired session. Since transactions are not prewarmed, the session pool does not need to distinguish between read-only and read-write session/transaction pairs. In the statistics classes that may be used for diagnostic purposes all properties distinguishing between read-only and read-write statistics have been removed. Similarly, Google.Cloud.Spanner.V1.SessionPoolOptions.WriteSessionsFraction has bee removed.
  • BREAKING CHANGE: Remove Obsolete code that had been introduced before v5.0.0-beta01.

Version 5.0.0-beta06, released 2025-04-14

New features

  • Support transaction tag through SpannerTransactionOptions. (commit 382cdaf)
  • Support commit priority through SpannerTransactionOptions. (commit 12da3b6)
  • Support commit timeout through SpannerTransactionOptions. (commit bf50e98)
  • BREAKING CHANGE Make all transaction types support SpannerTransactionOptions (commit 7e9f553)
  • Support log commit stats through SpannerTransactionOptions. (commit d7251a3)
  • Support transaction dispose behavior through SpannerTransactionOptions. (commit 41e716a)
  • Add a last field in the PartialResultSet (commit 872c61a)
  • A new enum IsolationLevel is added (commit c1059d1)
  • A new field isolation_level is added to message .google.spanner.v1.TransactionOptions (commit c1059d1)
  • Add instance partitions field in backup proto (commit 08930c5)
  • Add AddSplitPoints API (commit adacd9b)
  • Exposing InstanceType in Instance configuration (to define PROVISIONED or FREE spanner instance) (commit 1a75431)
  • Exposing FreeInstanceMetadata in Instance configuration (to define the metadata related to FREE instance type) (commit 1a75431)
  • Exposing storage_limit_per_processing_unit in InstanceConfig (commit 1a75431)
  • Exposing QuorumType in InstanceConfig (commit 1a75431)
  • Exposing FreeInstanceAvailability in InstanceConfig (commit 1a75431)
  • Add UUID in Spanner TypeCode enum (commit cacdc3b)
  • Add the last statement option to ExecuteSqlRequest and ExecuteBatchDmlRequest (commit 85f11dc)

Documentation improvements

  • A comment for field rows in message .google.spanner.v1.ResultSet is changed (commit 872c61a)
  • A comment for field stats in message .google.spanner.v1.ResultSet is changed (commit 872c61a)
  • A comment for field precommit_token in message .google.spanner.v1.ResultSet is changed (commit 872c61a)
  • A comment for field values in message .google.spanner.v1.PartialResultSet is changed (commit 872c61a)
  • A comment for field chunked_value in message .google.spanner.v1.PartialResultSet is changed (commit 872c61a)
  • A comment for field stats in message .google.spanner.v1.PartialResultSet is changed (commit 872c61a)
  • A comment for field precommit_token in message .google.spanner.v1.PartialResultSet is changed (commit 872c61a)
  • A comment for message ResultSetMetadata is changed (commit 872c61a)
  • A comment for field row_type in message .google.spanner.v1.ResultSetMetadata is changed (commit 872c61a)
  • A comment for message ResultSetStats is changed (commit 872c61a)
  • A comment for field query_plan in message .google.spanner.v1.ResultSetStats is changed (commit 872c61a)
  • A comment for field row_count_lower_bound in message .google.spanner.v1.ResultSetStats is changed (commit 872c61a)
  • A comment for enum value READ_LOCK_MODE_UNSPECIFIED in enum ReadLockMode is changed (commit c1059d1)
  • A comment for enum value PESSIMISTIC in enum ReadLockMode is changed (commit c1059d1)
  • A comment for enum value OPTIMISTIC in enum ReadLockMode is changed (commit c1059d1)
  • Fix typo timzeone -> timezone (commit c1d4fff)
  • A comment for method ListInstanceConfigs in service InstanceAdmin is changed (commit 1a75431)
  • A comment for method CreateInstanceConfig in service InstanceAdmin is changed (commit 1a75431)
  • A comment for method UpdateInstanceConfig in service InstanceAdmin is changed (commit 1a75431)
  • A comment for method ListInstanceConfigOperations in service InstanceAdmin is changed (commit 1a75431)
  • A comment for method CreateInstance in service InstanceAdmin is changed (commit 1a75431)
  • A comment for method UpdateInstance in service InstanceAdmin is changed (commit 1a75431)
  • A comment for method CreateInstancePartition in service InstanceAdmin is changed (commit 1a75431)
  • A comment for method UpdateInstancePartition in service InstanceAdmin is changed (commit 1a75431)
  • A comment for method ListInstancePartitionOperations in service InstanceAdmin is changed (commit 1a75431)
  • A comment for method MoveInstance in service InstanceAdmin is changed (commit 1a75431)
  • A comment for field location in message .google.spanner.admin.instance.v1.ReplicaInfo is changed (commit 1a75431)
  • A comment for enum value GOOGLE_MANAGED in enum Type is changed (commit 1a75431)
  • A comment for enum value USER_MANAGED in enum Type is changed (commit 1a75431)
  • A comment for field replicas in message .google.spanner.admin.instance.v1.InstanceConfig is changed (commit 1a75431)
  • A comment for field optional_replicas in message .google.spanner.admin.instance.v1.InstanceConfig is changed (commit 1a75431)
  • A comment for field base_config in message .google.spanner.admin.instance.v1.InstanceConfig is changed (commit 1a75431)
  • A comment for field storage_utilization_percent in message .google.spanner.admin.instance.v1.AutoscalingConfig is changed (commit 1a75431)
  • A comment for enum DefaultBackupScheduleType is changed (commit 1a75431)
  • A comment for enum value NONE in enum DefaultBackupScheduleType is changed (commit 1a75431)
  • A comment for enum value AUTOMATIC in enum DefaultBackupScheduleType is changed (commit 1a75431)
  • A comment for field node_count in message .google.spanner.admin.instance.v1.Instance is changed (commit 1a75431)
  • A comment for field processing_units in message .google.spanner.admin.instance.v1.Instance is changed (commit 1a75431)
  • A comment for field default_backup_schedule_type in message .google.spanner.admin.instance.v1.Instance is changed (commit 1a75431)
  • A comment for message CreateInstanceConfigRequest is changed (commit 1a75431)
  • A comment for field instance_config in message .google.spanner.admin.instance.v1.CreateInstanceConfigRequest is changed (commit 1a75431)
  • A comment for message UpdateInstanceConfigRequest is changed (commit 1a75431)
  • A comment for message DeleteInstanceConfigRequest is changed (commit 1a75431)
  • A comment for field filter in message .google.spanner.admin.instance.v1.ListInstanceConfigOperationsRequest is changed (commit 1a75431)
  • A comment for field operations in message .google.spanner.admin.instance.v1.ListInstanceConfigOperationsResponse is changed (commit 1a75431)
  • A comment for field node_count in message .google.spanner.admin.instance.v1.InstancePartition is changed (commit 1a75431)
  • A comment for field processing_units in message .google.spanner.admin.instance.v1.InstancePartition is changed (commit 1a75431)
  • A comment for field referencing_backups in message .google.spanner.admin.instance.v1.InstancePartition is changed (commit 1a75431)
  • A comment for field parent in message .google.spanner.admin.instance.v1.ListInstancePartitionsRequest is changed (commit 1a75431)
  • A comment for field unreachable in message .google.spanner.admin.instance.v1.ListInstancePartitionsResponse is changed (commit 1a75431)
  • A comment for field filter in message .google.spanner.admin.instance.v1.ListInstancePartitionOperationsRequest is changed (commit 1a75431)
  • A comment for field instance_partition_deadline in message .google.spanner.admin.instance.v1.ListInstancePartitionOperationsRequest is changed (commit 1a75431)
  • A comment for field operations in message .google.spanner.admin.instance.v1.ListInstancePartitionOperationsResponse is changed (commit 1a75431)

Breaking changes

  • All transaction types support SpannerTransactionOptions; this is breaking compared with previous betas, but not compared with previous GA.

Version 5.0.0-beta05, released 2024-11-07

New features

Documentation improvements

  • A comment for field node_count in message spanner.admin.instance.v1.Instance is changed (commit 905160d)
  • A comment for field processing_units in message spanner.admin.instance.v1.Instance is changed (commit 905160d)
  • Update comment for PROFILE QueryMode (commit 16d3bbb)

Version 5.0.0-beta04, released 2024-08-13

Bug fixes

  • Retriable transactions should be released after successful commit (commit f2c7840)
  • Partitioned updates are only executed on an ephemeral transaction (commit d88a807)
  • Timestamp bound reads and queries are only executed on an ephemeral transaction (commit f8f8235)

New features

  • Add resource reference annotation to backup schedules (commit 8403eb4)
  • Add edition field to the instance proto (commit 2b59065)
  • BREAKING CHANGE Fully support SpannerTransactionCreationOptoins (commit 34a25d3)
  • Support excluding a transaction from change streams (commit 9e3ec98)
  • Add protobuf column support for the data layer (commit 8646000)
  • Add support for protobuf typed colums for DDL (commit 551d519)
  • Add support for Cloud Spanner Incremental Backups (commit aa5a584)
  • Add support for Cloud Spanner Scheduled Backups (commit ac15c11)
  • BREAKING CHANGE Commit/Rollback releases sessions to the pool (commit 86fa6a6)
  • BREAKING CHANGE Support detached sessions/transactions (commit cfa961e)
  • Add field order_by in spanner.proto (commit a5f7b22)
  • Add field lock_hint in spanner.proto (commit a5f7b22)
  • Add support for multi region encryption config (commit bb95bbf)
  • Add RESOURCE_EXHAUSTED to the list of retryable error codes (commit fbb0099)
  • Add IServiceCollection extension methods for client registration where an IServiceProvider is required. (commit 022fab2)

Documentation improvements

  • Add an example to filter backups based on schedule name (commit 8403eb4)
  • Clarify documentation around session acquisition vs. transaction creation (commit 9aae25e)
  • Fix linting for several doc comments (commit bb95bbf)

Breaking changes

  • Some SpannerConnection begin transaction methods that had only been released in beta versions of the library have been removed. (commit 34a25d3)
  • The AmbientTransactionOptions class is split in SpannerTransactionCreationOptions and SpannerTransactionOptions, with all original options moving to one or the other. The SpannerConnection.Open set of methods that received an AmbientTransactionOptions before now receive one SpannerTransactionCreationOptions and one SpannerTransactionOptions. (commit 1541b99)
  • After a successfull commit or rollback, the transaction is disposed and may not be used again. See the Google.Cloud.Spanner.Data.SpannerTransaction.DisposeBehavior documentation for more information. (commit 86fa6a6)

Version 5.0.0-beta03, released 2024-04-19

New features

Breaking changes

  • The default mapping for values of CLR type decimal was FLOAT64 and it is now Numeric. (commit 9824a9c)
  • The default mapping for values of CLR type float was FLOAT64 and it is now FLOAT32. (commit 83700dd)
  • Support for specifying a maximum commit delay was added in v5.0.0-beta02. Unfortunately properties and methods for this feature were erroneously named using "commit delay" instead of "max commit delay". All such names are being corrected in this commit. (commit 03e66d7)
  • Remove Obsolete code that had been introduced before v5.0.0-beta01. (commit fdc4bff)

Version 5.0.0-beta02, released 2024-04-04

New features

  • Ambient transactions support commit delays (commit f4b4208)
  • Implicit transactions support commit delay (commit af15aaf)
  • Explicit transactions support commit delays (commit 4934cfd)
  • Adding EXPECTED_FULFILLMENT_PERIOD to the indicate instance creation times (with FULFILLMENT_PERIOD_NORMAL or FULFILLMENT_PERIOD_EXTENDED ENUM) with the extended instance creation time triggered by On-Demand Capacity Feature (commit 20bb7e7)
  • Change netstandard2.1 target to netstandard2.0 (commit 82bea85)
  • SpannerCommand supports directed reads (commit dfeb2c0)
  • SpannerConnection supports directed reads (commit d7620e5)
  • PooledSession supports directed reads (commit e26c8aa)
  • Add PG.OID support (commit 43818f3)
  • Update TransactionOptions to include new option exclude_txn_from_change_streams (commit 89764a0)
  • Add field for multiplexed session in spanner.proto (commit 4bdb639)

Documentation improvements

Other changes

(This isn't a breaking change unless code is compiled with warnings as errors, but we do expect to remove these methods entirely in v6.0 of this library.)

Version 5.0.0-beta01, released 2024-02-09

Bug fixes

  • Have SpannerTransaction check if it has been disposed before executing commands. (commit c97a70a)

New features

Documentation improvements

BREAKING CHANGE: In supporting inline transactions the main breaking change is behavioral: transactions are not prewarmed, instead they are acquired as needed, mainly through inlining transaction creation in the first command that attempts to use a transaction. The method Google.Cloud.Spanner.V1.PooledSession.WithFreshTransactionOrNewAsync has been removed, as a transaction is not created by the session until command execution. Use instead Google.Cloud.Spanner.V1.PooledSession.RefreshedOrNewAsync which returns a new PooledSession instance that either represents the same session but with no transaction associated to it or a newly acquired session. Since transactions are not prewarmed, the session pool does not need to distinguish between read-only and read-write session/transaction pairs. In the statistics classes that may be used for diagnostic purposes all properties distinguishing between read-only and read-write statistics have been removed. Similarly, Google.Cloud.Spanner.V1.SessionPoolOptions.WriteSessionsFraction has bee removed.

Version 4.6.0, released 2023-06-26

Bug fixes

  • Makes transactions marked as DisposedBehaviour.Detach actually detach from the session pool. (commit ab7526f)
  • Dispose result streams (commit d92f88e)

New features

  • Support dataBoostEnabled field in partitioned read and execute SQL operations. (commit 25531f2)
  • Add DdlStatementActionInfo and add actions to UpdateDatabaseDdlMetadata (commit 2bdd8bc)
  • Add support for UpdateDatabase in Cloud Spanner (commit 3b98d26)

Documentation improvements

Version 4.5.0, released 2023-05-04

New features

  • Introduce data_boost_enabled; this is currently not exposed via Google.Cloud.Spanner.Data (commit 983fbe6)

Documentation improvements

  • Formatting fix for the logging documentation

Version 4.4.0, released 2023-03-09

New features

Version 4.3.0, released 2023-02-08

New features

Version 4.2.0, released 2022-11-03

Bug fixes

New features

  • Update transaction.proto to include different lock modes (issue 9236) (commit 4fed510)
  • Add support for FGAC in Spanner (commit 4e7eddb)
  • Update result_set.proto to return undeclared parameters in ExecuteSql API (commit cb86746)
  • Support dependency injection of SpannerConnection (commit f29a7f9)
  • Support custom GoogleCredential in SpannerConnectionStringBuilder/SpannerConnection (commit 898d3b3)
  • Added support for JSONB type in the PostgreSQL dialect. Note that JSONB arrays are not supported server-side yet.

Version 4.1.0, released 2022-09-20

New features

  • Add custom instance config operations (commit 58cadb7)
  • Adds auto-generated CL for googleapis for jsonb (commit b8b8752)
  • Add ListDatabaseRoles API to support role based access control (commit 98e2aae)
  • Adding two new fields for Instance create_time and update_time (commit d002223)

Version 4.0.0, released 2022-06-22

First GA release of v4.0. Please see release notes for 4.0.0-beta01 and 4.0.0-beta02 for details of breaking changes since v3.x

Bug fixes

Version 4.0.0-beta02, released 2022-06-13

New features

BREAKING CHANGE: The Key classes (Key, KeyRange, KeySet) used to be immutable, and support equality as well as overriding ToString. As conversions from CLR to Spanner values now depend on the connection string, there's now an overload for ToString accepting a ConnectioStringBuilder, but no support for equality. We don't anticipate this breaking customers except perhaps for testing purposes.

Version 4.0.0-beta01, released 2022-06-09

This is the first version of this package to depend on GAX v4.

There are some breaking changes, both in GAX v4 and in the generated code. The changes that aren't specific to any given API are described in the Google Cloud documentation. We don't anticipate any changes to most customer code, but please file a GitHub issue if you run into problems.

The most important change in this release is the use of the Grpc.Net.Client package for gRPC communication, instead of Grpc.Core. When using .NET Core 3.1 or .NET 5.0+ this should lead to a smaller installation footprint and greater compatibility (e.g. with Apple M1 chips). Any significant change in a core component comes with the risk of incompatibility, however - so again, please let us know if you encounter any issues.

New features

  • Add an adapter for an ILogger to a Spanner Logger (commit 5b7556b)
    • This is an interim step to allow logs to be easily unified (to ILogger) before we eventually remove the Spanner internal logging system entirely.
  • Use self-signed JWTs in Spanner clients (commit d465906)
  • Add Session creator role (commit ffa9c84)
  • Allow default conversions between Spanner and the CLR to be specified via connection string options

Documentation improvements

Version 3.15.1, released 2022-05-05

Bug fixes

  • Make SpannerTransaction pick up SpannerConnection.LogCommitStats as documented. (commit db5c55d)

Version 3.15.0, released 2022-05-04

New features

  • Make ephemeral transactions retry on abort. (commit 97faf1c)
  • Introduced SpannerDate struct for date-only values. (The default type for DATE columns is still DateTime.) (commit 4e3b94e)
  • Introduced PgNumeric struct for support of the NUMERIC data type in the Postgres dialect. (commit 87c3306)

Version 3.14.0, released 2022-03-28

New features

Version 3.13.0, released 2021-12-01

Version 3.12.0, released 2021-08-24

  • Commit 7c6a6f1: feat: add support for JSON data type in Spanner (issue 6390)
  • Commit ac367e2: feat: Regenerate all APIs to support self-signed JWTs
  • Commit 61938b6:
    • feat(Spanner): Support comments and statement hints in untyped commands.
    • Alternative to issue 6848
    • Closes issue 6847
  • Commit d26b04c: fix: address review comments
  • Commit d2025be: fix: use logger from SpannerSettings
  • Commit b34f6f4: cleanup: fix comment + remove unnecessary import
  • Commit fc7a41b: test: remove connectionstring tests and add settings test
  • Commit 6016ef0:
    • feat: support custom SpannerSettings in SessionPoolManager
    • Support setting custom SpannerSettings when creating a SessionPoolManager.
  • Commit 0ab6b8b:
    • feat: allow adding an additional version header
    • Allows adding an additional version header to the connection string. This will be
    • added to the x-goog-api-client header that is used by the underlying Spanner client.
    • Only a fixed set of values may be set for the header (currently only 'efcore' is
    • allowed), and the property is not intended for public use.
  • Commit 250124f:
    • fix: synchronize access to the underlying transaction for ambient transactions (issue 6616)
      • fix: synchronize access to the underlying transaction for ambient transactions
    • Synchronizes access to the underlying Spanner transaction to prevent
    • multiple transactions from being created if parallel commands are
    • executed on the ambient transaction.
      • test: add integration test
      • fix: use Lazy for initialization
      • chore: address review comments
      • fix: remove unnecessary read call

Version 3.11.0, released 2021-07-09

Version 3.10.0, released 2021-06-28

Version 3.9.0, released 2021-06-09

  • Commit 0fb438e: feat: add query_optimizer_statistics_package support (see below)

The optimizer statistics package can be set through QueryOptions, which can be configured through the following mechanisms:

  • At the SpannerConnection level.
  • Through the SPANNER_OPTIMIZER_STATISTICS_PACKAGE environment variable.
  • At a query level.

If the options are configured through multiple mechanisms then:

  • Options set at an environment variable level will override options configured at the SpannerConnection level.
  • Options set at a query-level will override options set at either the SpannerConnection or environment variable level.

If no options are set, the optimizer statistics package will default to the package the database is pinned to. If the database is not pinned to a specific package, then the Cloud Spanner backend will use the "latest" version.

Version 3.8.0, released 2021-05-18

Version 3.7.0, released 2021-04-01

Version 3.6.0, released 2021-03-17

Version 3.5.0, released 2021-02-08

Version 3.4.0, released 2020-12-14

  • Commit 9fb3e43: feat: Database Admin: Adds UpdateDatabaseDdlMetadata.Throttled to indicate when a DDL operation is throttled due to resource constraints.

Version 3.3.0, released 2020-10-01

Version 3.2.0, released 2020-09-10

Version 3.1.0, released 2020-07-14

Version 3.1.0-beta01, released 2020-06-16

  • Commit 5b07f5a: fix: Roll back uncommitted (and not-rolled-back) read/write transactions on session release
  • Commit 7de296c: fix: Workaround for emulator bug of not populating ExecuteBatchDmlResponse.status
  • Commit a4455b9: feat: Spanner emulator support in Google.Cloud.Spanner.Data
  • Commit 947a573: fix: Regenerate all clients with more explicit documentation
  • Commit 0b01e4b: feat: add support for spanner emulator detection in clients (issue 4928)

Note that while the SpannerNumeric type has been added to the Google.Cloud.Spanner.V1 library, it is not currently integrated with the rest of the code, and should be ignored at this time.

Version 3.0.0, released 2020-04-15

GA release targeting GAX 3.0.0. No new features compared with 3.0.0-beta02, other than small resource name improvements for backups.

Version 3.0.0-beta02, released 2020-03-18

  • Commit c5090d1:
    • feat: Adds the ability to set QueryOptions when running Cloud Spanner queries.
  • Commit 36f1e1e: Apply gccl header for Spanner clients in Google.Cloud.Spanner.Data
  • Commit f21fd27:
    • feat: Backup support in Database Admin API
    • feat: List operations RPC in Database Admin API

This release depends on the GA version of GAX 3.0.

Version 3.0.0-beta01, released 2020-02-18

This is the first prerelease targeting GAX v3. Please see the breaking changes guide for details of changes to both GAX and code generation.

Version 2.1.0, released 2019-12-12

  • Commit 0740a76: Adds support for retriable transactions
  • Transparent support for batch creation of sessions (to make session creation more efficient)

Version 2.0.0, released 2019-06-03

New features:

  • Batch query support
  • Connection string option to enable SpannerDataReader.GetSchemaTable() to return schema information
  • DML and PDML support
  • Batch DML support
  • Session label support

Breaking changes:

  • Many aspects of configuration have changed. Please refer to the configuration guide, migration guide and connection string options for more details.
  • 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 throw InvalidCastException when requested to be converted to a non-nullable value type. The 1.0 behavior can be requested using the UseClrDefaultForNull connection string option.
  • Hashtable is no longer used as a default type for struct values. It can still be specified explicitly. The new default is Dictionary<string, object>.
  • The libraries no longer target netstandard1.5; only netstandard2.0 and net45 are supported

Version 1.0.0, released 2017-12-05

Initial release.