google-cloud-go/spanner のバージョン間差分リーディングスレ

[apstndb]

「詳解 google-cloud-go/spanner」 では google-cloud-go v0.38.0 の時点でのセッションとトランザクション周りを解説している。
それからの間に多くの更新があるため、リリースごとにメモしていく。

なお、 all: auto-regenerate gapics などの自動生成クライアントの更新による差分、 spansql, spannertest, その他テスト周りの更新のみの差分については記載しない。

下記は差分を spanner 以下の変更だけに絞って読む方法の一例

$ TIG_DIFF_OPTS=--ignore-space-change tig v0.38.0...spanner/v1.4.0 -- spanner

Refs

https://medium.com/google-cloud-jp/%E8%A9%B3%E8%A7%A3-google-cloud-go-spanner-%E3%83%88%E3%83%A9%E3%83%B3%E3%82%B6%E3%82%AF%E3%82%B7%E3%83%A7%E3%83%B3%E7%B7%A8-6b63099bd7fe
https://medium.com/google-cloud-jp/%E8%A9%B3%E8%A7%A3-google-cloud-go-spanner-%E3%82%BB%E3%83%83%E3%82%B7%E3%83%A7%E3%83%B3%E7%AE%A1%E7%90%86%E7%B7%A8-d805750edc75

[apstndb]

v0.38.0 〜 spanner/v1.0.0

https://github.com/googleapis/google-cloud-go/releases/tag/spanner%2Fv1.0.0
https://github.com/googleapis/google-cloud-go/releases/tag/v0.46.0

タグを打たれているコミットによると spanner/v1.0.0 = v0.46.2

spanner: Retry "Session not found" for read-only transactions

googleapis/google-cloud-go@5d17c75

Revert "spanner: Retry "Session not found" for read-only transactions"
googleapis/google-cloud-go@090ee50

テストを壊して revert されたらしい。未来にまたやりなおすやつ

spanner: retry aborted PDMLs

googleapis/google-cloud-go@02b9199

PDML は abort されてもクライアント側で内部的にリトライする前提だったがそうではなかったらしく、リトライを実装。

Spanner: prevent rpc timeouts in replenishPool

googleapis/google-cloud-go@1fc0d2f

reprenishPool における CreateSession, DeleteSession では上から渡ってきた context の設定とは無関係にタイムアウトを1分にする。
セッションプールの維持なのでリクエストのレイテンシに無縁なのに対し、 CreateSession には現実的ではないタイムアウトの短さでセッションタイムアウトのログが大量に出るため？

spanner: fix parsing incorrect types/values into a time.Time

googleapis/google-cloud-go@9a7f354

間違えて err ではなく nil を返していてバグがあったらしい

spanner: remove redundant x-goog-api-client header

googleapis/google-cloud-go@4b1db5f

x-goog-api-client はGAPIC が設定するからいらなくなった

spanner: check database name and add a trace span even when using the emulator

googleapis/google-cloud-go@acf4f9b

SPANNER_EMULATOR_HOST 設定時にも database の path が正しいことを検証

spanner: add basic benchserver, enable emulator usage

googleapis/google-cloud-go@da8e77f

SPANNER_EMULATOR_HOST 環境変数対応開始

use gapic client and rely on gax for retries

googleapis/google-cloud-go@9f33eb1

GAPIC & GAX の利用開始。これまでは生の gRPC コネクションと spannerpb を使っていた。

spanner: make PartitionedUpdate treat query parameters

googleapis/google-cloud-go@b1eefbd

PDML で query parameter が使われていなかったやつ。

Author: Yuki Ito <[email protected]>

[apstndb]

〜 spanner/v1.1.0

https://github.com/googleapis/google-cloud-go/releases/tag/spanner%2Fv1.1.0

The String() method of NullString, NullTime and NullDate will now return
an unquoted string instead of a quoted string. This is a BREAKING CHANGE.
If you relied on the old behavior, please use fmt.Sprintf("%q", T).
spanner: String() should return unquoted string

googleapis/google-cloud-go@b467917

NullString 等の型がダブルクオート付きで出力されていたのを生の型と同じ出力にした。

The Spanner client will now use the new BatchCreateSessions RPC to initialize
the session pool. This will improve the startup time of clients that are
initialized with a minimum number of sessions greater than zero
(i.e. SessionPoolConfig.MinOpened>0).
spanner: use BatchCreateSessions to init pool

googleapis/google-cloud-go@b246326

今まで spanner.Client が管理していたセッション作成や gRPC コネクションへのセッションの割り当てを責務として持つセッションクライアントを導入。
SessionPoolConfig.MinOpened が設定されている時にはヘルスチェッカーを起動する前のセッションプール初期化時に BatchCreateSessions で一括で確保するようにした。BatchCreateSession は gRPC チャンネルに対応する GAPIC クライアントに対してほぼ均等に分散して並列に発行され、 Session Consumer 経由でセッションプールに入る。
BatchCreateSessions RPC は必ずしも要求した数の SessionCount を一度に返さないから、各チャンネルで要求数取れるまでループするとのこと。

