Lernziele
In dieser Anleitung werden Sie durch die folgenden Schritte mit dem lokalen Spanner-PGAdapter-Proxy für PostgreSQL-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 derGoogle 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 PGAdapter-Umgebung vorbereiten
Sie können PostgreSQL-Treiber in Kombination mit PGAdapter verwenden, um eine Verbindung zu Spanner herzustellen. PGAdapter ist ein lokaler Proxy, der das PostgreSQL-Netzwerkprotokoll in das Spanner-gRPC-Protokoll übersetzt.
Für die Ausführung von PGAdapter ist entweder Java oder Docker erforderlich.
Installieren Sie eine der folgenden Optionen auf Ihrem Entwicklungscomputer, falls noch keine davon installiert ist:
- Java 8 JDK (herunterladen).
- Docker (Herunterladen)
Klonen Sie das Repository der Beispiel-App auf Ihren lokalen Computer:
git clone https://github.com/GoogleCloudPlatform/pgadapter.git
Wechseln Sie in das Verzeichnis, das den Spanner-Beispielcode enthält:
cd pgadapter/samples/snippets/psql-snippets
cd pgadapter/samples/snippets/java-snippets mvn package -DskipTests
cd pgadapter/samples/snippets/golang-snippets
cd pgadapter/samples/snippets/nodejs-snippets npm install
cd pgadapter/samples/snippets/python-snippets python -m venv ./venv pip install -r requirements.txt cd samples
cd pgadapter/samples/snippets/dotnet-snippets
cd pgadapter/samples/snippets/php-snippets composer install cd samples
Instanz erstellen
Wenn Sie Spanner zum ersten Mal verwenden, müssen Sie eine Instanz erstellen. Dabei handelt es sich um 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.
Führen Sie den folgenden Befehl aus, um eine 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 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 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 PGAdapter.
Sehen Sie sich den Ordnersamples/snippets
an. Darin wird die Verwendung von Spanner dargestellt. 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.
PGAdapter starten
Starten Sie PGAdapter auf Ihrem lokalen Entwicklungscomputer und weisen Sie ihn auf die von Ihnen erstellte Instanz hin.
Bei den folgenden Befehlen wird davon ausgegangen, dass Sie gcloud auth application-default login
ausgeführt haben.
wget https://storage.googleapis.com/pgadapter-jar-releases/pgadapter.tar.gz \
&& tar -xzvf pgadapter.tar.gz
java -jar pgadapter.jar -i test-instance
docker pull gcr.io/cloud-spanner-pg-adapter/pgadapter
docker run \
--name pgadapter \
--rm -d -p 5432:5432 \
-v "$HOME/.config/gcloud":/gcloud:ro \
--env CLOUDSDK_CONFIG=/gcloud \
gcr.io/cloud-spanner-pg-adapter/pgadapter \
-i test-instance -x
docker pull gcr.io/cloud-spanner-pg-adapter/pgadapter-emulator
docker run \
--name pgadapter-emulator \
--rm -d \
-p 5432:5432 \
-p 9010:9010 \
-p 9020:9020 \
gcr.io/cloud-spanner-pg-adapter/pgadapter-emulator
Dadurch wird PGAdapter mit einem eingebetteten Spanner-Emulator gestartet. Dieser eingebettete Emulator erstellt automatisch jede Spanner-Instanz oder ‑Datenbank, mit der Sie eine Verbindung herstellen, ohne dass Sie sie vorher manuell erstellen müssen.
Wir empfehlen, PGAdapter in der Produktion entweder als Sidecar-Container oder als In-Process-Abhängigkeit auszuführen. Weitere Informationen zur Bereitstellung von PGAdapter in der Produktion finden Sie unter Methode zum Ausführen von PGAdapter auswählen.
Datenbank erstellen
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.
Führen Sie das Beispiel mit dem folgenden Befehl aus:
PGDATABASE=example-db ./create_tables.sh example-db
java -jar target/pgadapter-snippets/pgadapter-samples.jar createtables example-db
go run sample_runner.go createtables example-db
npm start createtables example-db
python create_tables.py example-db
dotnet run createtables example-db
php create_tables.php example-db
Im nächsten Schritt werden Daten in die Datenbank geschrieben.
Verbindung herstellen
Bevor Sie Lese- oder Schreibvorgänge ausführen können, müssen Sie eine Verbindung zu PGAdapter herstellen. Alle Interaktionen mit Spanner müssen über einenConnection
erfolgen. Der Datenbankname wird im Verbindungsstring angegeben.
Führen Sie das Beispiel mit dem folgenden Befehl aus:
PGDATABASE=example-db ./create_connection.sh
java -jar target/pgadapter-snippets/pgadapter-samples.jar createconnection example-db
go run sample_runner.go createconnection example-db
npm start createconnection example-db
python create_connection.py example-db
dotnet run createconnection example-db
php create_connection.php example-db
Daten mit DML schreiben
Sie können Daten mit der Datenbearbeitungssprache (Data Manipulation Language, DML) in eine Lese-Schreib-Transaktion einfügen.
Diese Beispiele zeigen, wie Sie eine DML-Anweisung mit einem PostgreSQL-Treiber in Spanner ausführen.
Führen Sie das Beispiel mit dem folgenden Befehl aus:
PGDATABASE=example-db ./write_data_with_dml.sh
java -jar target/pgadapter-snippets/pgadapter-samples.jar writeusingdml example-db
go run sample_runner.go writeusingdml example-db
npm start writeusingdml example-db
python write_data_with_dml.py example-db
dotnet run writeusingdml example-db
php write_data_with_dml.php example-db
Sie sollten die folgende Antwort sehen:
4 records inserted.
Daten mit einem DML-Batch schreiben
PGAdapter unterstützt die Ausführung von DML-Batches. Wenn Sie mehrere DML-Anweisungen in einem Batch senden, wird die Anzahl der Aufrufe von Spanner reduziert und die Leistung Ihrer Anwendung verbessert.
Führen Sie das Beispiel mit dem folgenden Befehl aus:
PGDATABASE=example-db ./write_data_with_dml_batch.sh
java -jar target/pgadapter-snippets/pgadapter-samples.jar writeusingdmlbatch example-db
go run sample_runner.go writeusingdmlbatch example-db
npm start writeusingdmlbatch example-db
python write_data_with_dml_batch.py example-db
dotnet run writeusingdmlbatch example-db
php write_data_with_dml_batch.php example-db
Hier sollten Sie dies sehen:
3 records inserted.
Daten mit Mutationen schreiben
Sie können Daten auch mithilfe von Mutationen einfügen.
PGAdapter übersetzt den PostgreSQL-Befehl COPY
in Mutationen. Die Verwendung von COPY
ist die effizienteste Methode, um schnell Daten in Ihre Spanner-Datenbank einzufügen.
COPY
-Vorgänge sind standardmäßig atomar. Atomare Vorgänge in Spanner sind durch das Limit für die Commit-Größe begrenzt.
Weitere Informationen finden Sie unter CRUD-Limit.
Diese Beispiele zeigen, wie ein nicht atomarer COPY
-Vorgang ausgeführt wird. So kann der COPY
-Vorgang die Größenbeschränkung für Commits überschreiten.
Führen Sie das Beispiel mit dem folgenden Befehl aus:
PGDATABASE=example-db ./write_data_with_copy.sh
java -jar target/pgadapter-snippets/pgadapter-samples.jar write example-db
go run sample_runner.go write example-db
npm start write example-db
python write_data_with_copy.py example-db
dotnet run write example-db
php write_data_with_copy.php example-db
Hier sollten Sie dies sehen:
Copied 5 singers
Copied 5 albums
Daten mit SQL abfragen
Spanner unterstützt eine SQL-Oberfläche zum Lesen von Daten, auf die Sie in der Befehlszeile mit der Google Cloud CLI oder programmatisch mit einem PostgreSQL-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:
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
PostgreSQL-Treiber verwenden
Als Alternative zum Ausführen einer SQL-Anweisung in der Befehlszeile können Sie die gleiche SQL-Anweisung programmgesteuert mithilfe eines PostgreSQL-Treibers ausführen.
Führen Sie das Beispiel mit dem folgenden Befehl aus:
PGDATABASE=example-db ./query_data.sh
java -jar target/pgadapter-snippets/pgadapter-samples.jar query example-db
go run sample_runner.go query example-db
npm start query example-db
python query_data.py example-db
dotnet run query example-db
php query_data.php 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 in Ihrer Anwendung eine häufig ausgeführte Abfrage vorhanden ist, können Sie die Leistung durch Parameterisierung verbessern. Die resultierende parametrische Abfrage kann zwischengespeichert und wiederverwendet werden, wodurch die Kompilierungskosten reduziert werden. Weitere Informationen finden Sie unter Häufig ausgeführte Abfragen durch Abfrageparameter beschleunigen.
Im Folgenden finden Sie ein Beispiel für die Verwendung eines Parameters in der WHERE
-Klausel zum Abfragen von Datensätzen, die einen bestimmten Wert für LastName
enthalten.
Führen Sie das Beispiel mit dem folgenden Befehl aus:
PGDATABASE=example-db ./query_data_with_parameter.sh
java -jar target/pgadapter-snippets/pgadapter-samples.jar querywithparameter example-db
go run sample_runner.go querywithparameter example-db
npm start querywithparameter example-db
python query_data_with_parameter.py example-db
dotnet run querywithparameter example-db
php query_data_with_parameter.php 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 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 vornehmen.
Spalte hinzufügen
Sie können eine Spalte in der Befehlszeile mithilfe der Google Cloud CLI oder programmatisch mithilfe eines PostgreSQL-Treibers 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 marketing_budget BIGINT'
Hier sollten Sie dies sehen:
Schema updating...done.
PostgreSQL-Treiber verwenden
Führen Sie die DDL-Anweisung mit einem PostgreSQL-Treiber aus, um das Schema zu ändern:
Führen Sie das Beispiel mit dem folgenden Befehl aus:
PGDATABASE=example-db ./add_column.sh
java -jar target/pgadapter-snippets/pgadapter-samples.jar addmarketingbudget example-db
go run sample_runner.go addmarketingbudget example-db
npm start addmarketingbudget example-db
python add_column.py example-db
dotnet run addmarketingbudget example-db
php add_column.php example-db
Hier sollten Sie dies sehen:
Added marketing_budget column
DDL-Batch ausführen
Wir empfehlen, mehrere Schemaänderungen in einem Batch auszuführen.
Sie können mehrere DDL-Anweisungen in einem Batch ausführen, indem Sie die integrierte Batch-Funktion Ihres PostgreSQL-Treibers verwenden, alle DDL-Anweisungen als einen durch Semikolons getrennten SQL-String einreichen oder die Anweisungen START BATCH DDL
und RUN BATCH
verwenden.
Führen Sie das Beispiel mit dem folgenden Befehl aus:
PGDATABASE=example-db ./ddl_batch.sh
java -jar target/pgadapter-snippets/pgadapter-samples.jar ddlbatch example-db
go run sample_runner.go ddlbatch example-db
npm start ddlbatch example-db
python ddl_batch.py example-db
dotnet run ddlbatch example-db
php ddl_batch.php 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.
COPY
in Mutationen. COPY
-Befehle werden standardmäßig in Insert
-Mutationen umgewandelt.
Führen Sie set spanner.copy_upsert=true
aus, um COPY
-Befehle in InsertOrUpdate
-Mutationen zu übersetzen. So können Sie vorhandene Daten in Spanner aktualisieren.
Führen Sie das Beispiel mit dem folgenden Befehl aus:
PGDATABASE=example-db ./update_data_with_copy.sh
java -jar target/pgadapter-snippets/pgadapter-samples.jar update example-db
go run sample_runner.go update example-db
npm start update example-db
python update_data_with_copy.py example-db
dotnet run update example-db
php update_data_with_copy.php example-db
Hier sollten Sie dies sehen:
Updated 2 albums
Sie können auch eine SQL-Abfrage ausführen, um die Werte abzurufen, die Sie gerade geschrieben haben.
Mit diesem Code können Sie die Abfrage ausführen:
Führen Sie die Abfrage mit dem folgenden Befehl aus:
PGDATABASE=example-db ./query_data_with_new_column.sh
java -jar target/pgadapter-snippets/pgadapter-samples.jar querymarketingbudget example-db
go run sample_runner.go querymarketingbudget example-db
npm start querymarketingbudget example-db
python query_data_with_new_column.py example-db
dotnet run querymarketingbudget example-db
php query_data_with_new_column.php 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.
Führen Sie das Beispiel mit dem folgenden Befehl aus:
PGDATABASE=example-db ./update_data_with_transaction.sh
java -jar target/pgadapter-snippets/pgadapter-samples.jar writewithtransactionusingdml example-db
go run sample_runner.go writewithtransactionusingdml example-db
npm start writewithtransactionusingdml example-db
python update_data_with_transaction.py example-db
dotnet run writewithtransactionusingdml example-db
php update_data_with_transaction.php example-db
Hier sollten Sie dies sehen:
Transferred marketing budget from Album 2 to Album 1
Transaktions- und Anfrage-Tags
Verwenden Sie Transaktions- und Anfrage-Tags, um Probleme mit Transaktionen und Abfragen in Spanner zu beheben. Sie können Transaktions- und Anfrage-Tags mit den Sitzungsvariablen SPANNER.TRANSACTION_TAG
und SPANNER.STATEMENT_TAG
festlegen.
Führen Sie das Beispiel mit dem folgenden Befehl aus:
PGDATABASE=example-db ./tags.sh
java -jar target/pgadapter-snippets/pgadapter-samples.jar tags example-db
go run sample_runner.go tags example-db
npm start tags example-db
python tags.py example-db
dotnet run tags example-db
php tags.php 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 die Verbindung als schreibgeschützt 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:
Führen Sie das Beispiel mit dem folgenden Befehl aus:
PGDATABASE=example-db ./read_only_transaction.sh
java -jar target/pgadapter-snippets/pgadapter-samples.jar readonlytransaction example-db
go run sample_runner.go readonlytransaction example-db
npm start readonlytransaction example-db
python read_only_transaction.py example-db
dotnet run readonlytransaction example-db
php read_only_transaction.php 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 unterteilt eine Abfrage in kleinere Teile oder Partitionen 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 den Export oder das 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.
Führen Sie das Beispiel mit dem folgenden Befehl aus:
PGDATABASE=example-db ./data_boost.sh
java -jar target/pgadapter-snippets/pgadapter-samples.jar databoost example-db
go run sample_runner.go databoost example-db
npm start databoost example-db
python data_boost.py example-db
dotnet run databoost example-db
php data_boost.php example-db
Weitere Informationen zum Ausführen partitionierter Abfragen und zur Verwendung von Data Boost mit PGAdapter finden Sie unter Data Boost und Anweisungen für partitionierte Abfragen.
Partitionierte DML
Die partitionierte Datenbearbeitungssprache (DML) wurde für die folgenden Arten von Bulk-Aktualisierungen und -Löschvorgängen entwickelt:
- Regelmäßige und automatische Speicherbereinigungsvorgänge.
- Backfilling neuer Spalten mit Standardwerten.
Führen Sie das Beispiel mit dem folgenden Befehl aus:
PGDATABASE=example-db ./partitioned_dml.sh
java -jar target/pgadapter-snippets/pgadapter-samples.jar partitioneddml example-db
go run sample_runner.go partitioneddml example-db
npm start partitioneddml example-db
python partitioned_dml.py example-db
dotnet run datpartitioneddmlboost example-db
php partitioned_dml.php 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
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
Weitere Informationen zum Zugriff auf Spanner mit einer VM-Instanz
Informationen zu Anmeldedaten für die Autorisierung und Authentifizierung finden Sie unter Mithilfe von Clientbibliotheken bei Cloud-Diensten authentifizieren.