Use the Spanner database/sql driver

Go database/sql is a generic interface around SQL (or SQL-like) databases for the Go programming language. To use database/sql with your application, use the Spanner database/sql driver.

The Spannerdatabase/sql driver supports both GoogleSQL-dialect databases and PostgreSQL-dialect databases.

Install the Spanner database/sql driver

To use the Spanner database/sql driver in your application, add the following module to your go.mod file:

 github.com/googleapis/go-sql-spanner

Use the Spanner database/sql driver

To create a database/sql connection to a Spanner database, use spanner as the driver name and a fully qualified database name as the connection string:

GoogleSQL 

import ( "context" "database/sql" "fmt" _ "github.com/googleapis/go-sql-spanner" ) func connect(projectId, instanceId, databaseId string) error { ctx := context.Background() dsn := fmt.Sprintf("projects/%s/instances/%s/databases/%s", projectId, instanceId, databaseId) db, err := sql.Open("spanner", dsn) if err != nil { return fmt.Errorf("failed to open database connection: %v", err) } defer func() { _ = db.Close() }() fmt.Printf("Connected to %s\n", dsn) row := db.QueryRowContext(ctx, "select @greeting", "Hello from Spanner") var greeting string if err := row.Scan(&greeting); err != nil { return fmt.Errorf("failed to get greeting: %v", err) } fmt.Printf("Greeting: %s\n", greeting) return nil }

PostgreSQL 

import ( "context" "database/sql" "fmt" _ "github.com/googleapis/go-sql-spanner" ) func connect(projectId, instanceId, databaseId string) error { ctx := context.Background() dsn := fmt.Sprintf("projects/%s/instances/%s/databases/%s", projectId, instanceId, databaseId) db, err := sql.Open("spanner", dsn) if err != nil { return fmt.Errorf("failed to open database connection: %v", err) } defer func() { _ = db.Close() }() fmt.Printf("Connected to %s\n", dsn) // The Spanner database/sql driver supports both PostgreSQL-style query // parameters ($1, $2, ...) and positional query parameters (?, ?, ...). // This example uses PostgreSQL-style parameters. row := db.QueryRowContext(ctx, "select $1", "Hello from Spanner PostgreSQL") var greeting string if err := row.Scan(&greeting); err != nil { return fmt.Errorf("failed to get greeting: %v", err) } fmt.Printf("Greeting: %s\n", greeting) return nil }

For more information, see the Spanner database/sql driver GitHub repository.

Supported features

The Spanner Go database/sql examples code directory contains ready-to-run examples for commonly used Spanner features.

Performance tips

To get the best possible performance when using the Spanner database/sql driver, follow these best practices:

What's next