MinOpened をセッション数で割った余りを1つめの GAPIC クライアントに割り振るのはセッション数よりも MinOpened が少ない時に1RPC で済ませたいかららしいけど、もう少しうまく分配できる手があるような気はする。(均等でなくても大したことはないのか)
サーバサイドキャッシュを活かすためにセッションと gRPC チャンネルの割当は基本的に維持する必要があるとのこと。

https://pkg.go.dev/cloud.google.com/go/spanner?tab=doc#pkg-variables

MinOpened のデフォルト値は0から100になった。
WriteSessions のデフォルト値は0から0.2 になった

Spanner clients that are created with the NewClient method will now default
to a minimum of 100 opened sessions in the pool
(i.e. SessionPoolConfig.MinOpened=100). This will improve the performance
of the first transaction/query that is executed by an application, as a
session will normally not have to be created as part of the transaction.
Spanner clients that are created with the NewClientWithConfig method are
not affected by this change.

上のコミットに含まれる

Spanner clients that are created with the NewClient method will now default
to a write sessions fraction of 0.2 in the pool
(i.e. SessionPoolConfig.WriteSessions=0.2). Creating Spanner clients for
read-only purposes should be done using NewClientWithConfig with
SessionPoolConfig.WriteSessions=0.0. Spanner clients that are created with the NewClientWithConfig method are
not affected by this change.

上のコミットに含まれる

The session pool maintenance worker has been improved so it keeps better
track of the actual number of sessions needed. It will now less often delete
and re-create sessions. This can improve the overall performance of
applications with a low transaction rate.

spanner: keep better track of max sessions

googleapis/google-cloud-go@8097922

セッション仕様実績の計算方法を改善して時期尚早なセッションの解放を抑えた。

• 使用セッション最大数記録を session maintainer がヘルスチェック等の時だけ見に行くのではなく、セッション取得時に行うことで一時的なスパイクを見逃さないようにした。
• セッションメンテナンスのサイクルごとに最大セッション数を記録する
• セッションは少なくとも一つのセッションメンテナンスウィンドウ(10分間)が経過するまでは生き残る
  • 早すぎる解放を回避
• shrinkPool, growPool の双方で、一度に削除及び、作成するセッションの最大数を設定した
  • 急すぎるセッションの入れ替わりを抑える
• セッションプールが新しいセッションを作っている時には削除しないようにする

spanner: Fix shrinkPool and enable TestMaintainer

googleapis/google-cloud-go@0599e18

shrinkPool が壊れていたのを修正している。

spanner: use the standard GAX retryer for stream

googleapis/google-cloud-go@fe4e66c

GAX が標準で提供する Retryer を resumableStreamDecoder で使うようにし、 gRPC コードをチェックしてリトライする独自ロジックをなくした。

spanner: use a retry for Read/Write transactions

googleapis/google-cloud-go@5709d56

上の修正に対応する R/W tx 側の修正

[apstndb]

〜 spanner/v1.2.0

https://github.com/googleapis/google-cloud-go/releases/tag/spanner%2Fv1.2.0

Support tracking stacktrace of sessionPool.take() that allows the user
to instruct the session pool to keep track of the stacktrace of each
goroutine that checks out a session from the pool. This is disabled by
default, but it can be enabled by setting
SessionPoolConfig.TrackSessionHandles: true.

googleapis/google-cloud-go@06cb606

SessionPoolConfig.TrackSessionHandles: true した時にセッションプールからセッションを取得時の goroutine のスタックトレースを記録するようにした。スタックトレースはセッションタイムアウト時などに表示される。

Add resource-based routing that includes a step to retrieve the
instance-specific endpoint before creating the session client when
creating a new spanner client. This is disabled by default, but it can
be enabled by setting GOOGLE_CLOUD_SPANNER_ENABLE_RESOURCE_BASED_ROUTING.

googleapis/google-cloud-go@896180c

有効にした場合に Admin API の GetInstance で最適なエンドポイント情報を取得してグローバルな spanner.googleapis.com のかわりに使う事が可能。レイテンシ低下の狙いがあるらしい。 v1.4.0 時点でまだデフォルトで有効にはなっていない。

Support encoding custom types that point back to supported basic types.

googleapis/google-cloud-go@25b2b69

type CustomType BasicType した型のエンコードにも対応した。

spanner: Allow decoding Spanner values to custom types.

googleapis/google-cloud-go@39a127f

上のデコード側の実装

Allow decoding Spanner values to custom types that point back to supported
types.

googleapis/google-cloud-go@fbe1038

対応している型のポインタを nil 含めて正しく扱えるようになった。例えば spanner.NullString 型ではなく単に *string を使えるようになった。

make ReadWriteTransaction retry on Session not found error

googleapis/google-cloud-go@4c1e347

r/w tx は runInTransaction の中なので abort だけでなく session not found でも別のセッションで安全にリトライできる。リトライディレイを入れる abort と違って即時リトライする。

retry SessionNotFound on BeginTransaction for read-only tx

googleapis/google-cloud-go@4a4cd86

