Lernziele
In dieser Anleitung werden Sie durch die folgenden Schritte mit dem Spanner-JDBC-Treiber geführt:
- 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 Spanner verwendet, eine kostenpflichtige Komponente von Google Cloud. Informationen zu den Kosten für die Verwendung von Spanner finden Sie unter Preise.
Hinweise
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 JDBC-Umgebung vorbereiten
Installieren Sie Folgendes auf Ihrem Entwicklungscomputer, falls nicht bereits vorhanden:
- Java 8 JDK (herunterladen).
- Maven 3 (herunterladen).
Klonen Sie das Repository der Beispiel-App auf Ihren lokalen Computer:
git clone https://github.com/googleapis/java-spanner-jdbc.git
Wechseln Sie in das Verzeichnis, das den Spanner-Beispielcode enthält:
cd java-spanner-jdbc/samples/snippets
Instanz erstellen
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, 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 Spanner-Instanz in der Region us-central1
mit 1 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 finden Sie unter Informationen zu 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 finden Sie unter Knoten und Verarbeitungseinheiten.)
Hier sollten Sie das sehen:
Creating instance...done.
Beispieldateien ansehen
Das Beispiel-Repository enthält ein Beispiel für die Verwendung von Spanner mit JDBC.
Derpom.xml
fügt den Spanner-JDBC-Treiber den Abhängigkeiten des Projekts hinzu und konfiguriert das Assembly-Plug-in so, dass eine ausführbare JAR-Datei mit der in dieser Anleitung definierten Java-Klasse erstellt wird.
Erstellen Sie das Beispiel aus dem Verzeichnis samples/snippets
:
mvn package -DskipTests
Datenbank erstellen
Erstellen Sie eine Datenbank mit dem Namen example-db
in der Instanz test-instance
. Führen Sie dazu folgenden Befehl in der Befehlszeile aus:
GoogleSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
createdatabase test-instance example-db
PostgreSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
createpgdatabase test-instance example-db
Hier sollten Sie das sehen:
Created database [projects/my-project/instances/test-instance/databases/example-db]
Mit dem folgenden Code werden eine Datenbank und zwei Tabellen in der Datenbank erstellt.
GoogleSQL
PostgreSQL
Im nächsten Schritt werden Daten in die Datenbank geschrieben.
JDBC-Verbindung erstellen
Zum Ausführen von Lese- oder Schreibvorgängen müssen Sie einenConnection
erstellen. Alle Interaktionen mit Spanner müssen einen Connection
durchlaufen. Der Datenbankname und andere Attribute werden in der JDBC-Verbindungs-URL und im Satz java.util.Properties
angegeben.
GoogleSQL
PostgreSQL
Eine vollständige Liste der unterstützten Attribute finden Sie unter Verbindungs-URL-Attribute.
Da jede Connection
Ressourcen verwendet, empfiehlt es sich, Verbindungen entweder zu trennen, wenn sie nicht mehr benötigt werden, oder einen Verbindungspool zu verwenden, um sie in der gesamten Anwendung wiederzuverwenden.
Weitere Informationen finden Sie in der Javadoc-Referenz für Connection
.
JDBC-Treiber mit dem Emulator verbinden
Sie können den JDBC-Treiber auf zwei Arten mit dem Spanner-Emulator verbinden:
- Legen Sie die Umgebungsvariable
SPANNER_EMULATOR_HOST
fest: Dadurch wird der JDBC-Treiber angewiesen, eine Verbindung zum Emulator herzustellen. Die Spanner-Instanz und -Datenbank in der JDBC-Verbindungs-URL müssen bereits im Emulator vorhanden sein. - Fügen Sie der Verbindungs-URL
autoConfigEmulator=true
hinzu: Dadurch wird der JDBC-Treiber angewiesen, eine Verbindung zum Emulator herzustellen und die Spanner-Instanz und -Datenbank automatisch in der JDBC-Verbindungs-URL zu erstellen, wenn diese nicht vorhanden sind.
In diesem Beispiel wird gezeigt, wie Sie die autoConfigEmulator=true
-Verbindungs-URL-Option verwenden.
GoogleSQL
PostgreSQL
Daten mit DML schreiben
Sie können Daten mit der Datenbearbeitungssprache (Data Manipulation Language, DML) in eine Lese-Schreib-Transaktion einfügen.
Zum Ausführen einer DML-Anweisung verwenden Sie die Methode PreparedStatement.executeUpdate()
.
GoogleSQL
PostgreSQL
Führen Sie das Beispiel mit diesem Befehl aus:
GoogleSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
writeusingdml test-instance example-db
PostgreSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
writeusingdmlpg test-instance example-db
Hier sollten Sie das sehen:
4 records inserted.
Daten mit einem DML-Batch schreiben
Sie verwenden die Methoden PreparedStatement#addBatch()
und PreparedStatement#executeBatch()
, um mehrere DML-Anweisungen in einem Batch auszuführen.
GoogleSQL
PostgreSQL
Führen Sie das Beispiel mit diesem Befehl aus:
GoogleSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
writeusingdmlbatch test-instance example-db
PostgreSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
writeusingdmlbatchpg test-instance example-db
Hier sollten Sie das sehen:
3 records inserted.
Daten mit Mutationen schreiben
Sie können Daten auch mithilfe von Mutationen einfügen.
Sie können Daten mit einem Mutation
-Objekt schreiben.
Ein Mutation
-Objekt ist ein Container für Mutationsvorgänge. Ein Mutation
stellt eine Folge von Einfügungs-, Aktualisierungs- und Löschvorgängen dar, die Spanner in kleinstmöglichen Schritten auf verschiedene Zeilen und Tabellen in einer Spanner-Datenbank anwendet.
Die Methode newInsertBuilder()
in der Klasse Mutation
konstruiert 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. Alternativ können Sie die Methode newInsertOrUpdateBuilder
verwenden, um eine INSERT_OR_UPDATE
-Mutation zu erstellen, die Spaltenwerte aktualisiert, wenn die Zeile bereits vorhanden ist.
write()
in der CloudSpannerJdbcConnection
-Schnittstelle schreibt die Mutationen. Alle Mutationen in einem einzelnen Batch werden in kleinstmöglichen Schritten angewendet.
Sie können die CloudSpannerJdbcConnection
-Schnittstelle von einer Spanner-JDBC-Connection
entpacken.
Dieser Code zeigt, wie die Daten mithilfe von Mutationen geschrieben werden:
GoogleSQL
PostgreSQL
Führen Sie das Beispiel mit diesem Befehl aus:
GoogleSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
write test-instance example-db
PostgreSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
writepg test-instance example-db
Hier sollten Sie das sehen:
Inserted 10 rows.
Daten mit SQL abfragen
Spanner unterstützt eine SQL-Schnittstelle zum Lesen von Daten, auf die Sie in der Befehlszeile mit der Google Cloud CLI oder programmatisch mit dem Spanner-JDBC-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'
PostgreSQL
gcloud spanner databases execute-sql example-db --instance=test-instance \
--sql='SELECT singer_id, album_id, album_title FROM albums'
Das Ergebnis sollte in etwa 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
Spanner-JDBC-Treiber verwenden
Als Alternative zum Ausführen einer SQL-Anweisung in der Befehlszeile können Sie die gleiche SQL-Anweisung programmatisch mit dem Spanner-JDBC-Treiber ausführen.
Zum Ausführen der SQL-Abfrage werden die folgenden Methoden und Klassen verwendet:- Die Methode
createStatement()
in derConnection
-Schnittstelle: Mit dieser Methode können Sie ein neues Anweisungsobjekt zum Ausführen einer SQL-Anweisung erstellen. - Die Methode
executeQuery(String)
der KlasseStatement
: 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 ausführen. - Die Klasse
ResultSet
: Mit dieser Klasse können Sie auf die von einer SQL-Anweisung zurückgegebenen Daten zugreifen.
So geben Sie die Abfrage aus und greifen auf die Daten zu:
GoogleSQL
PostgreSQL
Führen Sie das Beispiel mit diesem Befehl aus:
GoogleSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
query test-instance example-db
PostgreSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
querypg 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
Wenn es für Ihre Anwendung eine häufig ausgeführte Abfrage gibt, können Sie die Leistung durch Parametrieren verbessern. Die resultierende parametrische Abfrage kann im Cache gespeichert und wiederverwendet werden, wodurch die Kompilierungskosten reduziert werden. Weitere Informationen finden Sie unter Mit Abfrageparametern häufig ausgeführte Abfragen beschleunigen.
Im folgenden Beispiel wird ein Parameter in der WHERE
-Klausel verwendet, um Datensätze abzufragen, die einen bestimmten Wert für LastName
enthalten.
Verwenden Sie java.sql.PreparedStatement
, um eine Abfrage mit einem Parameter auszuführen.
GoogleSQL
PostgreSQL
Führen Sie das Beispiel mit diesem Befehl aus:
GoogleSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
querywithparameter test-instance example-db
PostgreSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
querywithparameterpg test-instance example-db
Sie sollten folgendes Ergebnis sehen:
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 eine Datenbank, während die Datenbank weiterhin Traffic bereitstellt. Bei Schemaaktualisierungen muss die Datenbank nicht offline geschaltet werden und es müssen keine ganzen Tabellen oder Spalten gesperrt werden. Sie können während der Schemaaktualisierung weiter Daten in die Datenbank schreiben. Weitere Informationen zu unterstützten Schemaaktualisierungen und zur Leistung während der Schemaänderung finden Sie unter Schemaaktualisierungen vornehmen.
Spalte hinzufügen
Sie können eine Spalte in der Befehlszeile mithilfe der Google Cloud CLI oder programmgesteuert über die Spanner-Clientbibliothek für JDBC 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 das sehen:
Schema updating...done.
Spanner-JDBC-Treiber verwenden
Verwenden Sie die Methodeexecute(String)
der Klasse java.sql.Statement
, um das Schema zu ändern:
GoogleSQL
PostgreSQL
Führen Sie das Beispiel mit diesem Befehl aus:
GoogleSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
addmarketingbudget test-instance example-db
PostgreSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
addmarketingbudgetpg test-instance example-db
Hier sollten Sie das sehen:
Added MarketingBudget column.
DDL-Batch ausführen
Es empfiehlt sich, mehrere Schemaänderungen in einem Batch auszuführen. Mit der Methode addBatch(String)
von java.sql.Statement
können Sie einem Batch mehrere DDL-Anweisungen hinzufügen.
GoogleSQL
PostgreSQL
Führen Sie das Beispiel mit diesem Befehl aus:
GoogleSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
ddlbatch test-instance example-db
PostgreSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
ddlbatchpg test-instance example-db
Hier sollten Sie das sehen:
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 500000
für den Zeilenschlüssel, der durch Albums(2, 2)
angegeben wird.
GoogleSQL
PostgreSQL
Führen Sie das Beispiel mit diesem Befehl aus:
GoogleSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
update test-instance example-db
PostgreSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
updatepg test-instance example-db
Die Ausgabe sollte in etwa so aussehen:
Updated albums
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:
GoogleSQL
PostgreSQL
Führen Sie den folgenden Befehl aus, um diese Abfrage auszuführen:
GoogleSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
querymarketingbudget test-instance example-db
PostgreSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
querymarketingbudgetpg 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.
Legen Sie AutoCommit=false
fest, um Lese-Schreib-Transaktionen in JDBC auszuführen.
GoogleSQL
PostgreSQL
Führen Sie das Beispiel mit diesem Befehl aus:
GoogleSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
writewithtransactionusingdml test-instance example-db
PostgreSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
writewithtransactionusingdmlpg test-instance example-db
Transaktions-Tags und Anfrage-Tags
Verwenden Sie Transaktions-Tags und Anfrage-Tags, um Fehler bei Transaktionen und Abfragen in Spanner zu beheben. Sie können Transaktions- und Anfrage-Tags in der JDBC mit den Sitzungsvariablen TRANSACTION_TAG
und STATEMENT_TAG
festlegen.
GoogleSQL
PostgreSQL
Führen Sie das Beispiel mit diesem Befehl aus:
GoogleSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
tags test-instance example-db
PostgreSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
tagspg test-instance 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.
Legen Sie ReadOnly=true
und AutoCommit=false
für eine java.sql.Connection
fest oder verwenden Sie die SQL-Anweisung SET TRANSACTION READ ONLY
, um eine schreibgeschützte Transaktion auszuführen.
So werden eine Abfrage und ein Lesevorgang in derselben schreibgeschützten Transaktion ausgeführt:
GoogleSQL
PostgreSQL
Führen Sie das Beispiel mit diesem Befehl aus:
GoogleSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
readonlytransaction test-instance example-db
PostgreSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
readonlytransactionpg 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
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 Standardabfrage-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 mit nahezu keinen Auswirkungen auf vorhandene Arbeitslasten auf der bereitgestellten Spanner-Instanz ausführen. Data Boost unterstützt nur partitionierte Abfragen.
GoogleSQL
PostgreSQL
Führen Sie das Beispiel mit diesem Befehl aus:
GoogleSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
databoost test-instance example-db
PostgreSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
databoostpg test-instance example-db
Weitere Informationen zum Ausführen von partitionierten Abfragen und zur Verwendung von Data Boost mit dem JDBC-Treiber finden Sie unter:
- GoogleSQL: Data Boost und partitionierte Abfrageanweisungen
- PostgreSQL: Data Boost und partitionierte Abfrageanweisungen
Partitionierte DML
Die partitionierte Datenbearbeitungssprache (DML) wurde für die folgenden Typen von Bulk-Aktualisierungen und -Löschvorgängen entwickelt:
- Regelmäßige und automatische Speicherbereinigungsvorgänge.
Backfilling neuer Spalten mit Standardwerten.
GoogleSQL
PostgreSQL
Führen Sie das Beispiel mit diesem Befehl aus:
GoogleSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
pdml test-instance example-db
PostgreSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
pdmlpg test-instance example-db
Weitere Informationen zu AUTOCOMMIT_DML_MODE
finden Sie unter:
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
Rufen Sie in der Google Cloud Console die Seite 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
Google Cloud Console verwenden
Rufen Sie in der Google Cloud Console die Seite 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
- Spanner mit Spring Data JPA (GoogleSQL-Dialekt) einbinden
- Spanner mit Spring Data JPA (PostgreSQL-Dialekt) einbinden
- Spanner mit Hibernate ORM (GoogleSQL-Dialekt) einbinden
- Spanner mit Hibernate ORM (PostgreSQL-Dialekt) einbinden
- Weitere Informationen zu Befehlen zur JDBC-Sitzungsverwaltung (GoogleSQL)
- Weitere Informationen zu Befehlen zur JDBC-Sitzungsverwaltung (PostgreSQL)
Informationen zu Anmeldedaten für die Autorisierung und Authentifizierung finden Sie unter Mit Clientbibliotheken bei Cloud-Diensten authentifizieren.