chore: create shared lib for connections

.github/workflows/spanner-lib-tests.yml

@@ -0,0 +1,89 @@
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+permissions:
+  contents: read
+  pull-requests: write
+name: Spanner Lib Tests
+jobs:
+  test:
+    strategy:
+      matrix:
+        go-version: [1.24.x]
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - name: Install Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: ${{ matrix.go-version }}
+      - name: Checkout code
+        uses: actions/checkout@v4
+      - name: Run unit tests
+        working-directory: spannerlib/lib
+        run: go test -race -short
+
+  build-lib:
+    strategy:
+      matrix:
+        go-version: [1.24.x]
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - name: Install Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: ${{ matrix.go-version }}
+      - name: Checkout code
+        uses: actions/checkout@v4
+      - name: Build shared lib
+        working-directory: spannerlib/shared
+        run: go build -o spannerlib.so -buildmode=c-shared shared_lib.go
+
+  test-dotnet-ubuntu:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Install Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: 1.24
+      - name: Checkout code
+        uses: actions/checkout@v4
+      - name: Build shared lib
+        working-directory: spannerlib/shared
+        run: go build -o spannerlib.so -buildmode=c-shared shared_lib.go
+      - name: Copy lib to dotnet folder
+        working-directory: spannerlib
+        run: |
+          mkdir -p dotnet-spannerlib/Google.Cloud.SpannerLib.Native/libraries/any
+          cp shared/spannerlib.so dotnet-spannerlib/Google.Cloud.SpannerLib.Native/libraries/any/spannerlib.so
+      - name: Build gRPC server
+        working-directory: spannerlib/grpc-server
+        run: go build grpc_server.go
+      - name: Copy gRPC server to dotnet folder
+        working-directory: spannerlib
+        run: |
+          mkdir -p dotnet-spannerlib/Google.Cloud.SpannerLib.Grpc/binaries/any
+          cp grpc-server/grpc_server dotnet-spannerlib/Google.Cloud.SpannerLib.Grpc/binaries/any/grpc_server
+      - name: Install dotnet
+        uses: actions/setup-dotnet@v4
+        with:
+          dotnet-version: '9.0.x'
+      - name: dotnet version
+        run: dotnet --version
+      - name: Build native library package
+        run: dotnet pack
+        working-directory: spannerlib/dotnet-spannerlib/Google.Cloud.SpannerLib.Native
+      - name: Add package source
+        run: dotnet nuget add source "$PWD"/bin/Release --name local
+        working-directory: spannerlib/dotnet-spannerlib/Google.Cloud.SpannerLib.Native
+      - name: Restore dependencies
+        run: dotnet restore
+        working-directory: spannerlib/dotnet-spannerlib
+      - name: Build
+        run: dotnet build --no-restore
+        working-directory: spannerlib/dotnet-spannerlib
+      - name: Unit Tests
+        working-directory: spannerlib/dotnet-spannerlib/Google.Cloud.SpannerLib.Tests
+        run: dotnet test --no-build --verbosity normal

checksum_row_iterator.go