read only transaction は session not found が出た時に冪等性の問題なく別のセッションを使って安全にリトライできる。
よって、最初の result set をクライアントが処理するまでは暗黙のうちにリトライするようにした。

retry single use transactions on SessionNotFound

googleapis/google-cloud-go@7a18dc1

single use も同様に冪等性の問題なく別のセッションを使って安全にリトライできる。
よって、最初の result set をクライアントが処理するまでは暗黙のうちにリトライするようにした。

ReadOnlyTransaction().ReadRowUsingIndex

googleapis/google-cloud-go@4f99193

インデックスから厳密に1 row 取得する関数。0行もしくは複数行取得された場合はそれぞれ区別可能なエラーになる。

session client should return Spanner errors

googleapis/google-cloud-go@f858c6c

context や gRPC 由来のエラーが出た時に spanner パッケージのエラーになっていなかったのを修正。

fix automatic retry of aborted dml

googleapis/google-cloud-go@06a25b0

(context や gRPC など)Spanner ではないレイヤでエラーが出ていた時に DML がリトライされなかったのを修正

spanner: increase the timeout in session preparation

googleapis/google-cloud-go@6be7f45

ヘルスチェック時のタイムアウトを1秒から1分に変更。特に対応可能なことがないのにログが表示されすぎるためとのこと。

spanner: Use Go 1.13 error-unwrapping

googleapis/google-cloud-go@9f47821

Go 1.13 と xerrors のインターフェース(Unwrap)に対応

spanner: Stop prepare sessions on error

googleapis/google-cloud-go@4fba433

write session を裏で BeginTransaction しておく仕組みがあるが、エラー時には無限ループを避けるためにその動作を止めるようになった。

all: auto-regenerate gapics

googleapis/google-cloud-go@003d19f

コードジェネレータが gapic-generator から protoc-gen-go_gapic に変わって色々変わっている

spanner: quieten permission denied errors during session preparation

googleapis/google-cloud-go@cb4fdf1

session preparation での permission denied は無視できる。何故？

spanner: Make logger configurable

googleapis/google-cloud-go@187d661

ロガーを設定可能に。主にテスト時に起こることが分かっているエラーログを黙らせるために使われているっぽい。

spanner: take sessions in LIFO order

googleapis/google-cloud-go@25d2e81

セッションプールからの取得を LIFO に。これまではラウンドロビン

spanner: Handle permanent errors on prepare session

googleapis/google-cloud-go@0fd5feb

PermissionDenied や Database not found のようなリトライで復帰不可能なエラーではセッション獲得のリトライをしない。

[apstndb]

〜 spanner/v1.2.1

https://github.com/googleapis/google-cloud-go/releases/tag/spanner%2Fv1.2.1

Fix session leakage for ApplyAtLeastOnce. Previously session handles where
leaked whenever Commit() returned a non-abort, non-session-not-found error,
due to a missing recycle() call.

googleapis/google-cloud-go@2875e82

applyAtLeastOnce で apply した時、 abort のときはセッションを破棄、正常終了の場合はセッションをプールに戻していたが、それ以外のエラーの時にセッションリークしていたのを修正した

Fix error for WriteStruct with pointers. This fixes a specific check for
encoding and decoding to pointer types.

googleapis/google-cloud-go@8424551

WriteStruct でポインタにも対応したが、プリミティブな型にポインタが付いている時のチェックが抜けていたので修正したらしい

Fix a GRPCStatus issue that returns a Status that has Unknown code if the
base error is nil. Now, it always returns a Status based on Code field of
current error.

googleapis/google-cloud-go@ac2a25f

spanner.Error.GRPCStatus() が今まで codes.Unknown 持つ status.Status を返していた場合があったが、 e.Code を返すようになった。

[apstndb]

〜 spanner/v1.3.0

https://github.com/googleapis/google-cloud-go/releases/tag/spanner%2Fv1.3.0

spanner: support query options
Query options:

googleapis/google-cloud-go@7b40e56

クエリオプション及び環境変数からの optimizer version の設定方法の提供。

Connection pooling:

googleapis/google-cloud-go@b63d8a6

Cloud Spanner クライアントライブラリではなく grpc-go のコネクションプールを使う。

• ClientConfig.NumChannels から option.WithGRPCConnectionPool(numConns) への移行。
• gRPC connection pool の一括開始、一括終了
• 以前はセッションクライアントのプールからラウンドロビンしていたけど、 gRPC コネクションプールから毎回セッションクライアントを作っている？

Do not rollback after failed commit.

googleapis/google-cloud-go@b63d8a6

RunInTransaction でエラーが出た時にはロールバックしていたが、コミットを呼ぶ時のエラーはロールバックしない。
https://cloud.google.com/spanner/docs/reference/rpc/google.spanner.v1#google.spanner.v1.Spanner.Commit
コミットのエラー時には基本的に自動的にロールバックされてリトライするのは安全だから？

Return TransactionOutcomeUnknownError if a DEADLINE_EXCEEDED or CANCELED
error occurs while a COMMIT request is in flight.

googleapis/google-cloud-go@2159af9

