Erste Schritte mit Spanner in Go-Datenbank/SQL

Ziele

In dieser Anleitung werden die folgenden Schritte mit dem Spanner-Treiber „database/sql“ beschrieben:

• Spanner-Instanz und -Datenbank erstellen
• SQL-Abfragen für Daten in der Datenbank schreiben, lesen und ausführen
• Datenbankschema aktualisieren
• Daten mit einer Lese-Schreib-Transaktion aktualisieren
• Sekundären Index für die Datenbank hinzufügen
• Mit dem Index Daten lesen und SQL-Abfragen ausführen
• Daten über eine schreibgeschützte Transaktion abrufen

Kosten

In dieser Anleitung wird Cloud Spanner verwendet, eine kostenpflichtige Komponente vonGoogle Cloud. Informationen zu den Kosten für die Verwendung von Spanner finden Sie auf der Seite zu den Preisen.

Hinweis

Führen Sie die unter Einrichten beschriebenen Schritte aus. Dazu gehören das Erstellen und Festlegen eines Standardprojekts von Google Cloud , das Aktivieren der Abrechnung, das Aktivieren der Cloud Spanner API und das Einrichten von OAuth 2.0, um Authentifizierungsdaten für die Verwendung der Cloud Spanner API zu erhalten.

Sie müssen insbesondere gcloud auth application-default login ausführen, um die lokale Entwicklungsumgebung mit Anmeldedaten für die Authentifizierung einzurichten.

Hinweis: Wenn Sie die Ressourcen, die Sie in dieser Anleitung erstellen, nicht behalten möchten, sollten Sie ein neues Google Cloud -Projekt erstellen, anstatt ein vorhandenes Projekt auszuwählen. Nachdem Sie die Anleitung abgeschlossen haben, können Sie das Projekt löschen und alle mit dem Projekt verknüpften Ressourcen entfernen.

Lokale Datenbank-/SQL-Umgebung vorbereiten

1. Laden Sie Go herunter und installieren Sie es auf Ihrem Entwicklungscomputer, falls es noch nicht installiert ist.

2. Klonen Sie das Beispiel-Repository auf Ihren lokalen Computer:

   git clone https://github.com/googleapis/go-sql-spanner.git
   

3. Wechseln Sie zu dem Verzeichnis, das den Cloud Spanner-Beispielcode enthält:

   cd go-sql-spanner/snippets
   

Instanz erstellen

Bei der ersten Verwendung von Spanner müssen Sie eine Instanz erstellen. Dies ist eine Zuordnung von Ressourcen, die von Spanner-Datenbanken verwendet werden. Wenn Sie eine Instanz erstellen, müssen Sie eine Instanzkonfiguration auswählen. Abhängig davon werden der Speicherort Ihrer Daten sowie die Anzahl der zu verwendenden Knoten festgelegt. Anhand der Knotenanzahl wird dann die Menge der Bereitstellungs- und Speicherressourcen in Ihrer Instanz festgelegt.

Unter Instanz erstellen erfahren Sie, wie Sie eine Spanner-Instanz mit einer der folgenden Methoden erstellen. Sie können Ihre Instanz test-instance nennen, um sie mit anderen Themen in diesem Dokument zu verwenden, die auf eine Instanz mit dem Namen test-instance verweisen.

