RunTransaction doesn't work with only reads

[radhus]

We use Postgres dialect and the RunTransaction function to get retries for our transactions, both read and write. We happened to still run v1.15.0, and when upgrading this dependency it turns out that this doesn't work for read transactions since version v1.17.0.

I adapted the examples/postgres test to demonstrate the issue:

func helloWorldFromPostgreSQL(projectId, instanceId, databaseId string) error {
	ctx := context.Background()
	db, err := sql.Open("spanner", fmt.Sprintf("projects/%s/instances/%s/databases/%s", projectId, instanceId, databaseId))
	if err != nil {
		return fmt.Errorf("failed to open database connection: %v", err)
	}
	defer db.Close()

	err = spannerdriver.RunTransaction(
		ctx,
		db,
		&sql.TxOptions{ReadOnly: true},
		func(ctx context.Context, tx *sql.Tx) error {
			rows, err := tx.QueryContext(ctx, "SELECT $1::varchar as message", "Hello World from Spanner PostgreSQL")
			if err != nil {
				return fmt.Errorf("failed to execute query: %v", err)
			}
			defer rows.Close()

			var msg string
			for rows.Next() {
				if err := rows.Scan(&msg); err != nil {
					return fmt.Errorf("failed to scan row values: %v", err)
				}
				fmt.Printf("%s\n", msg)
			}
			if err := rows.Err(); err != nil {
				return fmt.Errorf("failed to execute query: %v", err)
			}
			return nil
		},
	)
	if err != nil {
		return fmt.Errorf("transaction failed: %v", err)
	}
	return nil
}

This test passes on v1.15.0:

Hello World from Spanner PostgreSQL

But on later versions, it fails with:

2026/01/21 16:26:21 transaction failed: spanner: code = "FailedPrecondition", desc = "this connection has not executed a read/write transaction that committed successfully"

I bisected the issue and it pinpointed first bad commit 463bb09 (PR #491) - something that was included to fix my own request in #488 🙈. Sorry for not testing it earlier!

Do you think we should keep using RunTransaction for read transactions, or should we use another pattern?

Thanks!

Environment details

• Programming language: Go
• OS: macOS
• Language runtime version: Go 1.25.5
• Package version: From v1.18.0 and to latest

[olavloite]

Do you think we should keep using RunTransaction for read transactions, or should we use another pattern?

For read-only transactions (so literally transactions that are configured with &sql.TxOptions{ReadOnly: true}) you do not need to use RunTransaction. RunTransaction is only intended for read/write transactions, as Spanner can abort any read/write transaction. Read-only transactions are never aborted by Spanner. So for read-only transactions you can safely use the standard database/sql transaction pattern like this:

	ctx := context.Background()
	db, err := sql.Open("spanner", fmt.Sprintf("projects/%s/instances/%s/databases/%s", projectId, instanceId, databaseId))
	if err != nil {
		return err
	}
	defer db.Close()

	tx, err := db.BeginTx(ctx, &sql.TxOptions{ReadOnly: true})
	if err != nil {
		return err
	}
	// Committing or rolling back a read-only transaction will not execute an actual Commit or Rollback
	// on the database, but it is needed in order to release the resources that are held by the read-only
	// transaction.
	defer tx.Commit()

	var c int64
	if err := tx.QueryRowContext(ctx, "SELECT COUNT(*) FROM Singers").Scan(&c); err != nil {
		return err
	}
	fmt.Printf("Singers count is initially %v\n", c)

	// Now insert a new record in the Singers table using an implicit transaction.
	// This change will be applied immediately to the database.
	if _, err := db.ExecContext(ctx, "INSERT INTO Singers (SingerId, Name) VALUES (@id, @name)", int64(1), "Bruce Allison"); err != nil {
		return err
	}

	// The read-only transaction was started before the row was inserted and will continue to read data at a timestamp
	// that was before the row was inserted. It will therefore not see the new record.
	if err := tx.QueryRowContext(ctx, "SELECT COUNT(*) FROM Singers").Scan(&c); err != nil {
		return err
	}
	fmt.Printf("Singers count as seen in the read-only transaction is %v\n", c)

[radhus]

@olavloite thanks, I'll just stop using that function for read-only transactions. Feel free to close this issue if you feel like it's not a bug, I was mostly surprised with the changed behavior.

[radhus]

@olavloite I realize I have another problem with RunTransaction but with the same error. Sometimes we do reads inside a read-write transaction and conclude we don't need to do any work and return nil.

Since commit 3253ded (#552) (since v1.20.0) we get the same error message as above. Example reproducing test:

func helloWorldFromPostgreSQL(projectId, instanceId, databaseId string) error {
	ctx := context.Background()
	db, err := sql.Open("spanner", fmt.Sprintf("projects/%s/instances/%s/databases/%s", projectId, instanceId, databaseId))
	if err != nil {
		return fmt.Errorf("failed to open database connection: %v", err)
	}
	defer db.Close()

	err = spannerdriver.RunTransaction(
		ctx,
		db,
		&sql.TxOptions{},
		func(ctx context.Context, tx *sql.Tx) error {
			fmt.Println("First transaction")
			rows, err := db.QueryContext(ctx, "SELECT $1::varchar as message", "Hello World from Spanner PostgreSQL")
			if err != nil {
				return fmt.Errorf("failed to execute query: %v", err)
			}
			defer rows.Close()
			return nil
		},
	)
	if err != nil {
		return fmt.Errorf("transaction failed: %v", err)
	}

	err = spannerdriver.RunTransaction(
		ctx,
		db,
		&sql.TxOptions{},
		func(ctx context.Context, tx *sql.Tx) error {
			fmt.Println("Second transaction")
			rows, err := db.QueryContext(ctx, "SELECT $1::varchar as message", "Hello World from Spanner PostgreSQL")
			if err != nil {
				return fmt.Errorf("failed to execute query: %v", err)
			}
			defer rows.Close()
			return nil
		},
	)
	if err != nil {
		return fmt.Errorf("transaction failed: %v", err)
	}
	return nil
}

On v1.15.0:

First transaction
Second transaction

On v1.20.0:

First transaction
2026/01/21 21:17:08 transaction failed: spanner: code = "FailedPrecondition", desc = "this connection has not executed a read/write transaction that committed successfully"

Is this a real problem (let me know if I should open another issue) or should I make sure to return non-nil errors on those RunTransaction inner functions? I'm not sure if such requirement is documented anywhere.