コミットリクエスト中に context 経由でのキャンセルやデッドラインが発動した場合は実際にはコミットが成功している場合もあるからエラーを区別できるようにした。この場合にはコミットの成否は不明なのでアプリケーション側で対応した方が良いとのこと。

Misc

spanner: change healthcheck interval to 30 mins
Change default healthcheck interval to 30 mins to reduce the GetSession
calls made to the backend.

googleapis/google-cloud-go@565ae89

ヘルスチェックを5分から30分間隔にして GetSession が呼ばれる頻度を下げた

Add marshal/unmarshal json for nullable types to support NullString,
NullInt64, NullFloat64, NullBool, NullTime, NullDate.

googleapis/google-cloud-go@0109565

spanner.Null* 型を正しく json.Marshal / json.Unmarshal できるようにした。

spanner: use ResourceInfo to extract error
Use ResourceInfo to extract error.

googleapis/google-cloud-go@863a84d

err.Error() の文字列処理ではなく errdetails.ResourceInfo からエラーの詳細を取得するようにすることでエラーハンドリングを改善したっぽい？

spanner: extract retry info from status
Extract retry info from status.

googleapis/google-cloud-go@8d3876f

retry info を HTTP2/gRPC trailer ではなく status から取り出すようにしたことで trailer を処理する必要性をなくした

[apstndb]

〜 spanner/v1.4.0

https://github.com/googleapis/google-cloud-go/releases/tag/spanner%2Fv1.4.0

e3374f3f5e1521b394a966253af920e462a4fdfa
Support managed backups. This includes the API methods for CreateBackup,
GetBackup, UpdateBackup, DeleteBackup and others. Also includes a simple
wrapper in DatabaseAdminClient to create a backup.

googleapis/google-cloud-go@e3374f3

未リリースのはずのマネージドバックアップ対応。

spanner: update the health check interval
Update the healthcheck interval. The default interval is updated to 50 mins.
By default, the first healthcheck is scheduled between 10 and 55 mins and
the subsequent healthchecks are between 45 and 55 mins. This update avoids
overloading the backend service with frequent healthchecking.

googleapis/google-cloud-go@62bc962

ヘルスチェックのための GetSession の呼び出しを30分間隔から50分間隔に調整。初回の幅を広げているのはヘルスチェックの間隔が揃うのを避けるためだと考えられる。

[apstndb]

〜 spanner/v1.5.0

https://github.com/googleapis/google-cloud-go/releases/tag/spanner%2Fv1.5.0

Metrics
Instrument client library with adding OpenCensus metrics. This allows for
better monitoring of the session pool.
googleapis/google-cloud-go@bd24341#diff-69f1cc5a16638c0dfbc583c9b5798297
googleapis/google-cloud-go@5b53923#diff-69f1cc5a16638c0dfbc583c9b5798297

これは下記記事の内容に相当する機能追加。

https://medium.com/@mayurkale22/troubleshooting-cloud-spanner-applications-with-opencensus-2cf424c4c590

なお上記記事からの変更として、 in_use_sessions は Type ラベルを持つ num_sessions_in_pool に変更されている。これは下記の issue の変更に追従するもの。

googleapis/java-spanner#53

Type : num_in_use_sessions | num_sessions_being_prepared | num_read_sessions | num_write_prepared_sessions

Session management
Switch the session keepalive method from GetSession to SELECT 1.
spanner: switch the session keepalive method from GetSession to SELECT 1

googleapis/google-cloud-go@f2776fc#diff-69f1cc5a16638c0dfbc583c9b5798297

Session Maintainer からのヘルスチェックで呼ばれる ping の実装を GetSession から single の SELECT 1 の発行に変更している。
どうやら java-spanner は repo 分割前の最初からそうだったっぽい。おそらく GetSession だとセッションの生存確認はできるけど keepalive には役に立たず、ヘルスチェックの周期を長くしたタイミングでセッションが維持しやすいように変更したのではないか。

追記

https://cloud.google.com/spanner/docs/sessions?hl=en#keep_an_idle_session_alive

Perform an inexpensive operation such as executing the SQL query SELECT 1 to keep the session alive.

とあるので推奨される方法に修正されたという認識でよさそう。
ドキュメントされている仕様として一時間以上使われていなかったセッションがサーバー側で閉じられるので、50分間隔で keepalive されるようになった結果 Session not found はほぼ発生しなくなることが期待できる。

Emulator
Use client hooks for admin clients running against an emulator. With
this change, users can use SPANNER_EMULATOR_HOST for initializing admin
clients when running against an emulator.
spanner: use client hooks for admin clients running against an emulator
1ac32cb883f8ec66a57bec3f2285e7b4b964102d

• 従来は Admin Client は自動生成されたクライアントライブラリなので SPANNER_EMULATOR_HOST を見て接続先を変えるロジックを入れていなかった(参照)が、クライアントフックで設定を注入して admin client も Cloud Spanner Emulator に接続できるようになった。
• テスト用のサービスアカウントとエンドポイントを指定するために専用の環境変数を使っていたのを廃止
• また、データクライアントも含めて SPANNER_EMULATOR_HOST よりもクライアントオプションによる設定を優先するようになった。