• Google Cloud CLI
• Die Google Cloud Console
• Eine Clientbibliothek (C++, C#, Go, Java, Node.js, PHP, Python, Ruby oder Rust)

Beispieldateien ansehen

Das Beispiel-Repository enthält ein Beispiel, das zeigt, wie Spanner mit database/sql verwendet wird.

Sehen Sie sich die Datei getting_started_guide.go an, in der die Verwendung von Spanner gezeigt wird. Der Code zeigt, wie eine neue Datenbank erstellt und verwendet wird. In den Daten wird das Beispielschema verwendet, das auf der Seite Schema und Datenmodell dargestellt ist.

Datenbank erstellen

GoogleSQL

gcloud spanner databases create example-db --instance=test-instance

PostgreSQL

gcloud spanner databases create example-db --instance=test-instance \
  --database-dialect=POSTGRESQL

Hier sollten Sie dies sehen:

Creating database...done.

Tabellen erstellen

Mit dem folgenden Code werden zwei Tabellen in der Datenbank erstellt.

Hinweis: In den folgenden Codebeispielen werden diese beiden Tabellen verwendet. Wenn Sie diesen Code nicht ausführen, erstellen Sie die Tabellen mit der Google Cloud Console oder der gcloud CLI. Weitere Informationen finden Sie im Beispielschema.

GoogleSQL

import (
	"context"
	"database/sql"
	"fmt"
	"io"

	_ "github.com/googleapis/go-sql-spanner"
)

func CreateTables(ctx context.Context, w io.Writer, databaseName string) error {
	db, err := sql.Open("spanner", databaseName)
	if err != nil {
		return err
	}
	defer db.Close()

	// Create two tables in one batch on Spanner.
	conn, err := db.Conn(ctx)
	defer conn.Close()

	// Start a DDL batch on the connection.
	// This instructs the connection to buffer all DDL statements until the
	// command `run batch` is executed.
	if _, err := conn.ExecContext(ctx, "start batch ddl"); err != nil {
		return err
	}
	if _, err := conn.ExecContext(ctx,
		`CREATE TABLE Singers (
				SingerId   INT64 NOT NULL,
				FirstName  STRING(1024),
				LastName   STRING(1024),
				SingerInfo BYTES(MAX)
			) PRIMARY KEY (SingerId)`); err != nil {
		return err
	}
	if _, err := conn.ExecContext(ctx,
		`CREATE TABLE Albums (
				SingerId     INT64 NOT NULL,
				AlbumId      INT64 NOT NULL,
				AlbumTitle   STRING(MAX)
			) PRIMARY KEY (SingerId, AlbumId),
			INTERLEAVE IN PARENT Singers ON DELETE CASCADE`); err != nil {
		return err
	}
	// `run batch` sends the DDL statements to Spanner and blocks until
	// all statements have finished executing.
	if _, err := conn.ExecContext(ctx, "run batch"); err != nil {
		return err
	}

	fmt.Fprintf(w, "Created Singers & Albums tables in database: [%s]\n", databaseName)
	return nil
}

PostgreSQL

import (
	"context"
	"database/sql"
	"fmt"
	"io"

	_ "github.com/googleapis/go-sql-spanner"
)

func CreateTablesPostgreSQL(ctx context.Context, w io.Writer, databaseName string) error {
	db, err := sql.Open("spanner", databaseName)
	if err != nil {
		return err
	}
	defer func() { _ = db.Close() }()

	// Create two tables in one batch on Spanner PostgreSQL.
	conn, err := db.Conn(ctx)
	if err != nil {
		return err
	}
	defer func() { _ = conn.Close() }()

	// Start a DDL batch on the connection.
	// This instructs the connection to buffer all DDL statements until the
	// command `run batch` is executed.
	if _, err := conn.ExecContext(ctx, "start batch ddl"); err != nil {
		return err
	}
	if _, err := conn.ExecContext(ctx,
		`create table singers (
				singer_id   bigint not null primary key,
				first_name  varchar(1024),
				last_name   varchar(1024),
				singer_info bytea
			)`); err != nil {
		return err
	}
	if _, err := conn.ExecContext(ctx,
		`create table albums (
				singer_id     bigint not null,
				album_id      bigint not null,
				album_title   varchar,
				primary key (singer_id, album_id)
			)
			interleave in parent singers on delete cascade`); err != nil {
		return err
	}
	// `run batch` sends the DDL statements to Spanner and blocks until
	// all statements have finished executing.
	if _, err := conn.ExecContext(ctx, "run batch"); err != nil {
		return err
	}

	_, _ = fmt.Fprintf(w, "Created singers & albums tables in database: [%s]\n", databaseName)
	return nil
}

Führen Sie das Beispiel mit dem folgenden Befehl aus:

GoogleSQL

go run getting_started_guide.go createtables projects/PROJECT_ID/instances/test-instance/databases/example-db

PostgreSQL

go run getting_started_guide.go createtablespg projects/PROJECT_ID/instances/test-instance/databases/example-db

Im nächsten Schritt werden Daten in die Datenbank geschrieben.

Verbindung herstellen

Zum Ausführen von Lese- oder Schreibvorgängen müssen Sie einen sql.DB erstellen. sql.DB enthält einen Verbindungspool, der für die Interaktion mit Spanner verwendet werden kann. Der Datenbankname und andere Verbindungseigenschaften werden im database/sql-Datenquellennamen angegeben.

GoogleSQL

import (
	"context"
	"database/sql"
	"fmt"
	"io"

	_ "github.com/googleapis/go-sql-spanner"
)

func CreateConnection(ctx context.Context, w io.Writer, databaseName string) error {
	// The dataSourceName should start with a fully qualified Spanner database name
	// in the format `projects/my-project/instances/my-instance/databases/my-database`.
	// Additional properties can be added after the database name by
	// adding one or more `;name=value` pairs.

	dsn := fmt.Sprintf("%s;numChannels=8", databaseName)
	db, err := sql.Open("spanner", dsn)
	if err != nil {
		return err
	}
	defer db.Close()

	row := db.QueryRowContext(ctx, "select 'Hello world!' as hello")
	var msg string
	if err := row.Scan(&msg); err != nil {
		return err
	}
	fmt.Fprintf(w, "Greeting from Spanner: %s\n", msg)
	return nil
}

PostgreSQL

import (
	"context"
	"database/sql"
	"fmt"
	"io"

	_ "github.com/googleapis/go-sql-spanner"
)

func CreateConnectionPostgreSQL(ctx context.Context, w io.Writer, databaseName string) error {
	// The dataSourceName should start with a fully qualified Spanner database name
	// in the format `projects/my-project/instances/my-instance/databases/my-database`.
	// Additional properties can be added after the database name by
	// adding one or more `;name=value` pairs.

	dsn := fmt.Sprintf("%s;numChannels=8", databaseName)
	db, err := sql.Open("spanner", dsn)
	if err != nil {
		return err
	}
	defer func() { _ = db.Close() }()

	// The Spanner database/sql driver supports both PostgreSQL-style query
	// parameters ($1, $2, ...) and positional query parameters (?, ?, ...).
	row := db.QueryRowContext(ctx, "select $1 as hello", "Hello world!")
	var msg string
	if err := row.Scan(&msg); err != nil {
		return err
	}
	_, _ = fmt.Fprintf(w, "Greeting from Spanner PostgreSQL: %s\n", msg)
	return nil
}

Daten mit DML schreiben

Sie können Daten mit der Datenbearbeitungssprache (Data Manipulation Language, DML) in eine Lese-Schreib-Transaktion einfügen.

Für das Ausführen einer DML-Anweisung verwenden Sie die Funktion ExecContext.

GoogleSQL

import (
	"context"
	"database/sql"
	"fmt"
	"io"

	_ "github.com/googleapis/go-sql-spanner"
)

func WriteDataWithDml(ctx context.Context, w io.Writer, databaseName string) error {
	db, err := sql.Open("spanner", databaseName)
	if err != nil {
		return err
	}
	defer db.Close()

	// Add 4 rows in one statement.
	// The database/sql driver supports positional query parameters.
	res, err := db.ExecContext(ctx,
		"INSERT INTO Singers (SingerId, FirstName, LastName) "+
			"VALUES (?, ?, ?), (?, ?, ?), "+
			"       (?, ?, ?), (?, ?, ?)",
		12, "Melissa", "Garcia",
		13, "Russel", "Morales",
		14, "Jacqueline", "Long",
		15, "Dylan", "Shaw")
	if err != nil {
		return err
	}
	c, err := res.RowsAffected()
	if err != nil {
		return err
	}
	fmt.Fprintf(w, "%v records inserted\n", c)

	return nil
}

PostgreSQL

import (
	"context"
	"database/sql"
	"fmt"
	"io"

	_ "github.com/googleapis/go-sql-spanner"
)

func WriteDataWithDmlPostgreSQL(ctx context.Context, w io.Writer, databaseName string) error {
	db, err := sql.Open("spanner", databaseName)
	if err != nil {
		return err
	}
	defer func() { _ = db.Close() }()

	// Add 4 rows in one statement.
	// The database/sql driver supports positional query parameters.
	res, err := db.ExecContext(ctx,
		"insert into singers (singer_id, first_name, last_name) "+
			"values (?, ?, ?), (?, ?, ?), "+
			"       (?, ?, ?), (?, ?, ?)",
		12, "Melissa", "Garcia",
		13, "Russel", "Morales",
		14, "Jacqueline", "Long",
		15, "Dylan", "Shaw")
	if err != nil {
		return err
	}
	c, err := res.RowsAffected()
	if err != nil {
		return err
	}
	_, _ = fmt.Fprintf(w, "%v records inserted\n", c)

	return nil
}

Führen Sie das Beispiel mit dem folgenden Befehl aus:

GoogleSQL

go run getting_started_guide.go dmlwrite projects/PROJECT_ID/instances/test-instance/databases/example-db

PostgreSQL

go run getting_started_guide.go dmlwritepg projects/PROJECT_ID/instances/test-instance/databases/example-db

Das Ergebnis zeigt Folgendes:

4 records inserted.

Hinweis: Die Commit-Größe ist begrenzt. Weitere Informationen finden Sie unter CRUD-Limit.

Daten mit Mutationen schreiben

Sie können Daten auch mithilfe von Mutationen einfügen.

Eine Mutation ist ein Container für Mutationsvorgänge. Eine Mutation stellt eine Sequenz von Einfügungen, Aktualisierungen und Löschungen dar, die Cloud Spanner atomar auf verschiedene Zeilen und Tabellen in einer Cloud Spanner-Datenbank anwendet.

Verwenden Sie Mutation.InsertOrUpdate(), um die Mutation INSERT_OR_UPDATE zu erstellen. Damit wird eine neue Zeile hinzugefügt oder Spaltenwerte aktualisiert, falls die Zeile bereits vorhanden ist. Alternativ können Sie die Methode Mutation.Insert() zum Erstellen der Mutation INSERT verwenden, mit der eine neue Zeile hinzugefügt wird.

Verwenden Sie die Funktion conn.Raw, um einen Verweis auf die zugrunde liegende Spanner-Verbindung abzurufen. Die Funktion SpannerConn.Apply wendet Mutationen atomar auf die Datenbank an.

Der folgende Code zeigt, wie die Daten mithilfe von Mutationen geschrieben werden:

GoogleSQL

import (
	"context"
	"database/sql"
	"fmt"
	"io"

	"cloud.google.com/go/spanner"
	spannerdriver "github.com/googleapis/go-sql-spanner"
)

func WriteDataWithMutations(ctx context.Context, w io.Writer, databaseName string) error {
	db, err := sql.Open("spanner", databaseName)
	if err != nil {
		return err
	}
	defer db.Close()

	// Get a connection so that we can get access to the Spanner specific
	// connection interface SpannerConn.
	conn, err := db.Conn(ctx)
	if err != nil {
		return err
	}
	defer conn.Close()

	singerColumns := []string{"SingerId", "FirstName", "LastName"}
	albumColumns := []string{"SingerId", "AlbumId", "AlbumTitle"}
	mutations := []*spanner.Mutation{
		spanner.Insert("Singers", singerColumns, []interface{}{int64(1), "Marc", "Richards"}),
		spanner.Insert("Singers", singerColumns, []interface{}{int64(2), "Catalina", "Smith"}),
		spanner.Insert("Singers", singerColumns, []interface{}{int64(3), "Alice", "Trentor"}),
		spanner.Insert("Singers", singerColumns, []interface{}{int64(4), "Lea", "Martin"}),
		spanner.Insert("Singers", singerColumns, []interface{}{int64(5), "David", "Lomond"}),
		spanner.Insert("Albums", albumColumns, []interface{}{int64(1), int64(1), "Total Junk"}),
		spanner.Insert("Albums", albumColumns, []interface{}{int64(1), int64(2), "Go, Go, Go"}),
		spanner.Insert("Albums", albumColumns, []interface{}{int64(2), int64(1), "Green"}),
		spanner.Insert("Albums", albumColumns, []interface{}{int64(2), int64(2), "Forever Hold Your Peace"}),
		spanner.Insert("Albums", albumColumns, []interface{}{int64(2), int64(3), "Terrified"}),
	}
	// Mutations can be written outside an explicit transaction using SpannerConn#Apply.
	if err := conn.Raw(func(driverConn interface{}) error {
		spannerConn, ok := driverConn.(spannerdriver.SpannerConn)
		if !ok {
			return fmt.Errorf("unexpected driver connection %v, expected SpannerConn", driverConn)
		}
		_, err = spannerConn.Apply(ctx, mutations)
		return err
	}); err != nil {
		return err
	}
	fmt.Fprintf(w, "Inserted %v rows\n", len(mutations))

	return nil
}

PostgreSQL

import (
	"context"
	"database/sql"
	"fmt"
	"io"

	"cloud.google.com/go/spanner"
	spannerdriver "github.com/googleapis/go-sql-spanner"
)

func WriteDataWithMutationsPostgreSQL(ctx context.Context, w io.Writer, databaseName string) error {
	db, err := sql.Open("spanner", databaseName)
	if err != nil {
		return err
	}
	defer func() { _ = db.Close() }()

	// Get a connection so that we can get access to the Spanner specific
	// connection interface SpannerConn.
	conn, err := db.Conn(ctx)
	if err != nil {
		return err
	}
	defer func() { _ = conn.Close() }()

	singerColumns := []string{"singer_id", "first_name", "last_name"}
	albumColumns := []string{"singer_id", "album_id", "album_title"}
	mutations := []*spanner.Mutation{
		spanner.Insert("singers", singerColumns, []interface{}{int64(1), "Marc", "Richards"}),
		spanner.Insert("singers", singerColumns, []interface{}{int64(2), "Catalina", "Smith"}),
		spanner.Insert("singers", singerColumns, []interface{}{int64(3), "Alice", "Trentor"}),
		spanner.Insert("singers", singerColumns, []interface{}{int64(4), "Lea", "Martin"}),
		spanner.Insert("singers", singerColumns, []interface{}{int64(5), "David", "Lomond"}),
		spanner.Insert("albums", albumColumns, []interface{}{int64(1), int64(1), "Total Junk"}),
		spanner.Insert("albums", albumColumns, []interface{}{int64(1), int64(2), "Go, Go, Go"}),
		spanner.Insert("albums", albumColumns, []interface{}{int64(2), int64(1), "Green"}),
		spanner.Insert("albums", albumColumns, []interface{}{int64(2), int64(2), "Forever Hold Your Peace"}),
		spanner.Insert("albums", albumColumns, []interface{}{int64(2), int64(3), "Terrified"}),
	}
	// Mutations can be written outside an explicit transaction using SpannerConn#Apply.
	if err := conn.Raw(func(driverConn interface{}) error {
		spannerConn, ok := driverConn.(spannerdriver.SpannerConn)
		if !ok {
			return fmt.Errorf("unexpected driver connection %v, expected SpannerConn", driverConn)
		}
		_, err = spannerConn.Apply(ctx, mutations)
		return err
	}); err != nil {
		return err
	}
	_, _ = fmt.Fprintf(w, "Inserted %v rows\n", len(mutations))

	return nil
}

Führen Sie das folgende Beispiel mit dem Argument write aus:

GoogleSQL

go run getting_started_guide.go write projects/PROJECT_ID/instances/test-instance/databases/example-db

PostgreSQL

go run getting_started_guide.go writepg projects/PROJECT_ID/instances/test-instance/databases/example-db

Hinweis: Die Commit-Größe ist begrenzt. Weitere Informationen finden Sie unter CRUD-Limit.

Daten mit SQL abfragen

Spanner unterstützt eine SQL-Schnittstelle zum Lesen von Daten, auf die Sie über die Befehlszeile mit der Google Cloud CLI oder programmatisch mit dem Spanner-Datenbank-/SQL-Treiber zugreifen können.

Über die Befehlszeile

Führen Sie die folgende SQL-Anweisung aus, damit Sie die Werte aller Spalten aus der Tabelle Albums lesen können:

GoogleSQL

gcloud spanner databases execute-sql example-db --instance=test-instance \
    --sql='SELECT SingerId, AlbumId, AlbumTitle FROM Albums'

GoogleSQL-Pipe-Syntax

gcloud spanner databases execute-sql example-db --instance=test-instance \
    --sql='FROM Albums |> SELECT SingerId, AlbumId, AlbumTitle'

PostgreSQL

gcloud spanner databases execute-sql example-db --instance=test-instance \
    --sql='SELECT singer_id, album_id, album_title FROM albums'

Hinweis: Die GoogleSQL-Referenz finden Sie unter Standard-SQL-Syntax in GoogleSQL oder Pipe-Syntax in GoogleSQL. Die PostgreSQL-Referenz finden Sie unter PostgreSQL-Lexikalische Struktur und Syntax.

Das Ergebnis zeigt Folgendes:

SingerId AlbumId AlbumTitle
1        1       Total Junk
1        2       Go, Go, Go
2        1       Green
2        2       Forever Hold Your Peace
2        3       Terrified

Spanner-Datenbank/SQL-Treiber verwenden

Sie können eine SQL-Anweisung nicht nur in der Befehlszeile ausführen, sondern auch programmatisch mit dem Spanner-Datenbank-/SQL-Treiber.

Die folgenden Funktionen und Structs werden zum Ausführen einer SQL-Abfrage verwendet:

• Die Funktion QueryContext in der Struktur DB: Verwenden Sie diese Funktion, um eine SQL-Anweisung auszuführen, die Zeilen zurückgibt, z. B. eine Abfrage oder eine DML-Anweisung mit einer THEN RETURN-Klausel.
• Die Struktur Rows: Verwenden Sie diese, um auf die von einer SQL-Anweisung zurückgegebenen Daten zuzugreifen.

Im folgenden Beispiel wird die Funktion QueryContext verwendet:

GoogleSQL

import (
	"context"
	"database/sql"
	"fmt"
	"io"

	_ "github.com/googleapis/go-sql-spanner"
)

func QueryData(ctx context.Context, w io.Writer, databaseName string) error {
	db, err := sql.Open("spanner", databaseName)
	if err != nil {
		return err
	}
	defer db.Close()

	rows, err := db.QueryContext(ctx,
		`SELECT SingerId, AlbumId, AlbumTitle
		FROM Albums
		ORDER BY SingerId, AlbumId`)
	defer rows.Close()
	if err != nil {
		return err
	}
	for rows.Next() {
		var singerId, albumId int64
		var title string
		err = rows.Scan(&singerId, &albumId, &title)
		if err != nil {
			return err
		}
		fmt.Fprintf(w, "%v %v %v\n", singerId, albumId, title)
	}
	if rows.Err() != nil {
		return rows.Err()
	}
	return rows.Close()
}

PostgreSQL

import (
	"context"
	"database/sql"
	"fmt"
	"io"

	_ "github.com/googleapis/go-sql-spanner"
)

func QueryDataPostgreSQL(ctx context.Context, w io.Writer, databaseName string) error {
	db, err := sql.Open("spanner", databaseName)
	if err != nil {
		return err
	}
	defer func() { _ = db.Close() }()

	rows, err := db.QueryContext(ctx,
		`select singer_id, album_id, album_title
		from albums
		order by singer_id, album_id`)
	defer func() { _ = rows.Close() }()
	if err != nil {
		return err
	}
	for rows.Next() {
		var singerId, albumId int64
		var title string
		err = rows.Scan(&singerId, &albumId, &title)
		if err != nil {
			return err
		}
		_, _ = fmt.Fprintf(w, "%v %v %v\n", singerId, albumId, title)
	}
	if rows.Err() != nil {
		return rows.Err()
	}
	return rows.Close()
}

Führen Sie das Beispiel mit dem folgenden Befehl aus:

GoogleSQL

go run getting_started_guide.go query projects/PROJECT_ID/instances/test-instance/databases/example-db

PostgreSQL

go run getting_started_guide.go querypg projects/PROJECT_ID/instances/test-instance/databases/example-db

Das Ergebnis zeigt Folgendes:

1 1 Total Junk
1 2 Go, Go, Go
2 1 Green
2 2 Forever Hold Your Peace
2 3 Terrified

Abfrage mit einem SQL-Parameter

Wenn Ihre Anwendung eine häufig ausgeführte Abfrage hat, können Sie die Leistung verbessern, indem Sie sie parametrisieren. Die resultierende parametrische Abfrage kann im Cache gespeichert und wiederverwendet werden, was die Kompilierungskosten senkt. Weitere Informationen finden Sie unter Abfrageparameter verwenden, um häufig ausgeführte Abfragen zu beschleunigen.

Hier ist ein Beispiel für die Verwendung eines Parameters in der WHERE-Klausel, um Datensätze abzufragen, die einen bestimmten Wert für LastName enthalten.

Der Spanner-Datenbank-/SQL-Treiber unterstützt sowohl positionale als auch benannte Abfrageparameter. Ein ? in einer SQL-Anweisung gibt einen positionellen Abfrageparameter an. Übergeben Sie die Suchparameterwerte als zusätzliche Argumente an die Funktion QueryContext. Beispiel:

GoogleSQL

import (
	"context"
	"database/sql"
	"fmt"
	"io"

	_ "github.com/googleapis/go-sql-spanner"
)

func QueryDataWithParameter(ctx context.Context, w io.Writer, databaseName string) error {
	db, err := sql.Open("spanner", databaseName)
	if err != nil {
		return err
	}
	defer db.Close()

	rows, err := db.QueryContext(ctx,
		`SELECT SingerId, FirstName, LastName
		FROM Singers
		WHERE LastName = ?`, "Garcia")
	defer rows.Close()
	if err != nil {
		return err
	}
	for rows.Next() {
		var singerId int64
		var firstName, lastName string
		err = rows.Scan(&singerId, &firstName, &lastName)
		if err != nil {
			return err
		}
		fmt.Fprintf(w, "%v %v %v\n", singerId, firstName, lastName)
	}
	if rows.Err() != nil {
		return rows.Err()
	}
	return rows.Close()
}

PostgreSQL

import (
	"context"
	"database/sql"
	"fmt"
	"io"

	_ "github.com/googleapis/go-sql-spanner"
)

func QueryDataWithParameterPostgreSQL(ctx context.Context, w io.Writer, databaseName string) error {
	db, err := sql.Open("spanner", databaseName)
	if err != nil {
		return err
	}
	defer func() { _ = db.Close() }()

	rows, err := db.QueryContext(ctx,
		`select singer_id, first_name, last_name
		from singers
		where last_name = ?`, "Garcia")
	defer func() { _ = rows.Close() }()
	if err != nil {
		return err
	}
	for rows.Next() {
		var singerId int64
		var firstName, lastName string
		err = rows.Scan(&singerId, &firstName, &lastName)
		if err != nil {
			return err
		}
		_, _ = fmt.Fprintf(w, "%v %v %v\n", singerId, firstName, lastName)
	}
	if rows.Err() != nil {
		return rows.Err()
	}
	return rows.Close()
}

Führen Sie das Beispiel mit dem folgenden Befehl aus:

GoogleSQL

go run getting_started_guide.go querywithparameter projects/PROJECT_ID/instances/test-instance/databases/example-db

PostgreSQL

go run getting_started_guide.go querywithparameterpg projects/PROJECT_ID/instances/test-instance/databases/example-db

Das Ergebnis zeigt Folgendes:

12 Melissa Garcia

Datenbankschema aktualisieren

Beispiel: Sie müssen eine neue Spalte namens MarketingBudget zur Tabelle Albums hinzufügen. Damit einer vorhandenen Tabelle eine neue Spalte hinzugefügt werden kann, muss das Datenbankschema aktualisiert werden. Spanner unterstützt Schemaaktualisierungen für Datenbanken, ohne dass die Traffic-Bereitstellung unterbrochen werden muss. Bei einer Schemaaktualisierung muss die Datenbank nicht offline geschaltet und es müssen keine ganzen Tabellen oder Spalten gesperrt werden. Sie können während der Aktualisierung weiter Daten in die Datenbank schreiben. Weitere Informationen zu unterstützten Schemaaktualisierungen und zur Leistung von Schemaänderungen finden Sie unter Schemaaktualisierungen vornehmen.

Spalte hinzufügen

Sie können eine Spalte über die Befehlszeile mit der Google Cloud CLI oder programmatisch mit dem Spanner-Datenbank-/SQL-Treiber hinzufügen.

Über die Befehlszeile

Verwenden Sie den folgenden Befehl ALTER TABLE, um die neue Spalte zur Tabelle hinzuzufügen:

GoogleSQL

gcloud spanner databases ddl update example-db --instance=test-instance \
    --ddl='ALTER TABLE Albums ADD COLUMN MarketingBudget INT64'

PostgreSQL

gcloud spanner databases ddl update example-db --instance=test-instance \
    --ddl='alter table albums add column marketing_budget bigint'

Hier sollten Sie dies sehen:

Schema updating...done.

Spanner-Datenbank/SQL-Treiber verwenden

Verwenden Sie die Funktion ExecContext, um das Schema zu ändern:

GoogleSQL

import (
	"context"
	"database/sql"
	"fmt"
	"io"

	_ "github.com/googleapis/go-sql-spanner"
)

func AddColumn(ctx context.Context, w io.Writer, databaseName string) error {
	db, err := sql.Open("spanner", databaseName)
	if err != nil {
		return err
	}
	defer db.Close()

	_, err = db.ExecContext(ctx,
		`ALTER TABLE Albums
			ADD COLUMN MarketingBudget INT64`)
	if err != nil {
		return err
	}

	fmt.Fprint(w, "Added MarketingBudget column\n")
	return nil
}

PostgreSQL

import (
	"context"
	"database/sql"
	"fmt"
	"io"

	_ "github.com/googleapis/go-sql-spanner"
)

func AddColumnPostgreSQL(ctx context.Context, w io.Writer, databaseName string) error {
	db, err := sql.Open("spanner", databaseName)
	if err != nil {
		return err
	}
	defer func() { _ = db.Close() }()

	_, err = db.ExecContext(ctx,
		`alter table albums
			add column marketing_budget bigint`)
	if err != nil {
		return err
	}

	_, _ = fmt.Fprint(w, "Added marketing_budget column\n")
	return nil
}

Führen Sie das Beispiel mit dem folgenden Befehl aus:

GoogleSQL

go run getting_started_guide.go addcolumn projects/PROJECT_ID/instances/test-instance/databases/example-db

PostgreSQL

go run getting_started_guide.go addcolumnpg projects/PROJECT_ID/instances/test-instance/databases/example-db

Das Ergebnis zeigt Folgendes:

Added MarketingBudget column.

DDL-Batch ausführen

Wir empfehlen, mehrere Schemaänderungen in einem Batch auszuführen. Verwenden Sie die Befehle START BATCH DDL und RUN BATCH, um einen DDL-Batch auszuführen. Im folgenden Beispiel werden zwei Tabellen in einem Batch erstellt:

GoogleSQL

import (
	"context"
	"database/sql"
	"fmt"
	"io"

	_ "github.com/googleapis/go-sql-spanner"
)

func DdlBatch(ctx context.Context, w io.Writer, databaseName string) error {
	db, err := sql.Open("spanner", databaseName)
	if err != nil {
		return err
	}
	defer db.Close()

	// Executing multiple DDL statements as one batch is
	// more efficient than executing each statement
	// individually.
	conn, err := db.Conn(ctx)
	defer conn.Close()

	if _, err := conn.ExecContext(ctx, "start batch ddl"); err != nil {
		return err
	}
	if _, err := conn.ExecContext(ctx,
		`CREATE TABLE Venues (
			VenueId     INT64 NOT NULL,
			Name        STRING(1024),
			Description JSON,
		) PRIMARY KEY (VenueId)`); err != nil {
		return err
	}
	if _, err := conn.ExecContext(ctx,
		`CREATE TABLE Concerts (
			ConcertId INT64 NOT NULL,
			VenueId   INT64 NOT NULL,
			SingerId  INT64 NOT NULL,
			StartTime TIMESTAMP,
			EndTime   TIMESTAMP,
			CONSTRAINT Fk_Concerts_Venues FOREIGN KEY
				(VenueId) REFERENCES Venues (VenueId),
			CONSTRAINT Fk_Concerts_Singers FOREIGN KEY
				(SingerId) REFERENCES Singers (SingerId),
		) PRIMARY KEY (ConcertId)`); err != nil {
		return err
	}
	// `run batch` sends the DDL statements to Spanner and blocks until
	// all statements have finished executing.
	if _, err := conn.ExecContext(ctx, "run batch"); err != nil {
		return err
	}

	fmt.Fprint(w, "Added Venues and Concerts tables\n")
	return nil
}

PostgreSQL

import (
	"context"
	"database/sql"
	"fmt"
	"io"

	_ "github.com/googleapis/go-sql-spanner"
)

func DdlBatchPostgreSQL(ctx context.Context, w io.Writer, databaseName string) error {
	db, err := sql.Open("spanner", databaseName)
	if err != nil {
		return err
	}
	defer func() { _ = db.Close() }()

	// Executing multiple DDL statements as one batch is
	// more efficient than executing each statement
	// individually.
	conn, err := db.Conn(ctx)
	defer func() { _ = conn.Close() }()

	if _, err := conn.ExecContext(ctx, "start batch ddl"); err != nil {
		return err
	}
	if _, err := conn.ExecContext(ctx,
		`create table venues (
			venue_id    bigint not null primary key,
			name        varchar(1024),
			description jsonb
		)`); err != nil {
		return err
	}
	if _, err := conn.ExecContext(ctx,
		`create table concerts (
			concert_id bigint not null primary key,
			venue_id   bigint not null,
			singer_id  bigint not null,
			start_time timestamptz,
			end_time   timestamptz,
			constraint fk_concerts_venues foreign key
				(venue_id) references venues (venue_id),
			constraint fk_concerts_singers foreign key
				(singer_id) references singers (singer_id)
		)`); err != nil {
		return err
	}
	// `run batch` sends the DDL statements to Spanner and blocks until
	// all statements have finished executing.
	if _, err := conn.ExecContext(ctx, "run batch"); err != nil {
		return err
	}

	_, _ = fmt.Fprint(w, "Added venues and concerts tables\n")
	return nil
}

Führen Sie das Beispiel mit dem folgenden Befehl aus:

GoogleSQL

go run getting_started_guide.go ddlbatch projects/PROJECT_ID/instances/test-instance/databases/example-db

PostgreSQL

go run getting_started_guide.go ddlbatchpg projects/PROJECT_ID/instances/test-instance/databases/example-db

Das Ergebnis zeigt Folgendes:

Added Venues and Concerts tables.

Daten in die neue Spalte schreiben

Mit dem folgenden Code werden Daten in die neue Spalte geschrieben. Er legt für MarketingBudget den Wert 100000 für den Zeilenschlüssel fest, der durch Albums(1, 1) angegeben wird, und er legt 500000 für den Zeilenschlüssel fest, der durch Albums(2, 2) angegeben wird.

GoogleSQL

import (
	"context"
	"database/sql"
	"fmt"
	"io"

	"cloud.google.com/go/spanner"
	spannerdriver "github.com/googleapis/go-sql-spanner"
)

func UpdateDataWithMutations(ctx context.Context, w io.Writer, databaseName string) error {
	db, err := sql.Open("spanner", databaseName)
	if err != nil {
		return err
	}
	defer db.Close()

	// Get a connection so that we can get access to the Spanner specific
	// connection interface SpannerConn.
	conn, err := db.Conn(ctx)
	if err != nil {
		return err
	}
	defer conn.Close()

	cols := []string{"SingerId", "AlbumId", "MarketingBudget"}
	mutations := []*spanner.Mutation{
		spanner.Update("Albums", cols, []interface{}{1, 1, 100000}),
		spanner.Update("Albums", cols, []interface{}{2, 2, 500000}),
	}
	if err := conn.Raw(func(driverConn interface{}) error {
		spannerConn, ok := driverConn.(spannerdriver.SpannerConn)
		if !ok {
			return fmt.Errorf("unexpected driver connection %v, "+
				"expected SpannerConn", driverConn)
		}
		_, err = spannerConn.Apply(ctx, mutations)
		return err
	}); err != nil {
		return err
	}
	fmt.Fprintf(w, "Updated %v albums\n", len(mutations))

	return nil
}

PostgreSQL

import (
	"context"
	"database/sql"
	"fmt"
	"io"

	"cloud.google.com/go/spanner"
	spannerdriver "github.com/googleapis/go-sql-spanner"
)

func UpdateDataWithMutationsPostgreSQL(ctx context.Context, w io.Writer, databaseName string) error {
	db, err := sql.Open("spanner", databaseName)
	if err != nil {
		return err
	}
	defer func() { _ = db.Close() }()

	// Get a connection so that we can get access to the Spanner specific
	// connection interface SpannerConn.
	conn, err := db.Conn(ctx)
	if err != nil {
		return err
	}
	defer func() { _ = conn.Close() }()

	cols := []string{"singer_id", "album_id", "marketing_budget"}
	mutations := []*spanner.Mutation{
		spanner.Update("albums", cols, []interface{}{1, 1, 100000}),
		spanner.Update("albums", cols, []interface{}{2, 2, 500000}),
	}
	if err := conn.Raw(func(driverConn interface{}) error {
		spannerConn, ok := driverConn.(spannerdriver.SpannerConn)
		if !ok {
			return fmt.Errorf("unexpected driver connection %v, "+
				"expected SpannerConn", driverConn)
		}
		_, err = spannerConn.Apply(ctx, mutations)
		return err
	}); err != nil {
		return err
	}
	_, _ = fmt.Fprintf(w, "Updated %v albums\n", len(mutations))

	return nil
}

Führen Sie das Beispiel mit dem folgenden Befehl aus:

GoogleSQL

go run getting_started_guide.go update projects/PROJECT_ID/instances/test-instance/databases/example-db

PostgreSQL

go run getting_started_guide.go updatepg projects/PROJECT_ID/instances/test-instance/databases/example-db

Das Ergebnis zeigt Folgendes:

Updated 2 albums

Sie können auch eine SQL-Abfrage ausführen, um die Werte abzurufen, die Sie gerade geschrieben haben.

Im folgenden Beispiel wird die Funktion QueryContext verwendet, um eine Abfrage auszuführen:

GoogleSQL

import (
	"context"
	"database/sql"
	"fmt"
	"io"

	_ "github.com/googleapis/go-sql-spanner"
)

func QueryNewColumn(ctx context.Context, w io.Writer, databaseName string) error {
	db, err := sql.Open("spanner", databaseName)
	if err != nil {
		return err
	}
	defer db.Close()

	rows, err := db.QueryContext(ctx,
		`SELECT SingerId, AlbumId, MarketingBudget
		FROM Albums
		ORDER BY SingerId, AlbumId`)
	defer rows.Close()
	if err != nil {
		return err
	}
	for rows.Next() {
		var singerId, albumId int64
		var marketingBudget sql.NullInt64
		err = rows.Scan(&singerId, &albumId, &marketingBudget)
		if err != nil {
			return err
		}
		budget := "NULL"
		if marketingBudget.Valid {
			budget = fmt.Sprintf("%v", marketingBudget.Int64)
		}
		fmt.Fprintf(w, "%v %v %v\n", singerId, albumId, budget)
	}
	if rows.Err() != nil {
		return rows.Err()
	}
	return rows.Close()
}

PostgreSQL

import (
	"context"
	"database/sql"
	"fmt"
	"io"

	_ "github.com/googleapis/go-sql-spanner"
)

func QueryNewColumnPostgreSQL(ctx context.Context, w io.Writer, databaseName string) error {
	db, err := sql.Open("spanner", databaseName)
	if err != nil {
		return err
	}
	defer func() { _ = db.Close() }()

	rows, err := db.QueryContext(ctx,
		`select singer_id, album_id, marketing_budget
		from albums
		order by singer_id, album_id`)
	defer func() { _ = rows.Close() }()
	if err != nil {
		return err
	}
	for rows.Next() {
		var singerId, albumId int64
		var marketingBudget sql.NullInt64
		err = rows.Scan(&singerId, &albumId, &marketingBudget)
		if err != nil {
			return err
		}
		budget := "null"
		if marketingBudget.Valid {
			budget = fmt.Sprintf("%v", marketingBudget.Int64)
		}
		_, _ = fmt.Fprintf(w, "%v %v %v\n", singerId, albumId, budget)
	}
	if rows.Err() != nil {
		return rows.Err()
	}
	return rows.Close()
}

Führen Sie den folgenden Befehl aus, um diese Abfrage auszuführen:

GoogleSQL

go run getting_started_guide.go querymarketingbudget projects/PROJECT_ID/instances/test-instance/databases/example-db

PostgreSQL

go run getting_started_guide.go querymarketingbudgetpg projects/PROJECT_ID/instances/test-instance/databases/example-db

Hier sollten Sie dies sehen:

1 1 100000
1 2 null
2 1 null
2 2 500000
2 3 null

Daten aktualisieren

Sie können Daten mit DML in einer Lese-Schreib-Transaktion aktualisieren.

Rufen Sie DB.BeginTx auf, um Lese-/Schreibtransaktionen in database/sql auszuführen.

GoogleSQL

import (
	"context"
	"database/sql"
	"fmt"
	"io"

	_ "github.com/googleapis/go-sql-spanner"
)

func WriteWithTransactionUsingDml(ctx context.Context, w io.Writer, databaseName string) error {
	db, err := sql.Open("spanner", databaseName)
	if err != nil {
		return err
	}
	defer db.Close()

	// Transfer marketing budget from one album to another. We do it in a
	// transaction to ensure that the transfer is atomic.
	tx, err := db.BeginTx(ctx, &sql.TxOptions{})
	if err != nil {
		return err
	}
	// The Spanner database/sql driver supports both positional and named
	// query parameters. This query uses named query parameters.
	const selectSql = "SELECT MarketingBudget " +
		"FROM Albums " +
		"WHERE SingerId = @singerId and AlbumId = @albumId"
	// Get the marketing_budget of singer 2 / album 2.
	row := tx.QueryRowContext(ctx, selectSql,
		sql.Named("singerId", 2), sql.Named("albumId", 2))
	var budget2 int64
	if err := row.Scan(&budget2); err != nil {
		tx.Rollback()
		return err
	}
	const transfer = 20000
	// The transaction will only be committed if this condition still holds
	// at the time of commit. Otherwise, the transaction will be aborted.
	if budget2 >= transfer {
		// Get the marketing_budget of singer 1 / album 1.
		row := tx.QueryRowContext(ctx, selectSql,
			sql.Named("singerId", 1), sql.Named("albumId", 1))
		var budget1 int64
		if err := row.Scan(&budget1); err != nil {
			tx.Rollback()
			return err
		}
		// Transfer part of the marketing budget of Album 2 to Album 1.
		budget1 += transfer
		budget2 -= transfer
		const updateSql = "UPDATE Albums " +
			"SET MarketingBudget = @budget " +
			"WHERE SingerId = @singerId and AlbumId = @albumId"
		// Start a DML batch and execute it as part of the current transaction.
		if _, err := tx.ExecContext(ctx, "start batch dml"); err != nil {
			tx.Rollback()
			return err
		}
		if _, err := tx.ExecContext(ctx, updateSql,
			sql.Named("singerId", 1),
			sql.Named("albumId", 1),
			sql.Named("budget", budget1)); err != nil {
			_, _ = tx.ExecContext(ctx, "abort batch")
			tx.Rollback()
			return err
		}
		if _, err := tx.ExecContext(ctx, updateSql,
			sql.Named("singerId", 2),
			sql.Named("albumId", 2),
			sql.Named("budget", budget2)); err != nil {
			_, _ = tx.ExecContext(ctx, "abort batch")
			tx.Rollback()
			return err
		}
		// `run batch` sends the DML statements to Spanner.
		// The result contains the total affected rows across the entire batch.
		result, err := tx.ExecContext(ctx, "run batch")
		if err != nil {
			tx.Rollback()
			return err
		}
		if affected, err := result.RowsAffected(); err != nil {
			tx.Rollback()
			return err
		} else if affected != 2 {
			// The batch should update 2 rows.
			tx.Rollback()
			return fmt.Errorf("unexpected number of rows affected: %v", affected)
		}
	}
	// Commit the current transaction.
	if err := tx.Commit(); err != nil {
		return err
	}

	fmt.Fprintln(w, "Transferred marketing budget from Album 2 to Album 1")

	return nil
}

PostgreSQL

import (
	"context"
	"database/sql"
	"fmt"
	"io"

	_ "github.com/googleapis/go-sql-spanner"
)

func WriteWithTransactionUsingDmlPostgreSQL(ctx context.Context, w io.Writer, databaseName string) error {
	db, err := sql.Open("spanner", databaseName)
	if err != nil {
		return err
	}
	defer func() { _ = db.Close() }()

	// Transfer marketing budget from one album to another. We do it in a
	// transaction to ensure that the transfer is atomic.
	tx, err := db.BeginTx(ctx, &sql.TxOptions{})
	if err != nil {
		return err
	}
	const selectSql = "select marketing_budget " +
		"from albums " +
		"where singer_id = $1 and album_id = $2"
	// Get the marketing_budget of singer 2 / album 2.
	row := tx.QueryRowContext(ctx, selectSql, 2, 2)
	var budget2 int64
	if err := row.Scan(&budget2); err != nil {
		_ = tx.Rollback()
		return err
	}
	const transfer = 20000
	// The transaction will only be committed if this condition still holds
	// at the time of commit. Otherwise, the transaction will be aborted.
	if budget2 >= transfer {
		// Get the marketing_budget of singer 1 / album 1.
		row := tx.QueryRowContext(ctx, selectSql, 1, 1)
		var budget1 int64
		if err := row.Scan(&budget1); err != nil {
			_ = tx.Rollback()
			return err
		}
		// Transfer part of the marketing budget of Album 2 to Album 1.
		budget1 += transfer
		budget2 -= transfer
		const updateSql = "update albums " +
			"set marketing_budget = $1 " +
			"where singer_id = $2 and album_id = $3"
		// Start a DML batch and execute it as part of the current transaction.
		if _, err := tx.ExecContext(ctx, "start batch dml"); err != nil {
			_ = tx.Rollback()
			return err
		}
		if _, err := tx.ExecContext(ctx, updateSql, budget1, 1, 1); err != nil {
			_, _ = tx.ExecContext(ctx, "abort batch")
			_ = tx.Rollback()
			return err
		}
		if _, err := tx.ExecContext(ctx, updateSql, budget2, 2, 2); err != nil {
			_, _ = tx.ExecContext(ctx, "abort batch")
			_ = tx.Rollback()
			return err
		}
		// `run batch` sends the DML statements to Spanner.
		// The result contains the total affected rows across the entire batch.
		result, err := tx.ExecContext(ctx, "run batch")
		if err != nil {
			_ = tx.Rollback()
			return err
		}
		if affected, err := result.RowsAffected(); err != nil {
			_ = tx.Rollback()
			return err
		} else if affected != 2 {
			// The batch should update 2 rows.
			_ = tx.Rollback()
			return fmt.Errorf("unexpected number of rows affected: %v", affected)
		}
	}
	// Commit the current transaction.
	if err := tx.Commit(); err != nil {
		return err
	}

	_, _ = fmt.Fprintln(w, "Transferred marketing budget from Album 2 to Album 1")

	return nil
}

Führen Sie das Beispiel mit dem folgenden Befehl aus:

GoogleSQL

go run getting_started_guide.go writewithtransactionusingdml projects/PROJECT_ID/instances/test-instance/databases/example-db

PostgreSQL

go run getting_started_guide.go writewithtransactionusingdmlpg projects/PROJECT_ID/instances/test-instance/databases/example-db

Transaktions-Tags und Anfrage-Tags

Verwenden Sie Transaktions- und Anfrage-Tags, um Fehler bei Transaktionen und Abfragen in Spanner zu beheben. Sie können zusätzliche Transaktionsoptionen an die Funktion spannerdriver.BeginReadWriteTransaction übergeben.

Verwenden Sie spannerdriver.ExecOptions, um zusätzliche Abfrageoptionen für eine SQL-Anweisung zu übergeben. Beispiel:

GoogleSQL

import (
	"context"
	"database/sql"
	"fmt"
	"io"

	"cloud.google.com/go/spanner"
	spannerdriver "github.com/googleapis/go-sql-spanner"
)

func Tags(ctx context.Context, w io.Writer, databaseName string) error {
	db, err := sql.Open("spanner", databaseName)
	if err != nil {
		return err
	}
	defer db.Close()

	// Use the spannerdriver.BeginReadWriteTransaction function
	// to specify specific Spanner options, such as transaction tags.
	tx, err := spannerdriver.BeginReadWriteTransaction(ctx, db,
		spannerdriver.ReadWriteTransactionOptions{
			TransactionOptions: spanner.TransactionOptions{
				TransactionTag: "example-tx-tag",
			},
		})
	if err != nil {
		return err
	}

	// Pass in an argument of type spannerdriver.ExecOptions to supply
	// additional options for a statement.
	row := tx.QueryRowContext(ctx, "SELECT MarketingBudget "+
		"FROM Albums "+
		"WHERE SingerId=? and AlbumId=?",
		spannerdriver.ExecOptions{
			QueryOptions: spanner.QueryOptions{RequestTag: "query-marketing-budget"},
		}, 1, 1)
	var budget int64
	if err := row.Scan(&budget); err != nil {
		tx.Rollback()
		return err
	}

	// Reduce the marketing budget by 10% if it is more than 1,000.
	if budget > 1000 {
		budget = int64(float64(budget) - float64(budget)*0.1)
		if _, err := tx.ExecContext(ctx,
			`UPDATE Albums SET MarketingBudget=@budget 
               WHERE SingerId=@singerId AND AlbumId=@albumId`,
			spannerdriver.ExecOptions{
				QueryOptions: spanner.QueryOptions{RequestTag: "reduce-marketing-budget"},
			},
			sql.Named("budget", budget),
			sql.Named("singerId", 1),
			sql.Named("albumId", 1)); err != nil {
			tx.Rollback()
			return err
		}
	}
	// Commit the current transaction.
	if err := tx.Commit(); err != nil {
		return err
	}
	fmt.Fprintln(w, "Reduced marketing budget")

	return nil
}

PostgreSQL

import (
	"context"
	"database/sql"
	"fmt"
	"io"

	"cloud.google.com/go/spanner"
	spannerdriver "github.com/googleapis/go-sql-spanner"
)

func TagsPostgreSQL(ctx context.Context, w io.Writer, databaseName string) error {
	db, err := sql.Open("spanner", databaseName)
	if err != nil {
		return err
	}
	defer func() { _ = db.Close() }()

	// Use the spannerdriver.BeginReadWriteTransaction function
	// to specify specific Spanner options, such as transaction tags.
	tx, err := spannerdriver.BeginReadWriteTransaction(ctx, db,
		spannerdriver.ReadWriteTransactionOptions{
			TransactionOptions: spanner.TransactionOptions{
				TransactionTag: "example-tx-tag",
			},
		})
	if err != nil {
		return err
	}

	// Pass in an argument of type spannerdriver.ExecOptions to supply
	// additional options for a statement.
	row := tx.QueryRowContext(ctx, "select marketing_budget "+
		"from albums "+
		"where singer_id=? and album_id=?",
		spannerdriver.ExecOptions{
			QueryOptions: spanner.QueryOptions{RequestTag: "query-marketing-budget"},
		}, 1, 1)
	var budget int64
	if err := row.Scan(&budget); err != nil {
		_ = tx.Rollback()
		return err
	}

	// Reduce the marketing budget by 10% if it is more than 1,000.
	if budget > 1000 {
		budget = int64(float64(budget) - float64(budget)*0.1)
		if _, err := tx.ExecContext(ctx,
			`update albums set marketing_budget=$1 
               where singer_id=$2 and album_id=$3`,
			spannerdriver.ExecOptions{
				QueryOptions: spanner.QueryOptions{RequestTag: "reduce-marketing-budget"},
			}, budget, 1, 1); err != nil {
			_ = tx.Rollback()
			return err
		}
	}
	// Commit the current transaction.
	if err := tx.Commit(); err != nil {
		return err
	}
	_, _ = fmt.Fprintln(w, "Reduced marketing budget")

	return nil
}

Führen Sie das Beispiel mit dem folgenden Befehl aus:

GoogleSQL

go run getting_started_guide.go tags projects/PROJECT_ID/instances/test-instance/databases/example-db

PostgreSQL

go run getting_started_guide.go tagspg projects/PROJECT_ID/instances/test-instance/databases/example-db

Daten mit schreibgeschützten Transaktionen abrufen

Angenommen, Sie möchten mehr als einen Lesevorgang mit demselben Zeitstempel ausführen. Bei schreibgeschützten Transaktionen wird ein gleichbleibendes Präfix des Commit-Verlaufs der Transaktionen beibehalten, damit die Anwendung immer konsistente Daten erhält. Setzen Sie das Feld TxOptions.ReadOnly auf true, um eine schreibgeschützte Transaktion auszuführen.

So werden eine Abfrage und ein Lesevorgang in derselben schreibgeschützten Transaktion ausgeführt:

GoogleSQL

import (
	"context"
	"database/sql"
	"fmt"
	"io"

	_ "github.com/googleapis/go-sql-spanner"
)

func ReadOnlyTransaction(ctx context.Context, w io.Writer, databaseName string) error {
	db, err := sql.Open("spanner", databaseName)
	if err != nil {
		return err
	}
	defer db.Close()

	// Start a read-only transaction by supplying additional transaction options.
	tx, err := db.BeginTx(ctx, &sql.TxOptions{ReadOnly: true})

	albumsOrderedById, err := tx.QueryContext(ctx,
		`SELECT SingerId, AlbumId, AlbumTitle
		FROM Albums
		ORDER BY SingerId, AlbumId`)
	defer albumsOrderedById.Close()
	if err != nil {
		return err
	}
	for albumsOrderedById.Next() {
		var singerId, albumId int64
		var title string
		err = albumsOrderedById.Scan(&singerId, &albumId, &title)
		if err != nil {
			return err
		}
		fmt.Fprintf(w, "%v %v %v\n", singerId, albumId, title)
	}

	albumsOrderedTitle, err := tx.QueryContext(ctx,
		`SELECT SingerId, AlbumId, AlbumTitle
		FROM Albums
		ORDER BY AlbumTitle`)
	defer albumsOrderedTitle.Close()
	if err != nil {
		return err
	}
	for albumsOrderedTitle.Next() {
		var singerId, albumId int64
		var title string
		err = albumsOrderedTitle.Scan(&singerId, &albumId, &title)
		if err != nil {
			return err
		}
		fmt.Fprintf(w, "%v %v %v\n", singerId, albumId, title)
	}

	// End the read-only transaction by calling Commit.
	return tx.Commit()
}

PostgreSQL

import (
	"context"
	"database/sql"
	"fmt"
	"io"

	_ "github.com/googleapis/go-sql-spanner"
)

func ReadOnlyTransactionPostgreSQL(ctx context.Context, w io.Writer, databaseName string) error {
	db, err := sql.Open("spanner", databaseName)
	if err != nil {
		return err
	}
	defer func() { _ = db.Close() }()

	// Start a read-only transaction by supplying additional transaction options.
	tx, err := db.BeginTx(ctx, &sql.TxOptions{ReadOnly: true})
	if err != nil {
		return err
	}

	albumsOrderedById, err := tx.QueryContext(ctx,
		`select singer_id, album_id, album_title
		from albums
		order by singer_id, album_id`)
	defer func() { _ = albumsOrderedById.Close() }()
	if err != nil {
		return err
	}
	for albumsOrderedById.Next() {
		var singerId, albumId int64
		var title string
		err = albumsOrderedById.Scan(&singerId, &albumId, &title)
		if err != nil {
			return err
		}
		_, _ = fmt.Fprintf(w, "%v %v %v\n", singerId, albumId, title)
	}

	albumsOrderedTitle, err := tx.QueryContext(ctx,
		`select singer_id, album_id, album_title
		from albums
		order by album_title`)
	defer func() { _ = albumsOrderedTitle.Close() }()
	if err != nil {
		return err
	}
	for albumsOrderedTitle.Next() {
		var singerId, albumId int64
		var title string
		err = albumsOrderedTitle.Scan(&singerId, &albumId, &title)
		if err != nil {
			return err
		}
		_, _ = fmt.Fprintf(w, "%v %v %v\n", singerId, albumId, title)
	}

	// End the read-only transaction by calling Commit.
	return tx.Commit()
}

Führen Sie das Beispiel mit dem folgenden Befehl aus:

GoogleSQL

go run getting_started_guide.go readonlytransaction projects/PROJECT_ID/instances/test-instance/databases/example-db

PostgreSQL

go run getting_started_guide.go readonlytransactionpg projects/PROJECT_ID/instances/test-instance/databases/example-db

Das Ergebnis zeigt Folgendes:

    1 1 Total Junk
    1 2 Go, Go, Go
    2 1 Green
    2 2 Forever Hold Your Peace
    2 3 Terrified
    2 2 Forever Hold Your Peace
    1 2 Go, Go, Go
    2 1 Green
    2 3 Terrified
    1 1 Total Junk

Partitionierte Abfragen und Data Boost

Die partitionQuery API teilt eine Abfrage in kleinere Teile oder Partitionen auf und verwendet mehrere Maschinen, um die Partitionen parallel abzurufen. Jede Partition wird durch ein Partitionstoken identifiziert. Die partitionQuery API hat eine höhere Latenz als die Standard-query API, da sie nur für Bulk-Vorgänge wie das Exportieren oder Scannen der gesamten Datenbank vorgesehen ist.

Mit Data Boost können Sie Analyseabfragen und Datenexporte nahezu ohne Auswirkungen auf vorhandene Arbeitslasten auf der bereitgestellten Spanner-Instanz ausführen. Data Boost unterstützt nur partitionierte Abfragen.

Im folgenden Beispiel wird gezeigt, wie Sie eine partitionierte Abfrage mit Data Boost mit dem database/sql-Treiber ausführen:

GoogleSQL

import (
	"context"
	"database/sql"
	"fmt"
	"io"
	"slices"

	"cloud.google.com/go/spanner"
	spannerdriver "github.com/googleapis/go-sql-spanner"
)

func DataBoost(ctx context.Context, w io.Writer, databaseName string) error {
	db, err := sql.Open("spanner", databaseName)
	if err != nil {
		return err
	}
	defer db.Close()

	// Run a partitioned query that uses Data Boost.
	rows, err := db.QueryContext(ctx,
		"SELECT SingerId, FirstName, LastName from Singers",
		spannerdriver.ExecOptions{
			PartitionedQueryOptions: spannerdriver.PartitionedQueryOptions{
				// AutoPartitionQuery instructs the Spanner database/sql driver to
				// automatically partition the query and execute each partition in parallel.
				// The rows are returned as one result set in undefined order.
				AutoPartitionQuery: true,
			},
			QueryOptions: spanner.QueryOptions{
				// Set DataBoostEnabled to true to enable DataBoost.
				// See https://cloud.google.com/spanner/docs/databoost/databoost-overview
				// for more information.
				DataBoostEnabled: true,
			},
		})
	defer rows.Close()
	if err != nil {
		return err
	}
	type Singer struct {
		SingerId  int64
		FirstName string
		LastName  string
	}
	var singers []Singer
	for rows.Next() {
		var singer Singer
		err = rows.Scan(&singer.SingerId, &singer.FirstName, &singer.LastName)
		if err != nil {
			return err
		}
		singers = append(singers, singer)
	}
	// Queries that use the AutoPartition option return rows in undefined order,
	// so we need to sort them in memory to guarantee the output order.
	slices.SortFunc(singers, func(a, b Singer) int {
		return int(a.SingerId - b.SingerId)
	})
	for _, s := range singers {
		fmt.Fprintf(w, "%v %v %v\n", s.SingerId, s.FirstName, s.LastName)
	}

	return nil
}

PostgreSQL

import (
	"context"
	"database/sql"
	"fmt"
	"io"
	"slices"

	"cloud.google.com/go/spanner"
	spannerdriver "github.com/googleapis/go-sql-spanner"
)

func DataBoostPostgreSQL(ctx context.Context, w io.Writer, databaseName string) error {
	db, err := sql.Open("spanner", databaseName)
	if err != nil {
		return err
	}
	defer func() { _ = db.Close() }()

	// Run a partitioned query that uses Data Boost.
	rows, err := db.QueryContext(ctx,
		"select singer_id, first_name, last_name from singers",
		spannerdriver.ExecOptions{
			PartitionedQueryOptions: spannerdriver.PartitionedQueryOptions{
				// AutoPartitionQuery instructs the Spanner database/sql driver to
				// automatically partition the query and execute each partition in parallel.
				// The rows are returned as one result set in undefined order.
				AutoPartitionQuery: true,
			},
			QueryOptions: spanner.QueryOptions{
				// Set DataBoostEnabled to true to enable DataBoost.
				// See https://cloud.google.com/spanner/docs/databoost/databoost-overview
				// for more information.
				DataBoostEnabled: true,
			},
		})
	defer func() { _ = rows.Close() }()
	if err != nil {
		return err
	}
	type Singer struct {
		SingerId  int64
		FirstName string
		LastName  string
	}
	var singers []Singer
	for rows.Next() {
		var singer Singer
		err = rows.Scan(&singer.SingerId, &singer.FirstName, &singer.LastName)
		if err != nil {
			return err
		}
		singers = append(singers, singer)
	}
	// Queries that use the AutoPartition option return rows in undefined order,
	// so we need to sort them in memory to guarantee the output order.
	slices.SortFunc(singers, func(a, b Singer) int {
		return int(a.SingerId - b.SingerId)
	})
	for _, s := range singers {
		_, _ = fmt.Fprintf(w, "%v %v %v\n", s.SingerId, s.FirstName, s.LastName)
	}

	return nil
}

Führen Sie das Beispiel mit dem folgenden Befehl aus:

GoogleSQL

go run getting_started_guide.go databoost projects/PROJECT_ID/instances/test-instance/databases/example-db

PostgreSQL

go run getting_started_guide.go databoostpg projects/PROJECT_ID/instances/test-instance/databases/example-db

Partitionierte DML

Die partitionierte Datenbearbeitungssprache (DML) ist für die folgenden Arten von Bulk-Aktualisierungen und -Löschvorgängen konzipiert:

• Regelmäßige und automatische Speicherbereinigungsvorgänge.
• Backfilling neuer Spalten mit Standardwerten.

GoogleSQL

import (
	"context"
	"database/sql"
	"fmt"
	"io"

	_ "github.com/googleapis/go-sql-spanner"
)

func PartitionedDml(ctx context.Context, w io.Writer, databaseName string) error {
	db, err := sql.Open("spanner", databaseName)
	if err != nil {
		return err
	}
	defer db.Close()

	conn, err := db.Conn(ctx)
	if err != nil {
		return err
	}
	// Enable Partitioned DML on this connection.
	if _, err := conn.ExecContext(ctx, "SET AUTOCOMMIT_DML_MODE='PARTITIONED_NON_ATOMIC'"); err != nil {
		return fmt.Errorf("failed to change DML mode to Partitioned_Non_Atomic: %v", err)
	}
	// Back-fill a default value for the MarketingBudget column.
	res, err := conn.ExecContext(ctx, "UPDATE Albums SET MarketingBudget=0 WHERE MarketingBudget IS NULL")
	if err != nil {
		return err
	}
	affected, err := res.RowsAffected()
	if err != nil {
		return fmt.Errorf("failed to get affected rows: %v", err)
	}

	// Partitioned DML returns the minimum number of records that were affected.
	fmt.Fprintf(w, "Updated at least %v albums\n", affected)

	// Closing the connection will return it to the connection pool. The DML mode will automatically be reset to the
	// default TRANSACTIONAL mode when the connection is returned to the pool, so we do not need to change it back
	// manually.
	_ = conn.Close()

	return nil
}

PostgreSQL

import (
	"context"
	"database/sql"
	"fmt"
	"io"

	_ "github.com/googleapis/go-sql-spanner"
)

func PartitionedDmlPostgreSQL(ctx context.Context, w io.Writer, databaseName string) error {
	db, err := sql.Open("spanner", databaseName)
	if err != nil {
		return err
	}
	defer func() { _ = db.Close() }()

	conn, err := db.Conn(ctx)
	if err != nil {
		return err
	}
	// Enable Partitioned DML on this connection.
	if _, err := conn.ExecContext(ctx, "set autocommit_dml_mode='partitioned_non_atomic'"); err != nil {
		return fmt.Errorf("failed to change DML mode to Partitioned_Non_Atomic: %v", err)
	}
	// Back-fill a default value for the marketing_budget column.
	res, err := conn.ExecContext(ctx, "update albums set marketing_budget=0 where marketing_budget is null")
	if err != nil {
		return err
	}
	affected, err := res.RowsAffected()
	if err != nil {
		return fmt.Errorf("failed to get affected rows: %v", err)
	}

	// Partitioned DML returns the minimum number of records that were affected.
	_, _ = fmt.Fprintf(w, "Updated at least %v albums\n", affected)

	// Closing the connection will return it to the connection pool. The DML mode will automatically be reset to the
	// default TRANSACTIONAL mode when the connection is returned to the pool, so we do not need to change it back
	// manually.
	_ = conn.Close()

	return nil
}

Führen Sie das Beispiel mit dem folgenden Befehl aus:

GoogleSQL

go run getting_started_guide.go pdml projects/PROJECT_ID/instances/test-instance/databases/example-db

PostgreSQL

go run getting_started_guide.go pdmlpg projects/PROJECT_ID/instances/test-instance/databases/example-db

Bereinigen

Löschen Sie die Datenbank und die erstellte Instanz, um zu vermeiden, dass Ihrem Cloud-Rechnungskonto die in dieser Anleitung verwendeten Ressourcen in Rechnung gestellt werden.

Datenbank löschen

Wenn Sie eine Instanz löschen, werden alle darin enthaltenen Datenbanken automatisch gelöscht. In diesem Schritt wird gezeigt, wie eine Datenbank gelöscht wird, ohne eine Instanz zu löschen (dabei fallen weiterhin Gebühren für die Instanz an).

Über die Befehlszeile

gcloud spanner databases delete example-db --instance=test-instance

Google Cloud Console verwenden

1. Rufen Sie in der Google Cloud Console die Seite Spanner-Instanzen auf.

   Zur Seite "VM-Instanzen"

2. Klicken Sie auf die Instanz.

3. Klicken Sie auf die Datenbank, die Sie löschen möchten.

4. Klicken Sie auf der Seite Datenbankdetails auf Löschen.

5. Bestätigen Sie, dass die Datenbank gelöscht werden soll, und klicken Sie auf Löschen.

Instanz löschen

Beim Löschen einer Instanz werden alle Datenbanken, die in der Instanz erstellt wurden, automatisch gelöscht.

Über die Befehlszeile

gcloud spanner instances delete test-instance

Google Cloud Console verwenden

1. Rufen Sie in der Google Cloud Console die Seite Spanner-Instanzen auf.

   Zur Seite "VM-Instanzen"

2. Klicken Sie auf die Instanz.

3. Klicken Sie auf Löschen.

4. Bestätigen Sie, dass die Instanz gelöscht werden soll, und klicken Sie auf Löschen.

Nächste Schritte

• Mit einer VM-Instanz auf Cloud Spanner zugreifen

• Weitere Informationen zu Anmeldedaten für die Autorisierung und Authentifizierung finden Sie unter Mithilfe von Clientbibliotheken bei Cloud-Diensten authentifizieren.

• Weitere Informationen zu den Best Practices für das Schemadesign in Spanner.