Lernziele
In dieser Anleitung werden Sie durch die folgenden Schritte mit Spanner geführt JDBC-Treiber:
- Erstellen Sie eine Spanner-Instanz und -Datenbank.
- 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 des 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 dem Entwicklungscomputer, sofern 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. Dies ist 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 zu erstellen
us-central1
mit 1 Knoten:
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 dies sehen:
Creating instance...done.
Beispieldateien ansehen
Das Beispiel-Repository enthält ein Beispiel für die Verwendung von Spanner mit JDBC.
pom.xml
fügt den Spanner-JDBC-Treiber zur
Projektabhängigkeiten und konfiguriert das Assembly-Plug-in, um ein
ausführbare JAR-Datei mit der in dieser Anleitung definierten Java-Klasse.
Erstellen Sie das Beispiel aus dem
samples/snippets
-Verzeichnis:
mvn package -DskipTests
Datenbank erstellen
Erstellen Sie eine Datenbank mit dem Namen example-db
in der Instanz test-instance
, indem Sie
und führen den 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 dies 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 Ihre Interaktionen
mit Spanner muss einen Connection
durchlaufen. Datenbankname und andere
werden in der JDBC-Verbindungs-URL und der
java.util.Properties
festgelegt.
GoogleSQL
PostgreSQL
Eine vollständige Liste der unterstützten Attribute finden Sie unter Eigenschaften der Verbindungs-URL:
Jede Connection
verbraucht Ressourcen, daher empfiehlt es sich, entweder
wenn sie nicht mehr benötigt werden,
oder um einen Verbindungspool zu nutzen,
Verbindungen in Ihrer gesamten Anwendung wiederverwenden.
Weitere Informationen finden Sie im Javadoc zu Connection
.
Referenz.
JDBC-Treiber mit dem Emulator verbinden
Sie können den JDBC-Treiber mit dem Spanner-Emulator verbinden in auf zwei Arten:
- Legen Sie die Umgebungsvariable
SPANNER_EMULATOR_HOST
fest: JDBC-Treiber zum Herstellen einer Verbindung zum Emulator. Spanner Instanz und Datenbank in der JDBC-Verbindungs-URL müssen bereits im Emulator. - Fügen Sie der Verbindungs-URL
autoConfigEmulator=true
hinzu: Dies weist den JDBC-Treiber zum Herstellen einer Verbindung zum Emulator und zum automatischen Erstellen des Spanner-Instanz und -Datenbank in der JDBC-Verbindungs-URL falls diese nicht existieren.
In diesem Beispiel wird gezeigt, wie die autoConfigEmulator=true
-Verbindungs-URL verwendet wird.
Option.
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 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 dies sehen:
4 records inserted.
Daten mit einem DML-Batch schreiben
Sie verwenden diePreparedStatement#addBatch()
und
PreparedStatement#executeBatch()
-Methoden zum Ausführen mehrerer DML-Anweisungen in
einen Batch.
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 dies sehen:
3 records inserted.
Daten mit Mutationen schreiben
Sie können Daten auch mithilfe von Mutationen einfügen.
Sie können Daten mit
Ein Mutation
-Objekt.
Ein Mutation
-Objekt ist ein Container für Mutationsvorgänge. Ein Mutation
eine Folge von Einfügungs-, Aktualisierungs- und Löschvorgängen darstellt, die Spanner
wird in kleinstmöglichen Schritten auf verschiedene Zeilen und Tabellen in einer Spanner-Datenbank angewendet.
Die newInsertBuilder()
in der Klasse Mutation
erstellt eine INSERT
-Mutation, die einen
neue Zeile in einer Tabelle. Wenn die Zeile bereits vorhanden ist, kann der Schreibvorgang nicht durchgeführt werden. Alternativ können Sie
können Sie den newInsertOrUpdateBuilder
Methode zum Erstellen einer INSERT_OR_UPDATE
-Mutation, die Spaltenwerte aktualisiert
falls die Zeile bereits vorhanden ist.
write()
in der CloudSpannerJdbcConnection
-Schnittstelle schreibt die Mutationen. Alle
werden Mutationen in einem
einzelnen Batch in kleinstmöglichen Schritten angewendet.
Sie können die CloudSpannerJdbcConnection
-Schnittstelle aus einem Spanner entpacken
JDBC-Connection
.
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 dies sehen:
Inserted 10 rows.
Daten mit SQL abfragen
Spanner unterstützt eine SQL-Schnittstelle zum Lesen von Daten, die Sie Zugriff über die Befehlszeile über die Google Cloud CLI oder programmatischen über den Spanner-JDBC-Treiber zu installieren.
Ü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 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
Neben dem Ausführen einer SQL-Anweisung in der Befehlszeile können Sie den Befehl mithilfe des JDBC-Treibers von Spanner programmatisch
Zum Ausführen der SQL-Abfrage werden die folgenden Methoden und Klassen verwendet:- Die
createStatement()
Methode in derConnection
-Schnittstelle: Hiermit erstellen Sie ein neues Anweisungsobjekt. zum Ausführen einer SQL-Anweisung. - Die Methode
executeQuery(String)
der KlasseStatement
: Verwenden Sie diese Methode, um eine Abfrage für eine Datenbank auszuführen. - Die
Statement
class: Verwenden Sie diese Klasse, um einen SQL-String auszuführen. - Die
ResultSet
class: Verwenden Sie diese Klasse, um auf die von einer SQL-Anweisung zurückgegebenen Daten zuzugreifen.
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 Ihre Anwendung eine häufig ausgeführte Abfrage hat, können Sie deren Leistung verbessern indem Sie es parametrisieren. Die resultierende parametrische Abfrage kann im Cache gespeichert und wiederverwendet werden, was reduziert die Kompilierungskosten. Weitere Informationen finden Sie unter Mit Abfrageparametern häufig ausgeführte Abfragen beschleunigen
Hier ist ein Beispiel für die Verwendung eines Parameters in der WHERE
-Klausel,
Abfragedatensätze, die einen bestimmten Wert für LastName
enthalten.
Sie können einen java.sql.PreparedStatement
verwenden.
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
die Datenverkehrsdatenbank
weiterhin Traffic bereitstellt. Schemaaktualisierungen erfordern keine
die Datenbank offline sind und
keine ganzen Tabellen oder Spalten sperren; können Sie fortfahren
Daten während der Schemaaktualisierung in die Datenbank schreiben. Weitere Informationen zu unterstützten
Schemaaktualisierungen und Schemaänderungsleistung in
Schemaaktualisierungen vornehmen
Spalte hinzufügen
Sie können eine Spalte in der Befehlszeile mithilfe der Google Cloud CLI oder programmatischen über den JDBC-Treibertreiber von Spanner.
Ü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-JDBC-Treiber verwenden
Verwenden Sie denexecute(String)
.
der Klasse java.sql.Statement
zum Ändern des Schemas:
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 dies sehen:
Added MarketingBudget column.
DDL-Batch ausführen
Es wird empfohlen, mehrere Schemaänderungen in einem Batch auszuführen. Verwenden Sie die Methode
addBatch(String)
java.sql.Statement
-Methode, um einem Batch mehrere DDL-Anweisungen hinzuzufü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 dies 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 er legt 500000
für den Zeilenschlüssel fest, 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 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.
Legen Sie AutoCommit=false
fest, um Lese-/Schreibtransaktionen 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- und Anfrage-Tags
Transaktions-Tags und Anfrage-Tags verwenden
um Fehler bei Transaktionen und Abfragen
in Spanner zu beheben. Sie können
Transaktions- und Anfrage-Tags in der JDBC mit der TRANSACTION_TAG
und STATEMENT_TAG
Sitzungsvariablen.
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
auf einem java.sql.Connection
fest oder verwenden Sie
die SQL-Anweisung SET TRANSACTION READ ONLY
, um eine schreibgeschützte
Transaktion.
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
Die API teilt eine Abfrage in kleinere Teile oder Partitionen auf und verwendet mehrere
um die Partitionen gleichzeitig abzurufen. Jede Partition wird durch ein
Partitionstoken. Die PartitionQuery API hat eine höhere Latenz als die Standard-API.
Query API verwenden, da sie nur für Bulk-Vorgänge wie das Exportieren oder
das Scannen der gesamten Datenbank.
Daten-Boost können Sie Analyseabfragen und Datenexporte mit nahezu null Auswirkungen auf vorhandene Arbeitslasten in der bereitgestellten Spanner-Instanz. 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 des JDBC-Treibers, siehe:
- GoogleSQL: Data Boost und partitionierte Abfrageanweisungen
- PostgreSQL: Data Boost und partitionierte Abfrageanweisungen
Partitionierte DML
Partitioned Data Manipulation Language (DML) ist die für die folgenden Arten von Bulk-Aktualisierungen und -Löschvorgängen vorgesehen sind:
- Regelmäßige und automatische Speicherbereinigungsvorgänge.
- Backfilling neuer Spalten mit Standardwerten.
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 hier:
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 in Spring Data JPA (GoogleSQL-Dialekt) einbinden
- Spanner in Spring Data JPA (PostgreSQL-Dialekt) einbinden
- Spanner in Hibernate ORM (GoogleSQL-Dialekt) einbinden
- Spanner in Hibernate ORM (PostgreSQL-Dialekt) einbinden
- Weitere Informationen zu JDBC-Befehlen zur Sitzungsverwaltung (GoogleSQL)
- Weitere Informationen zu JDBC-Befehlen zur Sitzungsverwaltung (PostgreSQL)
Informationen zu Anmeldedaten für die Autorisierung und Authentifizierung finden Sie unter Authentifizieren bei Cloud-Dienste mit Clientbibliotheken
Weitere Informationen zu Best Practices für das Schemadesign für Spanner.