Misc
Fix segfault when a non-existent credentials file had been specified.
spanner: fix segfault when missing credentials

googleapis/google-cloud-go@90c5e7c

gtransport.DialPool でエラーチェックをしていなくて credential がない時などに panic していたのを直したとのこと。

Fix race condition in batch read-only transaction.
spanner: fix race condition in batch read-only tx

googleapis/google-cloud-go@b0b68af

BatchReadOnlyTransaction のインスタンスがトランザクションの別のパーティションで再利用されて競合が起こり、結果が不正になることがあったのを修正した。

Fix the documentation of timestamp bounds.
spanner: fix timestamp bounds docs

googleapis/google-cloud-go@d0a3172

timestamp bounds read の read timestamp が一定時間以上古いと読み込み時エラーが出る仕様があるが、場所によって1時間と4時間の2つの記述に分かれていた。4時間は間違いであり、1時間が正しいため修正された。

Fix the regex issue in managing backups.
spanner: fix the regex issue in manging backups.

googleapis/google-cloud-go@ccd63b7

パスの中のコンポーネントを正規表現で抽出するロジックのバグの修正

[apstndb]

spanner/v1.5.1

Fix incorrect decreasing metrics, numReads and numWrites.
spanner: fix incorrect decreasing metrics
googleapis/google-cloud-go@6c924e2

v1.5.0 で実装されたメトリクスが 10分の health recycling period ごとの処理でセッションプールを縮小する判断が行われた時に正しくデクリメントされなかったのを修正した。

Fix an issue that XXX fields/methods are internal to proto and may change at any time. XXX_Merge panics in proto v1.4.0. Use proto.Merge instead of XXX_Merge.
spanner: use proto.Merge instead of XXX_Merge
googleapis/google-cloud-go@f3f771e

protobuf v1.4.0 対応のため、 XXX_Merge ではなく proto.Merge を使う。

[apstndb]

spanner/v1.6.0

Sessions:
Increase the number of sessions in batches instead of one by one when additional sessions are needed. The step size is set to 25, which means that whenever the session pool needs at least one more session, it will create a batch of 25 sessions.
spanner: increase sessions in batches

googleapis/google-cloud-go@5389830

従来はセッションプールを拡張する時には足りないセッションの数だけ CreateSession RPC を呼んで作成していたが、 BatchCreateSessions RPC で一括作成するようになった。
足りない数が少なくても最低25セッション作成することで小さすぎるステップで拡張を繰り返すことを避けている。

なおセッションの要求と確保は別の goroutine で行われ、新しいセッションの作成が完了した時以外にも他の goroutine がセッションを返却した時にもセッションを要求する goroutine に処理が戻る終わるため、必ずしも BatchCreateSessions RPC の時間待つ必要はないとのこと。
1.5.1 まではセッションが足りなかった際は必ず CreateSession でブロックしていたので、セッションの確保そのものによるレイテンシの悪化は減ると考えられる。

RPC retrying:
Retry CreateDatabase on retryable codes.
spanner: retry CreateDatabase on retryable codes
googleapis/google-cloud-go@5cf1a92

CreateDatabase がリトライ可能なエラーコードのときにリトライされるようになった。

Clearify docs on Aborted transaction.
spanner: clearify docs on Aborted tx

googleapis/google-cloud-go@eee5386

gRPC 的に abort の時にリトライされること、デッドロック時にも abort されることなどが明記された。

Fix timeout+staleness bound for test

Remove the support for resource-based routing.
spanner: remove the support for resource-based routing
googleapis/google-cloud-go@e103684

マージされていたクライアント側での resource-based routing は導入しないことになったので削除している。

[apstndb]

spanner/v1.7.0

