Lernziele
In dieser Anleitung werden Sie durch die folgenden Schritte mit der Spanner-Clientbibliothek für PHP geführt:
- 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, einer kostenpflichtigen Komponente von Google Cloud. Informationen zu den Kosten für die Verwendung von 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 PHP-Umgebung vorbereiten
Befolgen Sie die Schritte unter Dienstkonten, um ein Dienstkonto als Ihre Standardanmeldedaten für Anwendungen einzurichten. Beim Ausführen dieser Schritte erhalten Sie sowohl eine Dienstkonto-Schlüsseldatei (im JSON-Format) als auch eine
GOOGLE_APPLICATION_CREDENTIALS
-Umgebungsvariable, mit denen Sie sich bei der Spanner API authentifizieren können.Installieren Sie Folgendes auf Ihrem Entwicklungscomputer, falls nicht bereits vorhanden:
Klonen Sie das Repository der Beispielanwendung auf Ihren lokalen Computer:
git clone https://github.com/GoogleCloudPlatform/php-docs-samples
Sie können das Beispiel auch als ZIP-Datei herunterladen und extrahieren.
Wechseln Sie in das Verzeichnis, das den Spanner-Beispielcode enthält:
cd php-docs-samples/spanner
Installieren Sie die Abhängigkeiten:
composer install
Dadurch wird die Spanner-Clientbibliothek für PHP installiert, die Sie einem beliebigen Projekt durch Ausführen von
composer require google/cloud-spanner
hinzufügen können.
Instanz erstellen
Wenn Sie Spanner zum ersten Mal verwenden, müssen Sie eine Instanz erstellen. Dies ist 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 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 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 Spanner mit PHP.
Betrachten Sie die Funktionen in src/create_database.php
und src/add_column.php
näher. Damit können Sie eine Datenbank erstellen und ein Datenbankschema ändern. Für die Daten wird das auf der Seite Schema und Datenmodell angezeigte Beispielschema verwendet.
Datenbank erstellen
Erstellen Sie eine Datenbank mit dem Namen example-db
in der Instanz test-instance
, indem Sie Folgendes in der Befehlszeile ausführen:
php src/create_database.php test-instance example-db
Hier sollten Sie das sehen:
Created database example-db on instance test-instance
Mit dem folgenden Code werden eine Datenbank und zwei Tabellen in der Datenbank erstellt.
Im nächsten Schritt werden Daten in die Datenbank geschrieben.
Datenbankclient erstellen
Für Lese- und Schreibvorgänge benötigen Sie eine Instanz vonGoogle\Cloud\Spanner\Database
.
Sie können sich eine Database
als Datenbankverbindung vorstellen: Alle Interaktionen mit Spanner müssen eine Database
durchlaufen. In der Regel erstellen Sie Database
beim Start Ihrer Anwendung. Anschließend verwenden Sie Database
zum Lesen, Schreiben und Ausführen von Transaktionen. Jeder Client verwendet Ressourcen in Spanner.
Wenn Sie mehrere Clients in derselben Anwendung erstellen, sollten Sie Database::close
aufrufen, um die Ressourcen des Clients, einschließlich der Netzwerkverbindungen, zu bereinigen, sobald dies nicht mehr benötigt wird.
Weitere Informationen finden Sie in der Referenz zu Database
.
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 die Beispieldatei src/write_data_with_dml.php
aus.
php src/write_data_with_dml.php test-instance example-db
Hier sollten Sie das sehen:
Inserted 4 row(s).
Daten mit Mutationen schreiben
Sie können Daten auch mithilfe von Mutationen einfügen.
Daten werden mithilfe der Methode Database::insertBatch
geschrieben. Mit insertBatch
fügen Sie einer Tabelle neue Zeilen hinzu. Alle Eingaben in einen einzelnen Batch werden in kleinstmöglichen Schritten angewendet.
Dieser Code zeigt, wie die Daten mithilfe von Mutationen geschrieben werden:
Führen Sie die Beispieldatei src/insert_data.php
aus.
php src/insert_data.php test-instance example-db
Hier sollten Sie das sehen:
Inserted data.
Daten mit SQL abfragen
Spanner unterstützt eine native SQL-Schnittstelle zum Lesen von Daten, auf die Sie über die Google Cloud CLI oder über die Spanner-Clientbibliothek für PHP programmatisch 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 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-Clientbibliothek für PHP verwenden
Neben der Ausführung einer SQL-Anweisung in der Befehlszeile können Sie die gleiche SQL-Anweisung programmatisch mithilfe der Spanner-Clientbibliothek für PHP ausführen.
Führen Sie mitDatabase::execute()
die SQL-Abfrage aus.
So geben Sie die Abfrage aus und greifen auf die Daten zu:
Führen Sie die Beispieldatei src/query_data.php
aus.
php src/query_data.php test-instance example-db
Sie sollten folgendes Ergebnis sehen:
SingerId: 2, AlbumId: 2, AlbumTitle: Forever Hold Your Peace
SingerId: 1, AlbumId: 2, AlbumTitle: Go, Go, Go
SingerId: 2, AlbumId: 1, AlbumTitle: Green
SingerId: 2, AlbumId: 3, AlbumTitle: Terrified
SingerId: 1, AlbumId: 1, AlbumTitle: Total Junk
Die Ergebnisse werden nicht unbedingt in dieser Reihenfolge angezeigt. Wenn Sie ein sortiertes Ergebnis benötigen, verwenden Sie die Klausel ORDER BY
, wie unter Best Practices für SQL erläutert.
Abfrage mit einem SQL-Parameter
Wenn Ihre Anwendung eine häufig ausgeführte Abfrage hat, können Sie die Leistung durch Parametrisierung verbessern. Die resultierende parametrische Abfrage kann im Cache gespeichert und wiederverwendet werden, wodurch die Kompilierungskosten reduziert werden. Weitere Informationen finden Sie unter Abfrageparameter verwenden, um häufig ausgeführte Abfragen zu beschleunigen.
Hier ist ein Beispiel für die Verwendung eines Parameters in der WHERE
-Klausel zur Abfrage von Einträgen, die einen bestimmten Wert für LastName
enthalten.
Führen Sie die Beispieldatei src/query_data_with_parameter.php
aus.
php src/query_data_with_parameter.php test-instance example-db
Sie sollten folgendes Ergebnis sehen:
SingerId: 12, FirstName: Melissa, LastName: Garcia
Daten mit der Lese-API auslesen
Neben der SQL-Schnittstelle von Spanner unterstützt Spanner auch eine Leseschnittstelle.
Verwenden Sie Database::read()
, um Zeilen aus der Datenbank zu lesen. Verwenden Sie ein KeySet
-Objekt, um eine Sammlung von zu lesenden Schlüsseln und Schlüsselbereichen zu definieren.
So lesen Sie die Daten aus:
Führen Sie das Beispiel in der Datei read_data.php
aus.
php read_data.php test-instance example-db
Die Ausgabe sollte etwa so aussehen:
SingerId: 1, AlbumId: 1, AlbumTitle: Total Junk
SingerId: 1, AlbumId: 2, AlbumTitle: Go, Go, Go
SingerId: 2, AlbumId: 1, AlbumTitle: Green
SingerId: 2, AlbumId: 2, AlbumTitle: Forever Hold your Peace
SingerId: 2, AlbumId: 3, AlbumTitle: 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. Spanner unterstützt Schemaaktualisierungen für Datenbanken, während über die Datenbank weiterhin Traffic bereitgestellt wird. 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 über die Befehlszeile mithilfe der Google Cloud CLI oder programmatisch mit der Spanner-Clientbibliothek für PHP hinzufügen.
Über die Befehlszeile
Verwenden Sie den folgenden Befehl ALTER TABLE
, um die neue Spalte zur Tabelle hinzuzufügen:
Google-Standard-SQL
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 MarketingBudget BIGINT'
Hier sollten Sie das sehen:
Schema updating...done.
Spanner-Clientbibliothek für PHP verwenden
Verwenden Sie Database::updateDdl
, um das Schema zu ändern:
Führen Sie die Beispieldatei src/add_column.php
aus.
php src/add_column.php test-instance example-db
Hier sollten Sie das sehen:
Added the 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 die Beispieldatei src/update_data.php
aus.
php src/update_data.php test-instance example-db
Hier sollten Sie das sehen:
Updated data.
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ühren Sie die Beispieldatei src/query-data-with-new-column.php
aus, um diese Abfrage auszuführen.
php src/query_data_with_new_column.php test-instance example-db
Hier sollten Sie das sehen:
SingerId: 1, AlbumId: 1, MarketingBudget: 100000
SingerId: 1, AlbumId: 2, MarketingBudget: 0
SingerId: 2, AlbumId: 1, MarketingBudget: 0
SingerId: 2, AlbumId: 2, MarketingBudget: 500000
SingerId: 2, AlbumId: 3, MarketingBudget: 0
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 die Beispieldatei src/write_data_with_dml_transaction.php
aus.
php src/write_data_with_dml_transaction.php test-instance example-db
Hier sollten Sie das sehen:
Transaction complete.
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 unterstützt Spanner das Hinzufügen eines Index, während die Datenbank weiterhin Traffic verarbeitet. Spanner fügt den Index automatisch mit Ihren vorhandenen Daten ein. 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 Spanner diesen automatisch für SQL-Abfragen, die mit dem Index 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 über die gcloud-Befehlszeile oder programmatisch mithilfe der Spanner-Clientbibliothek für PHP 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 das sehen:
Schema updating...done.
Spanner-Clientbibliothek für PHP verwenden
Verwenden Sie Database::updateDdl
, um einen Index hinzuzufügen:
Führen Sie die Beispieldatei src/create_index.php
aus.
php src/create_index.php 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 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 Database::read
.
Führen Sie die Beispieldatei src/read_data_with_index.php
aus.
php src/read_data_with_index.php test-instance example-db
Hier sollten Sie das sehen:
AlbumId: 2, AlbumTitle: Forever Hold your Peace
AlbumId: 2, AlbumTitle: Go, Go, Go
AlbumId: 1, AlbumTitle: Green
AlbumId: 3, AlbumTitle: Terrified
AlbumId: 1, AlbumTitle: Total Junk
Index für Lesevorgänge nur mit Index hinzufügen
Vielleicht haben Sie bemerkt, dass im obigen Beispiel die Spalte MarketingBudget
nicht gelesen wird. Das liegt daran, dass die Leseschnittstelle von Spanner die Möglichkeit zum Zusammenführen eines Index mit einer Datentabelle zum Ermitteln von Werten, die nicht im Index gespeichert sind, nicht unterstützt.
Erstellen Sie eine alternative Definition von AlbumsByAlbumTitle
, die eine Kopie von MarketingBudget
im Index speichert.
Über die Befehlszeile
Google-Standard-SQL
gcloud spanner databases ddl update example-db --instance=test-instance \
--ddl='CREATE INDEX AlbumsByAlbumTitle2 ON Albums(AlbumTitle) STORING (MarketingBudget)
PostgreSQL
gcloud spanner databases ddl update example-db --instance=test-instance \
--ddl='CREATE INDEX AlbumsByAlbumTitle2 ON Albums(AlbumTitle) INCLUDE (MarketingBudget)
Das Hinzufügen eines Index kann einige Minuten dauern. Nachdem der Index hinzugefügt wurde, sollte Folgendes angezeigt werden:
Schema updating...done.
Spanner-Clientbibliothek für PHP verwenden
Verwenden SieDatabase::updateDdl
, um einen Index mit einer STORING
-Klausel hinzuzufügen:
Führen Sie die Beispieldatei src/create_storing_index.php
aus.
php src/create_storing_index.php test-instance example-db
Hier sollten Sie das sehen:
Added the 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 die Beispieldatei src/read_data_with_storing_index.php
aus.
php src/read_data_with_storing_index.php test-instance example-db
Die Ausgabe sollte etwa so aussehen:
AlbumId: 2, AlbumTitle: Forever Hold your Peace, MarketingBudget: 300000
AlbumId: 2, AlbumTitle: Go, Go, Go, MarketingBudget: 0
AlbumId: 1, AlbumTitle: Green, MarketingBudget: 0
AlbumId: 3, AlbumTitle: Terrified, MarketingBudget: 0
AlbumId: 1, AlbumTitle: Total Junk, MarketingBudget: 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 Snapshot
-Objekt . Mit der Methode Database::snapshot
können Sie ein Snapshot
-Objekt abrufen.
So werden eine Abfrage und ein Lesevorgang in derselben schreibgeschützten Transaktion ausgeführt:
Führen Sie die Beispieldatei src/read_only_transaction.php
aus.
php src/read_only_transaction.php test-instance example-db
Die Ausgabe sollte etwa so aussehen:
Results from first read:
SingerId: 2, AlbumId: 2, AlbumTitle: Forever Hold Your Peace
SingerId: 1, AlbumId: 2, AlbumTitle: Go, Go, Go
SingerId: 2, AlbumId: 1, AlbumTitle: Green
SingerId: 2, AlbumId: 3, AlbumTitle: Terrified
SingerId: 1, AlbumId: 1, AlbumTitle: Total Junk
Results from second read:
SingerId: 1, AlbumId: 1, AlbumTitle: Total Junk
SingerId: 1, AlbumId: 2, AlbumTitle: Go, Go, Go
SingerId: 2, AlbumId: 1, AlbumTitle: Green
SingerId: 2, AlbumId: 2, AlbumTitle: Forever Hold Your Peace
SingerId: 2, AlbumId: 3, AlbumTitle: Terrified
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
Auf eine VM-Instanz zugreifen: Erstellen Sie eine VM-Instanz mit Zugriff auf die Spanner-Datenbank.
Anmeldedaten für die Autorisierung und Authentifizierung: Siehe Erste Schritte bei der Authentifizierung