Datenbank über die gcloud CLI erstellen und abfragen

Lernziele

In dieser Anleitung führen Sie die folgenden Schritte mit dem gcloud aus.

• Spanner-Instanz, -Datenbank und -Schema erstellen
• Daten in die Datenbank schreiben und SQL-Abfragen ausführen
• Datenbank und Instanz durch Löschen bereinigen

Die vollständige gcloud spanner-Referenz finden Sie unter gcloud spanner.

Hinweis: Informationen zu Spanner mit einer 90-tägigen kostenlosen Testinstanz finden Sie unter Kostenlose Spanner-Testinstanz erstellen.

Preise

In dieser Anleitung wird Spanner verwendet, eine kostenpflichtige Komponente von Google Cloud. Informationen zu den Kosten für die Verwendung von Spanner finden Sie unter Preise.

Hinweise

1. Führen Sie die unter gcloud CLI installieren und Cloud Spanner API einrichten beschriebenen Schritte aus. Darin werden das Erstellen und Festlegen eines Google Cloud-Standardprojekts, das Aktivieren der Abrechnung, das Aktivieren der Cloud Spanner API und das Einrichten von OAuth 2.0 zum Abrufen von Authentifizierungsanmeldedaten für die Verwendung der Cloud Spanner API beschrieben.

Sie müssen insbesondere gcloud auth application-default login ausführen, um Ihre lokale Entwicklungsumgebung mit Authentifizierungsanmeldedaten einzurichten.

Standardprojekt festlegen

Legen Sie, falls noch nicht geschehen, die ID eines Google Cloud-Projekts als Standardprojekt für die Google Cloud CLI fest:

gcloud config set project PROJECT_ID

Wenn Sie das Standardprojekt nicht festlegen, müssen Sie --project PROJECT_ID an jeden der folgenden Befehle als erstes Argument an gcloud spanner übergeben. Beispiel:

gcloud spanner --project=PROJECT_ID instance-configs list

Instanzen

Wenn Sie Spanner zum ersten Mal verwenden, müssen Sie eine Instanz erstellen. Dabei handelt es sich um eine Zuweisung von Ressourcen, die von Spanner-Datenbanken verwendet werden. Wenn Sie eine Instanz erstellen, legen Sie fest, wo die Daten gespeichert und wie viel Rechenkapazität die Instanz hat.

Instanzen und Instanzkonfigurationen

Zum Erstellen einer Instanz müssen Sie eine Instanzkonfiguration auswählen, die wie eine Vorlage für Ihre Instanz ist und die geografische Platzierung und Replikation Ihrer Spanner-Daten definiert.

Instanzkonfigurationen auflisten

Wenn Sie eine Instanz erstellen, geben Sie eine Instanzkonfiguration an, mit der die geografische Platzierung und Replikation der Datenbanken in der Instanz definiert wird. Sie können eine regionale Konfiguration wählen, die Daten in einer Region speichert, oder eine multiregionale Konfiguration, die Daten über mehrere Regionen verteilt. Weitere Informationen dazu finden Sie unter Instanzen.

So zeigen Sie die Instanzkonfigurationen an, die für das Projekt verfügbar sind:

gcloud spanner instance-configs list

Sie sollten eine Liste mit regionalen sowie multiregionalen Konfigurationen sehen.

Regionale Konfigurationen verteilen Daten in einer einzelnen Region, während multiregionale Konfigurationen Daten geografisch über mehrere Regionen verteilen. Weitere Informationen hierzu finden Sie im Abschnitt Instanzen.

Instanz erstellen

So erstellen Sie eine Instanz namens test-instance mit dem Anzeigenamen My Instance und der regionalen Instanzkonfiguration regional-us-central1 mit 1 Knoten:

gcloud spanner instances create test-instance --config=regional-us-central1 \
    --description="My Instance" --nodes=1

Im obigen Befehl wird der Instanzname auf test-instance und --description auf den Anzeigenamen der Instanz festgelegt. Beide Werte müssen innerhalb eines Google Cloud Platform-Projekts einmalig sein.

Hinweis: Verwenden Sie die Instanz-ID und nicht den Anzeigenamen, wenn Sie in gcloud spanner-Befehlen auf eine Instanz verweisen.

Standardinstanz festlegen

Sie können die Standardinstanz festlegen, die Spanner verwendet, wenn Sie im Befehl keine Instanz angegeben haben. So legen Sie die Standardinstanz fest:

gcloud config set spanner/instance test-instance

Datenbank erstellen

Erstellen Sie eine Datenbank mit dem Namen example-db. Der Datenbankdialekt ist standardmäßig auf GoogleSQL eingestellt.

GoogleSQL

gcloud spanner databases create example-db

PostgreSQL

gcloud spanner databases create example-db --database-dialect=POSTGRESQL

Schema aktualisieren

Verwenden Sie die Datendefinitionssprache (DDL) von Spanner, um Tabellen zu erstellen, zu ändern oder zu löschen und Indexe zu erstellen oder zu löschen.

Lassen Sie uns zwei Tabellen erstellen:

GoogleSQL

gcloud spanner databases ddl update example-db \
--ddl='CREATE TABLE Singers ( SingerId INT64 NOT NULL, FirstName STRING(1024), LastName STRING(1024), SingerInfo BYTES(MAX) ) PRIMARY KEY (SingerId)'

gcloud spanner databases ddl update example-db \
--ddl='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'