Retry:
Only retry certain types of internal errors. (googleapis/google-cloud-go#2460)

googleapis/google-cloud-go@9f9e9d2

リトライ可能な internal error を限定した。通信関係の偶発的エラーを明示している様子。

Tracing/metrics:
Never sample ping() trace spans (googleapis/google-cloud-go#2520)

googleapis/google-cloud-go@a014b9d

ping の span は OpenCensus のサンプリング対象とならなくなった。

Add oc tests for session pool metrics. (googleapis/google-cloud-go#2416)
Encoding:

Allow encoding struct with custom types to mutation (googleapis/google-cloud-go#2529)

googleapis/google-cloud-go@f47eab4

custom base type サポートを mutation で使えるようにした。これまでの対応はパラメータやクエリ結果のみだったということの様子。

Misc:
Cleanup backoff files and rename a variable (googleapis/google-cloud-go#2526)

googleapis/google-cloud-go@2b852b6

GAX を使うようになったことで不要になっていた backoff の実装を削除したり変数名を変更するなどの整理。

[apstndb]

spanner/v1.8.0

Features:
feat(spanner): support of client-level custom retry settings (googleapis/google-cloud-go#2599)

クライアント共通のデフォルトのリトライ設定を ClientConfig.CallOptions から上書きできるようにした。

feat(spanner): add a statement-based way to run read-write transaction. (googleapis/google-cloud-go#2545)
124b5702eff3ac831ddcea3c7771f43111d8dd26

コールバックとしてトランザクション内の処理を受け取って自動的にトランザクションのリトライやコミットが行われる ReadWriteTransaction とは別に、プログラムから明示的にトランザクションを扱うための spanner.ReadWriteStmtBasedTransaction を追加した。

Bugfixes:
fix(spanner): set 'gccl' to the request header. (googleapis/google-cloud-go#2609)

gccl ヘッダで google-cloud-go のバージョンを渡すようにした。

fix(spanner): do not copy protobuf messages by value. (googleapis/google-cloud-go#2581)

ReadRequest などの構造体を丸ごとコピーしているコードがあったが、 unexported な protoimpl.MessageState に含まれる mutex のコピーは好ましくないため、フィールドを個別にコピーするようにした。

fix(spanner): add the missing resource prefix (googleapis/google-cloud-go#2605)
fix(spanner): fix the required resource prefix. (googleapis/google-cloud-go#2580)

resource prefix ヘッダが正しく渡るように修正している。どうやら resource based routing が裏で行われるようにするためのヒントとして機能するようだ。See also: googleapis/google-cloud-dotnet#5255

fix(spanner): remove appengine-specific numChannels. (googleapis/google-cloud-go#2513)

App Engine Go 1.9 以前を考慮する必要がなくなったため、 appengine ビルドタグを使った分岐を削除した。

[apstndb]

spanner/v1.9.0

Features:
feat(spanner): support custom field type (googleapis/google-cloud-go#2614)

EncodeSpanner() (interface{}, error) を持つ Encoder インターフェースや DecodeSpanner(input interface{}) error を持つ Decoder インターフェースを実装することで、ユーザ定義型を Cloud Spanner ネイティブな型の値と暗黙に変換できるようになった。 (*Row).ToStruct や各 Mutation の value, クエリパラメータとして使用可能。

Bugfixes:
fix(spanner): call ctx.cancel after stats have been recorded (googleapis/google-cloud-go#2728)

context.WithTimeout が返す cancel が呼ばれた後に stats の更新のために ctx を使っている箇所があった。googleapis/google-cloud-go#2660 を見る限りだと具体的に問題が起こることが確認されたわけではないが、不自然なコードとして修正された様子。

fix(spanner): retry session not found for read (googleapis/google-cloud-go#2724)

single-use read-only transaction 使おうとしたセッションが何らかの理由で既に無効になっていたことにより session not found エラーが派生した時に今まではアプリケーションコードにエラーを返していたが、安全にリトライ可能なのでクライアント内で別のセッションを使って暗黙にリトライするようになった。

fix(spanner): specify credentials with SPANNER_EMULATOR_HOST (googleapis/google-cloud-go#2701)

今まで SPANNER_EMULATOR_HOST を指定した際には WithCredentialsFile を使うとエラーになっていたが、そのチェックを外した。

fix(spanner): update pdml to retry EOS internal error (googleapis/google-cloud-go#2678)

Partitioned DML についても安全にリトライできる Internal なエラーコードはリトライするようになった。

[apstndb]

spanner/v1.10.0

feat(spanner): add support for NUMERIC data type (googleapis/google-cloud-go#2415)

BigQuery/ZetaSQL では実装済だが
Cloud Spanner ではまだ正式にはリリースされていない固定小数点数型の NUMERIC のクライアントライブラリ側の実装。

feat(spanner): add custom type support to spanner.Key (googleapis/google-cloud-go#2748)

googleapis/google-cloud-go#854, googleapis/google-cloud-go#2614 で組み込み型を underlying type として持つ型や EncodeSpanner() (interface{}, error) メソッドを実装した型を mutation 等でサポートしているが、 spanner.Key として使えなかったのを修正した。

fix(spanner): update PDML to take sessions from pool (googleapis/google-cloud-go#2736)

Partitioned DML で常に CreateSession を呼んでいたが、セッションプールを使うように修正した。

[apstndb]

spanner/v1.11.0

• Features:

• feat(spanner): add KeySetFromKeys function (feat(spanner): add KeySetFromKeys function googleapis/google-cloud-go#2837)

func KeySetFromKeys(keys ...spanner.Key) spanner.KeySet が追加され、 Read や Delete 等の非 SQL な低レベル API でユニークなキーで複数行を対象とする処理が書きやすくなった。

• Misc:

• docs(spanner): document NULL value (docs(spanner): document NULL value googleapis/google-cloud-go#2885)

spanner.Null* 型が Valid=false の時にどのような値を持つかがドキュメンテーションされた。

[apstndb]

spanner/v1.12.0

Features
spanner: add metadata to RowIterator (googleapis/google-cloud-go#3050) (googleapis/google-cloud-go@9a2289c), closes googleapis/google-cloud-go#1805

RowIterator から ResultSetMetadata を取得できるようになった。今までは *spanner.Row から spanner.GenericColumnValue を経由してクエリ結果の型を確認していたが、結果が0行なクエリや QueryMode=PLAN でも直接結果の列名や型を取得できるようになったため、汎用的なツールを作るのに役立つ。

spanner: export ToSpannerError (googleapis/google-cloud-go#3133) (googleapis/google-cloud-go@b951d8b), closes googleapis/google-cloud-go#3122

任意の error を *spanner.Error に変換する func ToSpannerError(err error) error が export されたため、エラーハンドリングをテストしやすくなった。

spanner: support rw-transaction with options (googleapis/google-cloud-go#3058) (googleapis/google-cloud-go@5130694)

TransactionOptions を受ける (*Client).ReadWriteTransactionWithOptions と (*Client).NewReadWriteStmtBasedTransactionWithOptionsが追加された他、内部的に commit timestamp 以外にも情報がある CommitResponse をコミットが返すことを想定したコードになった。
googleapis/google-cloud-go#3056 の commit stats をサポートする下準備なので、単体では特に変わらない。

spanner(fix): do not end span with iterator.Done (googleapis/google-cloud-go#3128)

クライアントライブラリが OpenCensus に出力している span に iterator.Done がエラーとして記録されるバグがあったため、修正している。

[apstndb]

https://github.com/googleapis/google-cloud-go/releases/tag/spanner%2Fv1.13.0

Features
spanner: Add a DirectPath fallback integration test (https://www.github.com/googleapis/google-cloud-go/issues/3487) (de821c5)
spanner: attempt DirectPath by default (https://www.github.com/googleapis/google-cloud-go/issues/3516) (bbc61ed)
spanner: include User agent (https://www.github.com/googleapis/google-cloud-go/issues/3465) (4e1ef1b)
spanner: run E2E test over DirectPath (https://www.github.com/googleapis/google-cloud-go/issues/3466) (18e3a4f)

DirectPath は GFE を迂回して Google 内から API を叩くための経路であると考えられ、それをクライアントライブラリから使えるようにする修正。
まだ通常のユーザには開放されていない。

spanner: support NUMERIC in mutations (https://www.github.com/googleapis/google-cloud-go/issues/3328) (fa90737)

NUMERIC 型の列に mutation で値を設定することができなかったのを修正している。

Bug Fixes
spanner: fix session leak (https://www.github.com/googleapis/google-cloud-go/issues/3461) (11fb917), refs https://www.github.com/googleapis/google-cloud-go/issues/3460
Read-Write transaction の中で panic が起こった際にセッションリークが起こっていたのを修正している。

[apstndb]

https://github.com/googleapis/google-cloud-go/releases/tag/spanner%2Fv1.14.0

• spanner: add option for returning Spanner commit stats (c7ecf0f)
• spanner: add option for returning Spanner commit stats (7bdebad)
• spanner: support CommitStats (#3444) (b7c3ca6)

従来は Commit の結果として Commit Timestamp のみを得ていたが、 MutationCount を含む CommitStats を得ることができるようになった。
CommitStats を得るには ReadWriteTransactionWithOptions(または NewReadWriteStmtBasedTransactionWithOptions) を使って ReturnCommitStats: true を渡す必要がある。

feat: support NUMERIC as key (https://www.github.com/googleapis/google-cloud-go/issues/3627)

Data types にあるように NUMERIC はキーとしては使えないが、対応する布石の可能性がある。

https://github.com/googleapis/google-cloud-go/releases/tag/spanner%2Fv1.14.1

spanner: restore removed scopes (#3684) (232d3a1)

Scope 関係の定数が削除されて破壊的変更になっていたのが修正された。

[apstndb]

https://github.com/googleapis/google-cloud-go/releases/tag/spanner%2Fv1.15.0

Features
spanner/admin/database: add CMEK fields to backup and database (47037ed)
spanner/admin/database: add CMEK fields to backup and database (16597fa)

backup の CMEK 対応

Bug Fixes
spanner: parallelize session deletion when closing pool (#3701) (75ac7d2), refs #3701

DeleteSession は1セッションにつき1 RPC 呼ぶ必要があり、今までは直列に呼んでいたのが並列化された。

[apstndb]

https://github.com/googleapis/google-cloud-go/releases/tag/spanner/v1.16.0

Features

• spanner: add optimizer_statistics_package field in QueryOptions (18c88c4)

未リリースの optimizer statistics package に関するフィールドが proto に追加されたため反映している。

[apstndb]

https://github.com/googleapis/google-cloud-go/releases/tag/spanner/v1.17.0

Features

• spanner/admin/database: add tagging request options (2b02a03)

request に tag を付ける未リリース機能のためのフィールドが proto に追加されたため反映している。

• spanner: add RPC Priority request options (b5b4da6)
• spanner: Add support for RPC priority (#3341) (88cf097)

RPC ごとに priority を指定するためのオプションに対応した。

• https://cloud.google.com/blog/topics/developers-practitioners/introducing-request-priorities-cloud-spanner-apis
• https://cloud.google.com/spanner/docs/reference/rest/v1/RequestOptions?hl=en#Priority

docs(spanner): fix the result handling after BufferWrite (#3803)

context がキャンセル済などでないと通常は発生しない txn.BufferWrite() のエラーが無視されていたのを修正している。

[apstndb]

https://github.com/googleapis/google-cloud-go/releases/tag/spanner/v1.18.0

Features

• spanner/admin/database: add progress field to UpdateDatabaseDdlMetadata (9029071)

DDL の進捗を取得するための progress フィールドが proto に追加されたので対応している。

• https://cloud.google.com/spanner/docs/secondary-indexes?hl=en#index-progress

リリースノート記載なし

feat(spanner): support request and transaction tags (#3233)
revert(spanner): support request and transaction tags (#3233) (#3989)

request/transaction へのタグの指定に対応したが、 v1.18.0 のリリースまでに正式にリリースされなかったため revert されている。

feat(spanner): enable request options for batch read (#3905)
revert(spanner): Revert enable request options for batch read (#3905)" (#3987)

PartitionRead に RPC を指定できるオプションの追加が revert されている。上の revert と conflict しているのが理由とのこと。

[apstndb]

https://github.com/googleapis/google-cloud-go/releases/tag/spanner/v1.19.0

Features

• spanner: add a database name getter to client (#4190) (7fce29a)

(*spanner.Client).DatabaseName() から今クライアントが接続しているデータベースのリソース名(projects/{project}/instances/{instance}/databases/{database})を取得できるようになった。

• spanner: add custom instance config to tests (#4194) (e935345)

テストコードのみの修正。

Bug Fixes

• spanner: add missing NUMERIC type to the doc for Row (#4116) (9a3b416)

godoc 上の Cloud Spanner の型と Go の型の対応関係 から NUMERIC 型が漏れていたのを修正している。

• spanner: indent code example for Encoder and Decoder (#4128) (7c1f48f)

文字通りインデントの修正のみを行っている。

• spanner: mark SessionPoolConfig.MaxBurst deprecated (#4115) (d60a686)

SessionPoolConfig.MaxBurst が v1.6.0 から一切使われなくなっていたので、コメントに deprecated であることが明記された。

リリースノート記載なし

docs(spanner): fix godoc for default value of health check interval (#4136)

SessionPoolConfig.HealthCheckInterval のデフォルト値が v1.1.0 から変わっていたのが godoc に反映されていなかったので修正されている。
なお、この値は通常設定する必要はない。

[apstndb]

https://github.com/googleapis/google-cloud-go/releases/tag/spanner%2Fv1.20.0

Features
spanner: add the support of optimizer statistics package (#2717)

Query optimizer statistics packages のクライアントライブラリ側の対応を実装している。

[apstndb]

v1.21.0

https://github.com/googleapis/google-cloud-go/releases/tag/spanner%2Fv1.21.0

Miscellaneous Chores
spanner: trigger a release for low cost instance (#4264)

Processing Unit 単位でインスタンスのコンピュートキャパシティを指定できるように更新された proto を取り込んでリリースしている。
"low cost instance" とは Granular instance sizing としてリリースされたものの別名。

[apstndb]

v1.22.0

Features
spanner: support request and transaction tags (#4336) (f08c73a)

Request Tag と Transaction Tagを TransactionOptions で指定できるようになった。

spanner: enable request options for batch read (#4337) (b9081c3)

PartitionRead* には ReadOptions が渡せる WithOptions の接尾辞が付いたバリエーションがなかったが、追加された。

[apstndb]

1.23.0 (2021-07-08)

Features

spanner/admin/database: add leader_options to InstanceConfig and default_leader to Database (7aa0e19)

マルチリージョンインスタンスでデフォルトとは異なる方の RW レプリカをデフォルトのリーダーレプリカにすることができる default_leader を指定できるようになっている。

[apstndb]

v1.24.0

Features

spanner: add row.String() and refine error message for decoding a struct array (#4431) (f6258a4)

Row.String() の実装により、行や STRUCT 全体を print して確認しやすくなった。また、 ARRAY<STRUCT> 型の列をデコードしようとした時に発生したエラーがわかりやすくなった。

spanner: allow untyped nil values in parameterized queries (#4482) (c1ba18b)

これまでは parameterized query に NULL を渡したい時には Statement.Params に NULL 扱いされる型のある値(例えば *string(nil) や NullString{Valid: False})を渡す必要があったが、 nil をそのまま渡せるようになった。

[apstndb]

v1.24.1

Bug Fixes

spanner: allow decoding null values to spanner.Decoder (#4558) (45ddaca), refs #4552

spanner.Decoder interface を実装した struct はデコード時の挙動をカスタマイズできるが、そこに NULL が渡ってきた際にはこれまでエラーになっていた。
この修正により、エラーではなく nil が DecodeSpanner() メソッドに渡ってくるようになった。

[apstndb]

v1.25.0

Features

spanner: add support for JSON data type (#4104) (ade8ab1)
Bug Fixes

JSON 型に対応している。クライアントライブラリ側では NullJSON 型 をエンコード及びデコードに使用する。

spanner: invalid numeric should throw an error (#3926) (cde8697)

NUMERIC 型で表現できない *big.Rat 型の値を渡した場合に丸めるかエラーとするかを LossOfPrecisionHandlingOption(NumericRound or NumericError) として渡せるようになった。