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