@@ -23,6 +23,7 @@ import (
 
 	"cloud.google.com/go/spanner"
 	sppb "cloud.google.com/go/spanner/apiv1/spannerpb"
+	"github.com/googleapis/go-sql-spanner/parser"
 	"google.golang.org/api/iterator"
 	"google.golang.org/grpc/codes"
 	"google.golang.org/grpc/status"
@@ -51,10 +52,11 @@ type checksumRowIterator struct {
 	*spanner.RowIterator
 	metadata *sppb.ResultSetMetadata
 
-	ctx     context.Context
-	tx      *readWriteTransaction
-	stmt    spanner.Statement
-	options spanner.QueryOptions
+	ctx      context.Context
+	tx       *readWriteTransaction
+	stmt     spanner.Statement
+	stmtType parser.StatementType
+	options  spanner.QueryOptions
 	// nc (nextCount) indicates the number of times that next has been called
 	// on the iterator. Next() will be called the same number of times during
 	// a retry.
@@ -253,10 +255,5 @@ func (it *checksumRowIterator) Metadata() (*sppb.ResultSetMetadata, error) {
 }
 
 func (it *checksumRowIterator) ResultSetStats() *sppb.ResultSetStats {
-	// TODO: The Spanner client library should offer an option to get the full
-	//       ResultSetStats, instead of only the RowCount and QueryPlan.
-	return &sppb.ResultSetStats{
-		RowCount:  &sppb.ResultSetStats_RowCountExact{RowCountExact: it.RowIterator.RowCount},
-		QueryPlan: it.RowIterator.QueryPlan,
-	}
+	return createResultSetStats(it.RowIterator, it.stmtType)
 }

conn.go

@@ -222,6 +222,9 @@ type SpannerConn interface {
 	// return the same Spanner client.
 	UnderlyingClient() (client *spanner.Client, err error)
 
+	// DetectStatementType returns the type of SQL statement.
+	DetectStatementType(query string) parser.StatementType
+
 	// resetTransactionForRetry resets the current transaction after it has
 	// been aborted by Spanner. Calling this function on a transaction that
 	// has not been aborted is not supported and will cause an error to be
@@ -280,12 +283,18 @@ type conn struct {
 	// tempBatchReadOnlyTransactionOptions are temporarily set right before a
 	// batch read-only transaction is started on a Spanner connection.
 	tempBatchReadOnlyTransactionOptions *BatchReadOnlyTransactionOptions
+	tempProtoTransactionOptions         *spannerpb.TransactionOptions
 }
 
 func (c *conn) UnderlyingClient() (*spanner.Client, error) {
 	return c.client, nil
 }
 
+func (c *conn) DetectStatementType(query string) parser.StatementType {
+	info := c.parser.DetectStatementType(query)
+	return info.StatementType
+}
+
 func (c *conn) CommitTimestamp() (time.Time, error) {
 	ts := propertyCommitTimestamp.GetValueOrDefault(c.state)
 	if ts == nil {
@@ -389,6 +398,16 @@ func (c *conn) ReadOnlyStaleness() spanner.TimestampBound {
 	return propertyReadOnlyStaleness.GetValueOrDefault(c.state)
 }
 
+func (c *conn) readOnlyStalenessPointer() *spanner.TimestampBound {
+	val := propertyReadOnlyStaleness.GetConnectionPropertyValue(c.state)
+	if val == nil || !val.HasValue() {
+		return nil
+	}
+	staleness, _ := val.GetValue()
+	timestampBound := staleness.(spanner.TimestampBound)
+	return &timestampBound
+}
+
 func (c *conn) SetReadOnlyStaleness(staleness spanner.TimestampBound) error {
 	_, err := c.setReadOnlyStaleness(staleness)
 	return err
@@ -675,6 +694,17 @@ func sum(affected []int64) int64 {
 	return sum
 }
 
+func (c *conn) WriteMutations(ctx context.Context, ms []*spanner.Mutation) (*spanner.CommitResponse, error) {
+	if c.inTransaction() {
+		return nil, c.BufferWrite(ms)
+	}
+	ts, err := c.Apply(ctx, ms)
+	if err != nil {
+		return nil, err
+	}
+	return &spanner.CommitResponse{CommitTs: ts}, nil
+}
+
 func (c *conn) Apply(ctx context.Context, ms []*spanner.Mutation, opts ...spanner.ApplyOption) (commitTimestamp time.Time, err error) {
 	if c.inTransaction() {
 		return time.Time{}, spanner.ToSpannerError(
@@ -858,13 +888,13 @@ func (c *conn) queryContext(ctx context.Context, query string, execOptions *Exec
 			// The statement was either detected as being a query, or potentially not recognized at all.
 			// In that case, just default to using a single-use read-only transaction and let Spanner
 			// return an error if the statement is not suited for that type of transaction.
-			iter = &readOnlyRowIterator{c.execSingleQuery(ctx, c.client, stmt, c.ReadOnlyStaleness(), execOptions)}
+			iter = &readOnlyRowIterator{c.execSingleQuery(ctx, c.client, stmt, c.ReadOnlyStaleness(), execOptions), statementType.StatementType}
 		}
 	} else {
 		if execOptions.PartitionedQueryOptions.PartitionQuery {
 			return c.tx.partitionQuery(ctx, stmt, execOptions)
 		}
-		iter, err = c.tx.Query(ctx, stmt, execOptions)
+		iter, err = c.tx.Query(ctx, stmt, statementType.StatementType, execOptions)
 		if err != nil {
 			return nil, err
 		}
@@ -987,6 +1017,7 @@ func (c *conn) options(reset bool) *ExecOptions {
 			},
 		},
 		PartitionedQueryOptions: PartitionedQueryOptions{},
+		TimestampBound:          c.readOnlyStalenessPointer(),
 	}
 	if c.tempExecOptions != nil {
 		effectiveOptions.merge(c.tempExecOptions)
@@ -1071,6 +1102,26 @@ func (c *conn) getBatchReadOnlyTransactionOptions() BatchReadOnlyTransactionOpti
 	return BatchReadOnlyTransactionOptions{TimestampBound: c.ReadOnlyStaleness()}
 }
 
+func (c *conn) BeginReadOnlyTransaction(ctx context.Context, options *ReadOnlyTransactionOptions) (driver.Tx, error) {
+	c.withTempReadOnlyTransactionOptions(options)
+	tx, err := c.BeginTx(ctx, driver.TxOptions{ReadOnly: true})
+	if err != nil {
+		c.withTempReadOnlyTransactionOptions(nil)
+		return nil, err
+	}
+	return tx, nil
+}
+
+func (c *conn) BeginReadWriteTransaction(ctx context.Context, options *ReadWriteTransactionOptions) (driver.Tx, error) {
+	c.withTempTransactionOptions(options)
+	tx, err := c.BeginTx(ctx, driver.TxOptions{})
+	if err != nil {
+		c.withTempTransactionOptions(nil)
+		return nil, err
+	}
+	return tx, nil
+}
+
 func (c *conn) Begin() (driver.Tx, error) {
 	return c.BeginTx(context.Background(), driver.TxOptions{})
 }
@@ -1254,18 +1305,21 @@ func (c *conn) inReadWriteTransaction() bool {
 	return false
 }
 
-func (c *conn) commit(ctx context.Context) (*spanner.CommitResponse, error) {
+func (c *conn) Commit(ctx context.Context) (*spanner.CommitResponse, error) {
 	if !c.inTransaction() {
 		return nil, status.Errorf(codes.FailedPrecondition, "this connection does not have a transaction")
 	}
 	// TODO: Pass in context to the tx.Commit() function.
 	if err := c.tx.Commit(); err != nil {
 		return nil, err
 	}
-	return c.CommitResponse()
+
+	// This will return either the commit response or nil, depending on whether the transaction was a
+	// read/write transaction or a read-only transaction.
+	return propertyCommitResponse.GetValueOrDefault(c.state), nil
 }
 
-func (c *conn) rollback(ctx context.Context) error {
+func (c *conn) Rollback(ctx context.Context) error {
 	if !c.inTransaction() {
 		return status.Errorf(codes.FailedPrecondition, "this connection does not have a transaction")
 	}
@@ -1274,6 +1328,9 @@ func (c *conn) rollback(ctx context.Context) error {
 }
 
 func queryInSingleUse(ctx context.Context, c *spanner.Client, statement spanner.Statement, tb spanner.TimestampBound, options *ExecOptions) *spanner.RowIterator {
+	if options.TimestampBound != nil {
+		tb = *options.TimestampBound
+	}
 	return c.Single().WithTimestampBound(tb).QueryWithOptions(ctx, statement, options.QueryOptions)
 }
 

driver.go

@@ -173,6 +173,10 @@ type ExecOptions struct {
 	TransactionOptions spanner.TransactionOptions
 	// QueryOptions are the query options that will be used for the statement.
 	QueryOptions spanner.QueryOptions
+	// TimestampBound is the timestamp bound that will be used for the statement
+	// if it is a query outside a transaction. Setting this option will override
+	// the default TimestampBound that is set on the connection.
+	TimestampBound *spanner.TimestampBound
 
 	// PartitionedQueryOptions are used for partitioned queries, and ignored
 	// for all other statements.
@@ -234,6 +238,9 @@ func (dest *ExecOptions) merge(src *ExecOptions) {
 	if src.AutocommitDMLMode != Unspecified {
 		dest.AutocommitDMLMode = src.AutocommitDMLMode
 	}
+	if src.TimestampBound != nil {
+		dest.TimestampBound = src.TimestampBound
+	}
 	(&dest.PartitionedQueryOptions).merge(&src.PartitionedQueryOptions)
 	mergeQueryOptions(&dest.QueryOptions, &src.QueryOptions)
 	mergeTransactionOptions(&dest.TransactionOptions, &src.TransactionOptions)
@@ -1143,6 +1150,10 @@ func BeginReadWriteTransaction(ctx context.Context, db *sql.DB, options ReadWrit
 		// be active when we hit this point.
 		go conn.Close()
 	}
+	return BeginReadWriteTransactionOnConn(ctx, conn, options)
+}
+
+func BeginReadWriteTransactionOnConn(ctx context.Context, conn *sql.Conn, options ReadWriteTransactionOptions) (*sql.Tx, error) {
 	if err := withTempReadWriteTransactionOptions(conn, &options); err != nil {
 		return nil, err
 	}
@@ -1195,6 +1206,10 @@ func BeginReadOnlyTransaction(ctx context.Context, db *sql.DB, options ReadOnlyT
 		// be active when we hit this point.
 		go conn.Close()
 	}
+	return BeginReadOnlyTransactionOnConn(ctx, conn, options)
+}
+
+func BeginReadOnlyTransactionOnConn(ctx context.Context, conn *sql.Conn, options ReadOnlyTransactionOptions) (*sql.Tx, error) {
 	if err := withTempReadOnlyTransactionOptions(conn, &options); err != nil {
 		return nil, err
 	}

driver_test.go

@@ -631,7 +631,9 @@ func TestConn_NonDdlStatementsInDdlBatch(t *testing.T) {
 		state:  createInitialConnectionState(connectionstate.TypeNonTransactional, map[string]connectionstate.ConnectionPropertyValue{}),
 		batch:  &batch{tp: parser.BatchTypeDdl},
 		execSingleQuery: func(ctx context.Context, c *spanner.Client, statement spanner.Statement, tb spanner.TimestampBound, options *ExecOptions) *spanner.RowIterator {
-			return &spanner.RowIterator{}
+			return &spanner.RowIterator{
+				Metadata: &spannerpb.ResultSetMetadata{},
+			}
 		},
 		execSingleDMLTransactional: func(ctx context.Context, c *spanner.Client, statement spanner.Statement, statementInfo *parser.StatementInfo, options *ExecOptions) (*result, *spanner.CommitResponse, error) {
 			return &result{}, &spanner.CommitResponse{}, nil

driver_with_mockserver_test.go

@@ -5531,9 +5531,8 @@ func setupTestDBConnectionWithParams(t *testing.T, params string) (db *sql.DB, s
 
 func setupTestDBConnectionWithParamsAndDialect(t *testing.T, params string, dialect databasepb.DatabaseDialect) (db *sql.DB, server *testutil.MockedSpannerInMemTestServer, teardown func()) {
 	server, _, serverTeardown := setupMockedTestServerWithDialect(t, dialect)
-	db, err := sql.Open(
-		"spanner",
-		fmt.Sprintf("%s/projects/p/instances/i/databases/d?useplaintext=true;%s", server.Address, params))
+	dsn := fmt.Sprintf("%s/projects/p/instances/i/databases/d?useplaintext=true;%s", server.Address, params)
+	db, err := sql.Open("spanner", dsn)
 	if err != nil {
 		serverTeardown()
 		t.Fatal(err)

partitioned_query.go

@@ -22,6 +22,7 @@ import (
 	"io"
 
 	"cloud.google.com/go/spanner"
+	"github.com/googleapis/go-sql-spanner/parser"
 	"google.golang.org/grpc/codes"
 	"google.golang.org/grpc/status"
 )
@@ -231,7 +232,7 @@ func (pq *PartitionedQuery) execute(ctx context.Context, index int) (*rows, erro
 		return nil, spanner.ToSpannerError(status.Errorf(codes.InvalidArgument, "invalid partition index: %d", index))
 	}
 	spannerIter := pq.tx.Execute(ctx, pq.Partitions[index])
-	iter := &readOnlyRowIterator{spannerIter}
+	iter := &readOnlyRowIterator{spannerIter, parser.StatementTypeQuery}
 	return &rows{it: iter, decodeOption: pq.execOptions.DecodeOption}, nil
 }
 

spannerlib/.gitignore

@@ -0,0 +1,3 @@
+spannerlib.h
+spannerlib.so
+grpc_server

spannerlib/README.md

@@ -0,0 +1,6 @@
+# Shared Library (Internal)
+
+__This module can receive breaking changes without prior notice.__
+
+This is an internal module that is used to expose the features in the database/sql driver
+to drivers in other programming languages.

spannerlib/api/README.md

@@ -0,0 +1,6 @@
+# Shared Library (Internal)
+
+__This module can receive breaking changes without prior notice.__
+
+This is the common internal API for the various external APIs for exposing the
+features in the database/sql driver to drivers in other programming languages.