Add support for Directed reads (#163)

* Add option for Directed Read

* Add test and README for Directed reads

* Explicitly set query-level directed read options for read-write transactions.

* Bump up Go version to 1.19

Author: takabow

.github/workflows/run-tests.yaml

@@ -33,7 +33,7 @@ jobs:
       - uses: actions/checkout@v2
       - uses: actions/setup-go@v2
         with:
-          go-version: '1.18'
+          go-version: '1.19'
       - run: go version
       - run: make setup-emulator
         env:

README.md

@@ -31,18 +31,20 @@ Usage:
   spanner-cli [OPTIONS]
 
 spanner:
-  -p, --project=    (required) GCP Project ID. [$SPANNER_PROJECT_ID]
-  -i, --instance=   (required) Cloud Spanner Instance ID [$SPANNER_INSTANCE_ID]
-  -d, --database=   (required) Cloud Spanner Database ID. [$SPANNER_DATABASE_ID]
-  -e, --execute=    Execute SQL statement and quit.
-  -f, --file=       Execute SQL statement from file and quit.
-  -t, --table       Display output in table format for batch mode.
-  -v, --verbose     Display verbose output.
-      --credential= Use the specific credential file
-      --prompt=     Set the prompt to the specified format
-      --history=    Set the history file to the specified path
-      --priority=   Set default request priority (HIGH|MEDIUM|LOW)
-      --role=       Use the specific database role
+  -p, --project=       (required) GCP Project ID. [$SPANNER_PROJECT_ID]
+  -i, --instance=      (required) Cloud Spanner Instance ID [$SPANNER_INSTANCE_ID]
+  -d, --database=      (required) Cloud Spanner Database ID. [$SPANNER_DATABASE_ID]
+  -e, --execute=       Execute SQL statement and quit.
+  -f, --file=          Execute SQL statement from file and quit.
+  -t, --table          Display output in table format for batch mode.
+  -v, --verbose        Display verbose output.
+      --credential=    Use the specific credential file
+      --prompt=        Set the prompt to the specified format
+      --history=       Set the history file to the specified path
+      --priority=      Set default request priority (HIGH|MEDIUM|LOW)
+      --role=          Use the specific database role
+      --directed-read= Directed read option (replica_location:replica_type).
+                       The replicat_type is optional and either READ_ONLY or READ_WRITE.
 
 Help Options:
   -h, --help        Show this help message
@@ -144,6 +146,38 @@ $ spanner-cli -p myproject -i myinstance -d mydb -e 'SELECT * FROM users;' -t
 +----+------+--------+
 ```
 
+### Directed reads mode
+
+spanner-cli now supports directed reads, a feature that allows you to read data from a specific replica of a Spanner database. 
+To use directed reads with spanner-cli, you need to specify the `--directed-read` flag.
+The `--directed-read` flag takes a single argument, which is the name of the replica that you want to read from.
+The replica name can be specified in one of the following formats:
+
+- `<replica_location>`
+- `<replica_location>:<replica_type>`
+
+The `<replica_location>` specifies the region where the replica is located such as `us-central1`, `asia-northeast2`.  
+The `<replica_type>` specifies the type of the replica either `READ_WRITE` or `READ_ONLY`. 
+ 
+```
+$ spanner-cli -p myproject -i myinstance -d mydb --directed-read us-central1
+
+$ spanner-cli -p myproject -i myinstance -d mydb --directed-read us-central1:READ_ONLY
+
+$ spanner-cli -p myproject -i myinstance -d mydb --directed-read asia-northeast2:READ_WRITE
+```
+
+Directed reads are only effective for single queries or queries within a read-only transaction.
+Please note that directed read options do not apply to queries within a read-write transaction.
+
+> [!NOTE]
+> If you specify an incorrect region or type for directed reads, directed reads will not be enabled and [your requsts won't be routed as expected](https://cloud.google.com/spanner/docs/directed-reads#parameters). For example, in a multi-region configuration `nam3`, if you mistype `us-east1` as `us-east-1`, the connection will succeed, but directed reads will not be enabled. 
+>
+> To perform directed reads to `asia-northeast2` in a multi-region configuration `asia1`, you need to specify `asia-northeast2` or `asia-northeast2:READ_WRITE`.
+> Since the replicas placed in `asia-northeast2` are READ_WRITE replicas, directed reads will not be enabled if you specify `asia-northeast2:READ_ONLY`.
+> 
+> Please refer to [the Spanner documentation](https://cloud.google.com/spanner/docs/instance-configurations#available-configurations-multi-region) to verify the valid configurations.
+
 ## Syntax
 
 In the following syntax, we use `<>` for a placeholder, `[]` for an optional keyword,

cli.go

@@ -75,8 +75,8 @@ type command struct {
 	Vertical bool
 }
 
-func NewCli(projectId, instanceId, databaseId, prompt, historyFile string, credential []byte, inStream io.ReadCloser, outStream io.Writer, errStream io.Writer, verbose bool, priority pb.RequestOptions_Priority, role string, endpoint string) (*Cli, error) {
-	session, err := createSession(projectId, instanceId, databaseId, credential, priority, role, endpoint)
+func NewCli(projectId, instanceId, databaseId, prompt, historyFile string, credential []byte, inStream io.ReadCloser, outStream io.Writer, errStream io.Writer, verbose bool, priority pb.RequestOptions_Priority, role string, endpoint string, directedRead *pb.DirectedReadOptions) (*Cli, error) {
+	session, err := createSession(projectId, instanceId, databaseId, credential, priority, role, endpoint, directedRead)
 	if err != nil {
 		return nil, err
 	}
@@ -148,7 +148,7 @@ func (c *Cli) RunInteractive() int {
 		}
 
 		if s, ok := stmt.(*UseStatement); ok {
-			newSession, err := createSession(c.Session.projectId, c.Session.instanceId, s.Database, c.Credential, c.Priority, s.Role, c.Endpoint)
+			newSession, err := createSession(c.Session.projectId, c.Session.instanceId, s.Database, c.Credential, c.Priority, s.Role, c.Endpoint, c.Session.directedRead)
 			if err != nil {
 				c.PrintInteractiveError(err)
 				continue
@@ -310,15 +310,15 @@ func (c *Cli) getInterpolatedPrompt() string {
 	return prompt
 }
 
-func createSession(projectId string, instanceId string, databaseId string, credential []byte, priority pb.RequestOptions_Priority, role string, endpoint string) (*Session, error) {
+func createSession(projectId string, instanceId string, databaseId string, credential []byte, priority pb.RequestOptions_Priority, role string, endpoint string, directedRead *pb.DirectedReadOptions) (*Session, error) {
 	var opts []option.ClientOption
 	if credential != nil {
 		opts = append(opts, option.WithCredentialsJSON(credential))
 	}
 	if endpoint != "" {
 		opts = append(opts, option.WithEndpoint(endpoint))
 	}
-	return NewSession(projectId, instanceId, databaseId, priority, role, opts...)
+	return NewSession(projectId, instanceId, databaseId, priority, role, directedRead, opts...)
 }
 
 func readInteractiveInput(rl *readline.Instance, prompt string) (*inputStatement, error) {

go.mod

@@ -1,46 +1,63 @@
 module github.com/cloudspannerecosystem/spanner-cli
 
-go 1.18
+go 1.19
 
 require (
-	cloud.google.com/go v0.110.0
-	cloud.google.com/go/spanner v1.44.0
+	cloud.google.com/go v0.111.0
+	cloud.google.com/go/spanner v1.55.0
 	github.com/apstndb/gsqlsep v0.0.0-20230324124551-0e8335710080
 	github.com/chzyer/readline v0.0.0-20180603132655-2972be24d48e
-	github.com/google/go-cmp v0.5.9
+	github.com/google/go-cmp v0.6.0
 	github.com/jessevdk/go-flags v1.4.0
 	github.com/olekukonko/tablewriter v0.0.4
 	github.com/xlab/treeprint v1.0.1-0.20200715141336-10e0bc383e01
-	google.golang.org/api v0.111.0
-	google.golang.org/genproto v0.0.0-20230303212802-e74f57abe488
-	google.golang.org/grpc v1.53.0
-	google.golang.org/protobuf v1.28.1
+	google.golang.org/api v0.155.0
+	google.golang.org/genproto v0.0.0-20231212172506-995d672761c0
+	google.golang.org/grpc v1.60.1
+	google.golang.org/protobuf v1.32.0
 )
 
 require (
-	cloud.google.com/go/compute v1.18.0 // indirect
+	cloud.google.com/go/compute v1.23.3 // indirect
 	cloud.google.com/go/compute/metadata v0.2.3 // indirect
-	cloud.google.com/go/iam v0.12.0 // indirect
-	cloud.google.com/go/longrunning v0.4.1 // indirect
+	cloud.google.com/go/iam v1.1.5 // indirect
+	cloud.google.com/go/longrunning v0.5.4 // indirect
 	github.com/census-instrumentation/opencensus-proto v0.4.1 // indirect
 	github.com/cespare/xxhash/v2 v2.2.0 // indirect
 	github.com/chzyer/logex v1.1.10 // indirect
 	github.com/chzyer/test v0.0.0-20180213035817-a1ea475d72b1 // indirect
 	github.com/cncf/udpa/go v0.0.0-20220112060539-c52dc94e7fbe // indirect
-	github.com/cncf/xds/go v0.0.0-20230112175826-46e39c7b9b43 // indirect
-	github.com/envoyproxy/go-control-plane v0.11.0 // indirect
-	github.com/envoyproxy/protoc-gen-validate v0.9.1 // indirect
+	github.com/cncf/xds/go v0.0.0-20230607035331-e9ce68804cb4 // indirect
+	github.com/envoyproxy/go-control-plane v0.11.1 // indirect
+	github.com/envoyproxy/protoc-gen-validate v1.0.2 // indirect
+	github.com/felixge/httpsnoop v1.0.4 // indirect
+	github.com/go-logr/logr v1.3.0 // indirect
+	github.com/go-logr/stdr v1.2.2 // indirect
 	github.com/golang/groupcache v0.0.0-20210331224755-41bb18bfe9da // indirect
-	github.com/golang/protobuf v1.5.2 // indirect
-	github.com/googleapis/enterprise-certificate-proxy v0.2.3 // indirect
-	github.com/googleapis/gax-go/v2 v2.7.0 // indirect
+	github.com/golang/protobuf v1.5.3 // indirect
+	github.com/google/s2a-go v0.1.7 // indirect
+	github.com/googleapis/enterprise-certificate-proxy v0.3.2 // indirect
+	github.com/googleapis/gax-go/v2 v2.12.0 // indirect
+	github.com/json-iterator/go v1.1.12 // indirect
 	github.com/mattn/go-runewidth v0.0.8 // indirect
+	github.com/modern-go/concurrent v0.0.0-20180228061459-e0a39a4cb421 // indirect
+	github.com/modern-go/reflect2 v1.0.2 // indirect
 	go.opencensus.io v0.24.0 // indirect
+	go.opentelemetry.io/contrib/instrumentation/google.golang.org/grpc/otelgrpc v0.46.1 // indirect
+	go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.46.1 // indirect
+	go.opentelemetry.io/otel v1.21.0 // indirect
+	go.opentelemetry.io/otel/metric v1.21.0 // indirect
+	go.opentelemetry.io/otel/trace v1.21.0 // indirect
+	golang.org/x/crypto v0.17.0 // indirect
 	golang.org/x/exp v0.0.0-20230310171629-522b1b587ee0 // indirect
-	golang.org/x/net v0.8.0 // indirect
-	golang.org/x/oauth2 v0.6.0 // indirect
-	golang.org/x/sys v0.6.0 // indirect
-	golang.org/x/text v0.8.0 // indirect
-	golang.org/x/xerrors v0.0.0-20220907171357-04be3eba64a2 // indirect
-	google.golang.org/appengine v1.6.7 // indirect
+	golang.org/x/net v0.19.0 // indirect
+	golang.org/x/oauth2 v0.15.0 // indirect
+	golang.org/x/sync v0.5.0 // indirect
+	golang.org/x/sys v0.15.0 // indirect
+	golang.org/x/text v0.14.0 // indirect
+	golang.org/x/time v0.5.0 // indirect
+	golang.org/x/xerrors v0.0.0-20231012003039-104605ab7028 // indirect
+	google.golang.org/appengine v1.6.8 // indirect
+	google.golang.org/genproto/googleapis/api v0.0.0-20240102182953-50ed04b92917 // indirect
+	google.golang.org/genproto/googleapis/rpc v0.0.0-20240102182953-50ed04b92917 // indirect
 )