PostgreSQL

gcloud spanner databases ddl update example-db \
--ddl='CREATE TABLE Singers ( SingerId bigint NOT NULL, FirstName varchar(1024), LastName varchar(1024), SingerInfo bytea, PRIMARY KEY (SingerId) )'

gcloud spanner databases ddl update example-db \
--ddl='CREATE TABLE Albums ( SingerId bigint NOT NULL, AlbumId bigint NOT NULL, AlbumTitle varchar, PRIMARY KEY (SingerId, AlbumId) ) INTERLEAVE IN PARENT Singers ON DELETE CASCADE'

Mit gcloud spanner operations describe können Sie den Fortschritt des Vorgangs prüfen. Für diesen Befehl ist die Vorgangs-ID erforderlich.

Rufen Sie die Vorgangs-ID ab:

gcloud spanner operations list --instance="test-instance" \
--database=DATABASE-NAME --type=DATABASE_UPDATE_DDL

Ersetzen Sie DATABASE-NAME durch den Namen der Datenbank.

Führen Sie gcloud spanner operations describe aus.

gcloud spanner operations describe \
  --instance="test-instance" \
  --database="example-db" \
  projects/PROJECT-NAME/instances/test-instance/databases/example-db/operations/OPERATION-ID

Ersetzen Sie Folgendes:

• PROJECT-NAME: Der Projektname.
• OPERATION-ID: Die Vorgangs-ID des Vorgangs, den Sie prüfen möchten.

Die Ausgabe sieht dann ungefähr so aus:

done: true
metadata:
...
progress:
- endTime: '2022-03-01T00:28:06.691403Z'
  progressPercent: 100
  startTime: '2022-03-01T00:28:04.221401Z'
- endTime: '2022-03-01T00:28:17.624588Z'
  startTime: '2022-03-01T00:28:06.691403Z'
  progressPercent: 100
...

Daten schreiben

Fügen Sie nun einige Beispieldaten zur Datenbank hinzu:

GoogleSQL

gcloud spanner rows insert --database=example-db \
  --table=Singers \
  --data=SingerId=1,FirstName=Marc,LastName=Richards

gcloud spanner rows insert --database=example-db \
  --table=Singers \
  --data=SingerId=2,FirstName=Catalina,LastName=Smith

gcloud spanner rows insert --database=example-db \
  --table=Singers \
  --data=SingerId=3,FirstName=Alice,LastName=Trentor

gcloud spanner rows insert --database=example-db \
  --table=Albums \
  --data=SingerId=1,AlbumId=1,AlbumTitle="Total Junk"

gcloud spanner rows insert --database=example-db \
  --table=Albums \
  --data=SingerId=2,AlbumId=1,AlbumTitle="Green"

gcloud spanner rows insert --database=example-db \
  --table=Albums \
  --data=^:^SingerId=2:AlbumId=2:AlbumTitle="Go, Go, Go"

Standardmäßig werden Elemente in Listen durch Kommas getrennt. Im letzten Einfügebefehl haben wir einen Doppelpunkt (^:^) als Trennzeichen angegeben, damit wir im Albumtitel ein Komma verwenden konnten.

PostgreSQL

Hinweis: Es gibt ein bekanntes Problem, bei dem die gcloud CLI keine Tabellennamen abrufen kann, wenn Mutationen zum Schreiben von Daten in eine PostgreSQL-Datenbank verwendet werden. Daher müssen Sie zum Einfügen von Daten DML verwenden.

gcloud spanner databases execute-sql example-db \
  --sql="INSERT INTO Singers (SingerId, FirstName, LastName) VALUES (1, 'Marc', 'Richards')"

gcloud spanner databases execute-sql example-db \
  --sql="INSERT INTO Singers (SingerId, FirstName, LastName) VALUES (2, 'Catalina', 'Smith')"

gcloud spanner databases execute-sql example-db   \
  --sql="INSERT INTO Singers (SingerId, FirstName, LastName) VALUES (3, 'Alice', 'Trentor')"

gcloud spanner databases execute-sql example-db   \
  --sql="INSERT INTO Albums (SingerId, AlbumId, AlbumTitle) VALUES (1, 1, 'Total Junk')"

gcloud spanner databases execute-sql example-db   \
  --sql="INSERT INTO Albums (SingerId, AlbumId, AlbumTitle) VALUES (2, 1, 'Green')"

gcloud spanner databases execute-sql example-db   \
  --sql="INSERT INTO Albums (SingerId, AlbumId, AlbumTitle) VALUES (2, 2, 'Go, Go, Go')"

Daten mit SQL abfragen

Führen Sie eine Abfrage in der Befehlszeile aus:

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

Die SQL-Referenz für Spanner finden Sie unter Abfragesyntax für GoogleSQL oder Abfragesyntax für PostgreSQL.

Eine Liste der Flags, die Sie mit dem Befehl execute-sql verwenden können, finden Sie unter gcloud spanner databases execute-sql.

Bereinigen

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

Datenbank löschen

So löschen Sie eine vorhandene Instanz:

gcloud spanner databases delete example-db

Instanz löschen

So löschen Sie eine vorhandene Instanz:

gcloud spanner instances delete test-instance

Beachten Sie, dass beim Löschen einer Instanz auch alle Datenbanken in der Instanz gelöscht werden. Das Löschen einer Instanz kann nicht rückgängig gemacht werden.