Lernziele
In dieser Anleitung werden Sie durch die folgenden Schritte mit der Cloud Spanner-Clientbibliothek für Java geführt:
- Cloud 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 von Google Cloud. Informationen zu den Kosten der Nutzung von Cloud Spanner finden Sie unter Preise.
Hinweis
Führen Sie die unter Einrichten beschriebenen Schritte aus, die das Erstellen und Festlegen eines standardmäßigen Google Cloud-Projekts, das Aktivieren der Rechnungsstellung, das Aktivieren der Cloud Spanner API und das Einrichten von OAuth 2.0 umfassen, um Anmeldedaten für die Authentifizierung 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.
Lokale Java-Umgebung vorbereiten
Installieren Sie Folgendes auf Ihrem Entwicklungscomputer, falls nicht bereits vorhanden:
Klonen Sie das Repository der Beispiel-App auf Ihren lokalen Computer:
git clone https://github.com/googleapis/java-spanner.git
Wechseln Sie in das Verzeichnis, das den Cloud Spanner-Beispielcode enthält:
cd java-spanner/samples/snippets
Instanz erstellen
Wenn Sie Cloud Spanner zum ersten Mal verwenden, müssen Sie eine Instanz erstellen. Dabei handelt es sich um eine Zuordnung von Ressourcen, die von Cloud 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.
Führen Sie den folgenden Befehl aus, um eine Cloud Spanner-Instanz in der Region us-central1
mit nur einem Knoten zu erstellen:
gcloud spanner instances create test-instance --config=regional-us-central1 \
--description="Test Instance" --nodes=1
Dadurch wird eine Instanz mit diesen Properties erstellt:
- Instanz-ID
test-instance
- Anzeigename
Test Instance
- Instanzkonfiguration
regional-us-central1
– Bei regionalen Konfigurationen werden Daten in nur einer Region gespeichert, während sie bei multiregionalen Konfigurationen auf mehrere Regionen verteilt werden. Weitere Informationen dazu finden Sie unter Instanzen. - Knotenanzahl 1 –
node_count
entspricht der Anzahl der Bereitstellungs- und Speicherressourcen in der Instanz, die für Datenbanken zur Verfügung stehen. Weitere Informationen dazu finden Sie unter Knotenzahl.
Hier sollten Sie das sehen:
Creating instance...done.
Beispieldateien ansehen
Das Beispiel-Repository enthält ein Beispiel für die Verwendung von Cloud Spanner mit Java.
Mit der Dateipom.xml
wird die Cloud Spanner-Clientbibliothek für Java den abhängigen Komponenten des Projekts hinzugefügt und das Assembly-Plug-in konfiguriert, um eine ausführbare JAR-Datei mit der in dieser Anleitung definierten Java-Klasse zu erstellen.
Erstellen Sie das Beispiel aus dem Verzeichnis samples/snippets
:
mvn package
Datenbank erstellen
Erstellen Sie eine Datenbank mit dem Namen example-db
in der Instanz test-instance
, indem Sie Folgendes in der Befehlszeile ausführen:
java -jar target/spanner-google-cloud-samples-jar-with-dependencies.jar \
createdatabase test-instance example-db
Hier sollten Sie das sehen:
Created database [example-db]
Sie haben gerade eine Cloud Spanner-Datenbank erstellt. Die Datenbank wurde aus diesem Code erstellt:
Mit dem Code werden außerdem die beiden Tabellen Singers
und Albums
für eine einfache Musikanwendung definiert. Die Tabellen werden im weiteren Verlauf dieser Seite verwendet. Sehen Sie sich das Beispielschema an, falls Sie es noch nicht getan haben.
Im nächsten Schritt werden Daten in die Datenbank geschrieben.
Datenbankclient erstellen
Zum Ausführen von Lese- oder Schreibvorgängen müssen Sie einenDatabaseClient
erstellen.
Sie können sich einen DatabaseClient
wie eine Datenbankverbindung vorstellen: Alle Interaktionen mit Cloud Spanner müssen einen DatabaseClient
durchlaufen. In der Regel erstellen Sie einen DatabaseClient
beim Starten Ihrer Anwendung. Anschließend verwenden Sie DatabaseClient
zum Lesen, Schreiben und Ausführen von Transaktionen.
Da jeder Client Ressourcen in Cloud Spanner belegt, empfiehlt es sich, nicht benötigte Clients durch den Aufruf von close()
zu schließen.
Weitere Informationen finden Sie in der Javadoc-Referenz für DatabaseClient
.
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 Methode executeUpdate()
.
Führen Sie das Beispiel mit dem Argument writeusingdml
aus.
java -jar target/spanner-google-cloud-samples-jar-with-dependencies.jar \
writeusingdml test-instance example-db
Hier sollten Sie das sehen:
4 records inserted.
Daten mit Mutationen schreiben
Sie können Daten auch mithilfe von Mutationen einfügen.
Daten werden mit einem Mutation
-Objekt geschrieben.
Ein Mutation
-Objekt ist ein Container für Mutationsvorgänge. Eine Mutation
stellt eine Folge von Einfügungs-, Aktualisierungs- und Löschvorgängen dar, die Cloud Spanner in kleinstmöglichen Schritten auf verschiedene Zeilen und Tabellen in einer Cloud Spanner-Datenbank anwenden kann.
Die Methode newInsertBuilder()
in der Klasse Mutation
erstellt eine INSERT
-Mutation, die eine neue Zeile in eine Tabelle einfügt. Wenn die Zeile bereits vorhanden ist, kann der Schreibvorgang nicht durchgeführt werden. In diesem Fall können Sie alternativ mit der Methode newInsertOrUpdateBuilder
die Mutation INSERT_OR_UPDATE
erstellen, um Spaltenwerte zu aktualisieren.
Die Methode write()
in der Klasse DatabaseClient
schreibt die Mutationen. Alle Mutationen in einem einzelnen Batch werden in kleinstmöglichen Schritten angewendet.
Dieser Code zeigt, wie die Daten mithilfe von Mutationen geschrieben werden:
Führen Sie das Beispiel mit dem Argument write
aus.
java -jar target/spanner-google-cloud-samples-jar-with-dependencies.jar \
write test-instance example-db
Der Befehl sollte erfolgreich ausgeführt werden.
Daten mit SQL abfragen
Cloud Spanner unterstützt eine native SQL-Oberfläche zum Lesen von Daten, auf die Sie in der Befehlszeile mit dem gcloud
-Befehlszeilentool oder programmatisch mit der Cloud Spanner-Clientbibliothek für Java 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:
gcloud spanner databases execute-sql example-db --instance=test-instance \
--sql='SELECT SingerId, AlbumId, AlbumTitle FROM Albums'
Das Ergebnis sollte so aussehen:
SingerId AlbumId AlbumTitle
1 1 Total Junk
1 2 Go, Go, Go
2 1 Green
2 2 Forever Hold Your Peace
2 3 Terrified
Cloud Spanner-Clientbibliothek für Java verwenden
Als Alternative zum Ausführen einer SQL-Anweisung in der Befehlszeile können Sie die gleiche SQL-Anweisung programmgesteuert mithilfe der Cloud Spanner-Clientbibliothek für Java ausführen.
Zum Ausführen der SQL-Abfrage werden die folgenden Methoden und Klassen verwendet:- Die Methode
singleUse()
in der KlasseDatabaseClient
: Hiermit können Sie den Wert einer oder mehrerer Spalten aus einer oder mehreren Zeilen in einer Cloud Spanner-Tabelle lesen.singleUse()
gibt ein Objekt des TypsReadContext
zurück, die zum Ausführen einer Lese- oder SQL-Anweisung verwendet wird. - Die Methode
executeQuery()
der KlasseReadContext
: Verwenden Sie diese Methode, um eine Abfrage für eine Datenbank auszuführen. - Die Klasse
Statement
: Mit dieser Klasse können Sie einen SQL-String erstellen. - Die Klasse
ResultSet
: Mit dieser Klasse können Sie auf die von SQL-Anweisungen oder Leseaufrufen zurückgegebenen Daten zugreifen.
So geben Sie die Abfrage aus und greifen auf die Daten zu:
Führen Sie das Beispiel mit dem Argument query
aus.
java -jar target/spanner-google-cloud-samples-jar-with-dependencies.jar \
query test-instance example-db
Sie sollten folgendes Ergebnis sehen:
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
Sie können mithilfe von unterstützten SQL-Typen benutzerdefinierte Werte in SQL-Anweisungen einfügen.
Im Folgenden finden Sie ein Beispiel für die Verwendung von @lastName
als Parameter in der WHERE
-Klausel zum Abfragen von Datensätzen, die einen bestimmten Wert für LastName
enthalten.
Führen Sie das Beispiel mit dem Argument queryWithParameter aus.
java -jar target/spanner-google-cloud-samples-jar-with-dependencies.jar \
querywithparameter test-instance example-db
Sie sollten dieses Ergebnis sehen:
12 Melissa Garcia
Daten mit der Lese-API auslesen
Neben der SQL-Schnittstelle unterstützt Cloud Spanner auch eine Leseschnittstelle.
Verwenden Sie die Methoderead()
der Klasse ReadContext
, um Zeilen aus der Datenbank zu lesen. Mit dem Objekt KeySet
können Sie eine Sammlung der zu lesenden Schlüssel und Schlüsselbereiche definieren.
So lesen Sie die Daten aus:
Führen Sie das Beispiel mit dem Argument read
aus.
java -jar target/spanner-google-cloud-samples-jar-with-dependencies.jar \
read test-instance example-db
Die Ausgabe sollte etwa so aussehen:
1 1 Total Junk
1 2 Go, Go, Go
2 1 Green
2 2 Forever Hold Your Peace
2 3 Terrified
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. Cloud 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 während der Schemaänderung finden Sie unter Schemaaktualisierungen.
Spalte hinzufügen
Sie können eine Spalte in der Befehlszeile mithilfe des gcloud
-Befehlszeilentools oder programmatisch mithilfe der Cloud Spanner-Clientbibliothek für Java hinzufügen.
Über die Befehlszeile
Verwenden Sie den folgenden Befehl ALTER TABLE
, um die neue Spalte zur Tabelle hinzuzufügen:
gcloud spanner databases ddl update example-db --instance=test-instance \
--ddl='ALTER TABLE Albums ADD COLUMN MarketingBudget INT64'
Hier sollten Sie dies sehen:
Schema updating...done.
Cloud Spanner-Clientbibliothek für Java verwenden
Verwenden Sie die MethodeupdateDatabaseDdl()
der Klasse DatabaseAdminClient
, um das Schema zu ändern:
Führen Sie das Beispiel mit dem Argument addmarketingbudget
aus.
java -jar target/spanner-google-cloud-samples-jar-with-dependencies.jar \
addmarketingbudget test-instance example-db
Hier sollten Sie das sehen:
Added MarketingBudget column.
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 500000
für den Zeilenschlüssel, der durch Albums(2, 2)
angegeben wird.
Führen Sie das Beispiel mit dem Argument update
aus.
java -jar target/spanner-google-cloud-samples-jar-with-dependencies.jar \
update test-instance example-db
Sie können auch eine SQL-Abfrage oder einen Leseaufruf ausführen, um die Werte abzurufen, die Sie gerade geschrieben haben.
Mit diesem Code können Sie die Abfrage ausführen:
Für diese Abfrage führen Sie das Beispiel mit dem Argument querymarketingbudget
aus.
java -jar target/spanner-google-cloud-samples-jar-with-dependencies.jar \
querymarketingbudget test-instance example-db
Hier sollten Sie das 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.
Für das Ausführen einer DML-Anweisung verwenden Sie die Methode executeUpdate()
.
Führen Sie das Beispiel mit dem Argument writewithtransactionusingdml
aus.
java -jar target/spanner-google-cloud-samples-jar-with-dependencies.jar \
writewithtransactionusingdml test-instance example-db
Sekundären Index verwenden
Beispiel: Sie möchten alle Zeilen aus Albums
abrufen, deren Wert für AlbumTitle
in einem bestimmten Bereich liegen. Sie könnten dazu alle Werte aus der Spalte AlbumTitle
mit einer SQL-Anweisung oder einem Leseaufruf lesen und dann die Zeilen verwerfen, die die Kriterien nicht erfüllen. Dieser vollständige Tabellenscan wäre jedoch sehr kostspielig, insbesondere bei Tabellen mit vielen Zeilen. Stattdessen können Sie einen sekundären Index für die Tabelle erstellen und damit das Abrufen von Zeilen beim Suchen über Spalten mit nicht primärem Schlüssel beschleunigen.
Damit ein sekundärer Index einer vorhandenen Tabelle hinzugefügt werden kann, muss das Schema aktualisiert werden. Wie bei anderen Schemaaktualisierungen kann mit Cloud Spanner ein Index hinzugefügt werden, ohne dass die Traffic-Bereitstellung unterbrochen werden muss. Cloud Spanner verwendet dann automatisch die vorhandenen Daten, um einen Backfill für den Index auszuführen. Backfills können einige Minuten dauern. Sie müssen aber die Datenbank nicht offline schalten und können während des Vorgangs weiter in die indexierten Tabellen schreiben. Weitere Informationen finden Sie unter Index-Backfill.
Nachdem Sie einen sekundären Index hinzugefügt haben, verwendet Cloud Spanner diesen automatisch für SQL-Abfragen, die mit dem Index sehr wahrscheinlich schneller ausgeführt werden. Wenn Sie die Leseschnittstelle verwenden, müssen Sie den Index angeben, den Sie nutzen möchten.
Sekundären Index hinzufügen
Sie können einen Index in der Befehlszeile mithilfe des gcloud
-Befehlszeilentools oder programmatisch mithilfe der Cloud Spanner-Clientbibliothek für Java hinzufügen.
Über die Befehlszeile
Verwenden Sie den folgenden Befehl CREATE INDEX
, um der Datenbank einen Index hinzuzufügen:
gcloud spanner databases ddl update example-db --instance=test-instance \
--ddl='CREATE INDEX AlbumsByAlbumTitle ON Albums(AlbumTitle)'
Hier sollten Sie dies sehen:
Schema updating...done.
Cloud Spanner-Clientbibliothek für Java verwenden
Verwenden Sie die MethodeupdateDatabaseDdl()
der Klasse DatabaseAdminClient
, um einen Index hinzuzufügen:
Führen Sie das Beispiel mit dem Argument addindex
aus.
java -jar target/spanner-google-cloud-samples-jar-with-dependencies.jar \
addindex test-instance example-db
Das Hinzufügen eines Index kann einige Minuten dauern. Nachdem der Index hinzugefügt wurde, sollten Sie das sehen:
Added the AlbumsByAlbumTitle index.
Mit dem Index auslesen
Für SQL-Abfragen verwendet Cloud Spanner automatisch einen geeigneten Index. In der Leseschnittstelle müssen Sie den Index in Ihrer Anfrage angeben.
Für die Verwendung des Index in der Leseschnittstelle nutzen Sie die Methode readUsingIndex()
der Klasse ReadContext
.
Mit dem folgenden Code werden alle Spalten AlbumId
und AlbumTitle
aus dem Index AlbumsByAlbumTitle
abgerufen.
Führen Sie das Beispiel mit dem Argument readindex
aus.
java -jar target/spanner-google-cloud-samples-jar-with-dependencies.jar \
readindex test-instance example-db
Hier sollten Sie das sehen:
2 Forever Hold Your Peace
2 Go, Go, Go
1 Green
3 Terrified
1 Total Junk
Index mit einer STORING-Klausel hinzufügen
Vielleicht haben Sie bemerkt, dass im obigen Beispiel die Spalte MarketingBudget
nicht gelesen wird. Die Leseschnittstelle von Cloud Spanner unterstützt nicht die Möglichkeit, einen Index mit einer Datentabelle zu verbinden, um Werte zu suchen, die nicht im Index gespeichert sind.
Erstellen Sie eine alternative Definition von AlbumsByAlbumTitle
, die eine Kopie von MarketingBudget
im Index speichert.
Über die Befehlszeile
gcloud spanner databases ddl update example-db --instance=test-instance \
--ddl='CREATE INDEX AlbumsByAlbumTitle2 ON Albums(AlbumTitle) STORING (MarketingBudget)'
Das Hinzufügen eines Index kann einige Minuten dauern. Nachdem der Index hinzugefügt wurde, sollten Sie Folgendes sehen:
Schema updating...done.
Cloud Spanner-Clientbibliothek für Java verwenden
Verwenden Sie die Methode updateDatabaseDdl()
der Klasse DatabaseAdminClient
, um einen Index mit einer STORING
-Klausel hinzuzufügen:
Führen Sie das Beispiel mit dem Argument addstoringindex
aus.
java -jar target/spanner-google-cloud-samples-jar-with-dependencies.jar \
addstoringindex test-instance example-db
Das Hinzufügen eines Index kann einige Minuten dauern. Nachdem der Index hinzugefügt wurde, sollten Sie das sehen:
Added AlbumsByAlbumTitle2 index
Sie können jetzt einen Lesevorgang ausführen, der die Spalten AlbumId
, AlbumTitle
und MarketingBudget
aus dem Index AlbumsByAlbumTitle2
abruft:
Führen Sie das Beispiel mit dem Argument readstoringindex
aus.
java -jar target/spanner-google-cloud-samples-jar-with-dependencies.jar \
readstoringindex test-instance example-db
Die Ausgabe sollte etwa so aussehen:
2 Forever Hold Your Peace 300000
2 Go, Go, Go NULL
1 Green NULL
3 Terrified NULL
1 Total Junk 300000
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.
Zum Ausführen schreibgeschützter Transaktionen verwenden Sie ein ReadOnlyTransaction
-Objekt . Verwenden Sie die Methode readOnlyTransaction()
der Klasse DatabaseClient
, um ein ReadOnlyTransaction
-Objekt zu erhalten.
So werden eine Abfrage und ein Lesevorgang in derselben schreibgeschützten Transaktion ausgeführt:
Führen Sie das Beispiel mit dem Argument readonlytransaction
aus.
java -jar target/spanner-google-cloud-samples-jar-with-dependencies.jar \
readonlytransaction test-instance example-db
Die Ausgabe sollte etwa so aussehen:
2 2 Forever Hold Your Peace
1 2 Go, Go, Go
2 1 Green
2 3 Terrified
1 1 Total Junk
1 1 Total Junk
1 2 Go, Go, Go
2 1 Green
2 2 Forever Hold Your Peace
2 3 Terrified
Clean-up
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
Mit der Cloud Console
Rufen Sie in der Google Cloud Console die Seite Cloud Spanner-Instanzen auf.
Klicken Sie auf die Instanz.
Klicken Sie auf die Datenbank, die Sie löschen möchten.
Klicken Sie auf der Seite Datenbankdetails auf Löschen.
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
Mit der Cloud Console
Rufen Sie in der Google Cloud Console die Seite Cloud Spanner-Instanzen auf.
Klicken Sie auf die Instanz.
Klicken Sie auf Löschen.
Bestätigen Sie, dass die Instanz gelöscht werden soll, und klicken Sie auf Löschen.
Nächste Schritte
- Spring Data-Modul für Cloud Spanner testen.
- Über eine VM-Instanz auf Cloud Spanner zugreifen: Erstellen Sie eine VM-Instanz mit Zugriff auf die Cloud Spanner-Datenbank.
- Anmeldedaten für die Autorisierung und Authentifizierung: Siehe Erste Schritte bei der Authentifizierung
- Cloud Spanner-Konzepte