Auf dieser Seite wird erläutert, wie Sie PGAdapter in Spanner starten. Weitere Informationen zu PGAdapter finden Sie unter Informationen zu PGAdapter. Informationen zum Abrufen der PGAdapter-Binärdatei finden Sie unter PGAdapter abrufen.
Sie können PGAdapter auf folgende Arten starten:
- Als eigenständiger Prozess
- In einem Docker-Container
- In Cloud Run
- PGAdapter als Sidecar-Proxy verwenden (z. B. in einem Kubernetes-Cluster)
- In-Process mit Ihrer Java-Anwendung
- PostgreSQL-Befehlszeilentools mit dem Spanner PG Connector (
spgc) ausführen
Hinweis
Bevor Sie PGAdapter starten, müssen Sie sich mit einem Nutzerkonto oder Dienstkonto auf dem Computer authentifizieren, auf dem PGAdapter ausgeführt wird. Wenn Sie ein Dienstkonto verwenden, müssen Sie den Speicherort der JSON-Schlüsseldatei (der Datei mit den Anmeldedaten) kennen. Anschließend können Sie den Pfad zu den Anmeldedaten entweder mit der PGAdapter-Option -c oder durch Festlegen der Umgebungsvariablen GOOGLE_APPLICATION_CREDENTIALS angeben.
Weitere Informationen finden Sie unter:
Methode zum Ausführen von PGAdapter auswählen
Sie können PGAdapter als eigenständigen Prozess, in einem Docker-Container, in Cloud Run, prozessintern mit Ihrer Java-Anwendung oder mit dem Spanner PG Connector (spgc) starten. Wenn Sie PGAdapter starten, geben Sie das Projekt, die Spanner-Instanz-ID und die Datenbank an, zu der eine Verbindung hergestellt werden soll. Sie können auch den Pfad für eine JSON-formatierte Datei mit Anmeldedaten (Schlüsseldatei) angeben.
Eigenständig
Laden Sie PGAdapter mit dem folgenden Befehl herunter.
wget https://storage.googleapis.com/pgadapter-jar-releases/pgadapter.tar.gz \ && tar -xzvf pgadapter.tar.gz
Starten Sie PGAdapter mit dem folgenden Befehl.
java -jar pgadapter.jar -p PROJECT_ID -i INSTANCE_ID -d DATABASE_ID \ -c CREDENTIALS_FILE_PATH \ ADDITIONAL_OPTIONS
Folgende Optionen sind erforderlich:
-
-p project_id - ID des Projekts, in dem die Spanner-Datenbank ausgeführt wird.
-
-i instance_id - Spanner-Instanz-ID.
-
-d database_ID - ID der Spanner-Datenbank, zu der eine Verbindung hergestellt werden soll.
Folgende Optionen sind optional:
-r databaseRole=database_role- Datenbankrolle, die für die Sitzung verwendet werden soll. Weitere Informationen finden Sie unter Autorisierung mit PGAdapter.
-
-c credentials_file_path - : Vollständiger Pfad für die Schlüsseldatei, die die Anmeldedaten des Dienstkontos im JSON-Format enthält. Wenn diese Option nicht festgelegt ist, werden die Anmeldedaten aus dem Pfad gelesen, der durch die Umgebungsvariable
GOOGLE_APPLICATION_CREDENTIALSangegeben ist.Informationen zum Erstellen eines Dienstkontos und zum Herunterladen einer JSON-formatierten Schlüsseldatei finden Sie unter Dienstkonto erstellen.
Achten Sie darauf, dass Sie dem Dienstkonto ausreichende Anmeldedaten für den Zugriff auf die Datenbank gewähren.
Sie können diese Option weglassen, wenn Sie sich zuerst mit dem folgenden Befehl bei der Google Cloud CLI authentifizieren:
gcloud auth application-default loginWeitere Informationen finden Sie unter Authentifizierung und Autorisierung einrichten.
-
-s port - Port, den PGAdapter überwacht. Der Standardwert ist 5432 (der PostgreSQL-Standardport).
-
-v version_number -
Versionsnummer von PostgreSQL, die dem Client während der Verbindung angezeigt werden soll. Der Standardwert ist 14.1.
Einige PostgreSQL-Anwendungen und -Treiber aktivieren je nach dieser Versionsnummer zusätzliche Funktionen. Spanner unterstützt diese Funktionen möglicherweise nicht. Eine vollständige Liste der unterstützten Clients finden Sie unter Treiber und Clients.
-
-x -
Aktivieren Sie Verbindungen von anderen Hosts als localhost. Verwenden Sie diese Option nicht, wenn Sie PGAdapter im eigenständigen Modus starten. Nur beim Starten in einem Docker-Container verwenden.
Standardmäßig akzeptiert PGAdapter aus Sicherheitsgründen nur Verbindungen von localhost.
Im folgenden Beispiel wird PGAdapter im eigenständigen Modus auf Port 5432 mit den Standardanmeldedaten für Anwendungen gestartet.
java -jar pgadapter.jar \ -p my-project \ -i my-instance \ -d my-database \ -s 5432
Docker
Starten Sie PGAdapter mit dem folgenden Befehl.
docker run -d -p HOST-PORT:DOCKER-PORT \ -v CREDENTIALS_FILE_PATH:/acct_credentials.json \ gcr.io/cloud-spanner-pg-adapter/pgadapter:latest \ -p PROJECT_ID -i INSTANCE_ID -d DATABASE_ID \ -c /acct_credentials.json -x OTHER_PGAdapter_OPTIONS
Zusätzlich zu den PGAdapter-Optionen zum Angeben von Projekt, Instanz, Datenbank und Anmeldedaten sind die folgenden Optionen erforderlich:
-
-p 127.0.0.1:HOST-PORT:DOCKER-PORT -
Mit dieser Docker-Option wird der Port
DOCKER-PORTim Docker-Container dem PortHOST-PORTaußerhalb des Containers zugeordnet.DOCKER-PORTmuss mit der Konfiguration von PGAdapter im Container übereinstimmen. Die Standardeinstellung ist 5432.HOST-PORTist der Port, an dem Docker außerhalb des Containers auf Verbindungsanfragen warten soll. Es muss immer ein verfügbarer Port auf localhost sein.Weitere Informationen finden Sie in der Docker-Dokumentation unter Port veröffentlichen oder freigeben (-p, --expose).
-v CREDENTIALS_FILE_PATH:in_container_mount_point-
Diese Docker-Option bindet ein freigegebenes Volume. Der Hostpfad außerhalb des Containers wird einem Volume (Bereitstellungspunkt) innerhalb des Containers zugeordnet. Die Host- und Containerpfade werden durch einen Doppelpunkt (:) getrennt.
Mit dieser Option kann PGAdapter auf die JSON-Anmeldedatendatei zugreifen, die sich außerhalb des Containers befindet. Im vorherigen Beispiel verweist die Option
-cauf den Bereitstellungspunkt im Container. In diesem Beispiel wird der Bereitstellungspunkt im Container mit/acct_credentials.jsonbenannt. Sie können ihm einen beliebigen Namen geben.Weitere Informationen finden Sie in der Docker-Dokumentation unter VOLUME (freigegebene Dateisysteme).
-
-x -
Aktivieren Sie Verbindungen von anderen Hosts als localhost. Dies ist erforderlich, da der Port im Container, der dem Hostport zugeordnet ist, für PGAdapter nicht als Localhost angezeigt wird.
Folgende Optionen sind optional:
-r databaseRole=database_role- Datenbankrolle, die für die Sitzung verwendet werden soll. Weitere Informationen finden Sie unter Autorisierung mit PGAdapter.
Im folgenden Beispiel sind sowohl der Docker-Port als auch der Host-Port auf den Standardport 5432 des PostgreSQL-Datenbankdienstes festgelegt.
docker run -d -p 127.0.0.1:5432:5432 \ -v /tmp/credentials.json:/acct_credentials.json \ gcr.io/cloud-spanner-pg-adapter/pgadapter:latest \ -p my_project -i my_instance -d my_database \ -c /acct_credentials.json -x
Cloud Run
Sie können PGAdapter nicht als eigenständigen Dienst in Cloud Run bereitstellen, aber als Sidecar-Proxy.
Die Ausführung von PGAdapter in einem Sidecar-Muster wird aus folgenden Gründen gegenüber der Ausführung als separater Dienst empfohlen:- Verhindert einen Single Point of Failure. Der Zugriff jeder Anwendung auf Ihre Datenbank ist unabhängig von den anderen, was die Ausfallsicherheit erhöht.
- Die Anzahl der PGAdapter-Instanzen wird automatisch linear mit der Anzahl der Anwendungsinstanzen skaliert.
Das PGAdapter-GitHub-Repository enthält mehrere funktionierende Beispielanwendungen, die Cloud Run und PGAdapter als Sidecar-Proxy für verschiedene Programmiersprachen verwenden.
Die folgende Konfigurationsdatei zeigt, wie Sie PGAdapter als Sidecar-Proxy zu Cloud Run hinzufügen:
apiVersion: serving.knative.dev/v1 kind: Service metadata: annotations: # This example uses an in-memory volume for Unix domain sockets. # This is a Cloud Run beta feature. run.googleapis.com/launch-stage: BETA name: pgadapter-sidecar-example spec: template: metadata: annotations: run.googleapis.com/execution-environment: gen1 # This registers 'pgadapter' as a dependency of 'app' and ensures that pgadapter starts # before the app container. run.googleapis.com/container-dependencies: '{"app":["pgadapter"]}' spec: # Create an in-memory volume that can be used for Unix domain sockets. volumes: - name: sockets-dir emptyDir: # This directory contains the virtual socket files that are used to # communicate between your application and PGAdapter. sizeLimit: 50Mi medium: Memory containers: # This is the main application container. - name: app # Example: europe-north1-docker.pkg.dev/my-test-project/cloud-run-source-deploy/pgadapter-sidecar-example image: MY-REGION.pkg.dev/MY-PROJECT/cloud-run-source-deploy/pgadapter-sidecar-example # The PGADAPTER_HOST variable is set to point to /sockets, which is the shared in-memory # volume that is used for Unix domain sockets. env: - name: SPANNER_PROJECT value: my-project - name: SPANNER_INSTANCE value: my-instance - name: SPANNER_DATABASE value: my-database - name: PGADAPTER_HOST value: /sockets - name: PGADAPTER_PORT value: "5432" ports: - containerPort: 8080 volumeMounts: - mountPath: /sockets name: sockets-dir # This is the PGAdapter sidecar container. - name: pgadapter image: gcr.io/cloud-spanner-pg-adapter/pgadapter volumeMounts: - mountPath: /sockets name: sockets-dir args: - -dir /sockets - -x # Add a startup probe that checks that PGAdapter is listening on port 5432. startupProbe: initialDelaySeconds: 10 timeoutSeconds: 10 periodSeconds: 10 failureThreshold: 3 tcpSocket: port: 5432
Sidecar-Proxy
Sie können PGAdapter als Sidecar-Proxy verwenden, z. B. in einem Kubernetes-Cluster. Kubernetes-Sidecar-Container werden parallel zum Hauptcontainer im Pod ausgeführt.
Die Ausführung von PGAdapter in einem Sidecar-Muster wird aus folgenden Gründen gegenüber der Ausführung als separater Dienst empfohlen:
- Verhindert einen Single Point of Failure. Der Zugriff jeder Anwendung auf Ihre Datenbank ist unabhängig von den anderen, was die Ausfallsicherheit erhöht.
- Da PGAdapter Ressourcen linear zur Nutzung verbraucht, können Sie mit diesem Muster Ressourcen genauer bestimmen und entsprechend der Skalierung Ihrer Anwendungen anfordern.
Die folgende Konfigurationsdatei zeigt, wie Sie PGAdapter als Sidecar-Proxy zu Ihrem Kubernetes-Cluster hinzufügen:
containers: - name: pgadapter image: gcr.io/cloud-spanner-pg-adapter/pgadapter ports: - containerPort: 5432 args: - "-p my-project" - "-i my-instance" - "-d my-database" - "-x" resources: requests: # PGAdapter's memory use scales linearly with the number of active # connections. Fewer open connections will use less memory. Adjust # this value based on your application's requirements. memory: "512Mi" # PGAdapter's CPU use scales linearly with the amount of IO between # the database and the application. Adjust this value based on your # application's requirements. cpu: "1"
Das PGAdapter-GitHub-Repository enthält eine detaillierte Anleitung und eine Beispielanwendung. Dieses Beispiel enthält eine Anleitung zur Verwendung von Workload Identity Federation for GKE mit PGAdapter.
Java-In-Process
Erstellen und starten Sie eine PGAdapter-Instanz mit Ihrem Java-Code. Dies ist die empfohlene Einrichtung für Java-Anwendungen.
Wenn Sie ein Dienstkonto für die Authentifizierung verwenden, muss die Umgebungsvariable GOOGLE_APPLICATION_CREDENTIALS auf den Pfad der Datei mit den Anmeldedaten festgelegt sein.
-
Fügen Sie
google-cloud-spanner-pgadapterals Abhängigkeit zu Ihrem Projekt hinzu. Weitere Informationen finden Sie unter PGAdapter abrufen. - Erstellen Sie einen Server mit der Klasse
com.google.cloud.spanner.pgadapter.ProxyServer.
/**
* Starts PGAdapter in-process and returns a reference to the server. Use this reference to
* gracefully shut down the server when your application shuts down.
*
* @param project the Google Cloud project that PGAdapter should connect to
* @param instance the Spanner instance that PGAdapter should connect to
* @param credentialsFile the full path of a credentials file that PGAdapter should use, or
* null if PGAdapter should use the application default credentials
*/
static Server startPGAdapter(String project, String instance, String credentialsFile) {
OptionsMetadata.Builder builder =
OptionsMetadata.newBuilder()
.setProject(project)
.setInstance(instance)
// Start PGAdapter on any available port.
.setPort(0);
if (credentialsFile != null) {
builder.setCredentialsFile(credentialsFile);
}
ProxyServer server = new ProxyServer(builder.build());
server.startServer();
server.awaitRunning();
return new PGAdapter(server);
}Das PGAdapter-GitHub-Repository enthält eine vollständige Beispielanwendung.
Spanner PG Connector (spgc)
spanner-pg-connector (mit dem Alias spgc) ist ein eigenständiger CLI-Wrapper zum Ausführen von PostgreSQL-Befehlszeilentools (wie psql oder pg_dump) für Spanner. Es bündelt PGAdapter und eine minimale Java-Laufzeit, sodass Sie Java oder Docker nicht lokal installieren müssen. Wenn Sie einen Befehl ausführen, startet spgc PGAdapter im Hintergrund auf einem dynamisch zugewiesenen localhost-Port und legt PGHOST und PGPORT fest. Anschließend wird der PostgreSQL-Clientbefehl ausgeführt und PGAdapter beendet, wenn der Befehl beendet wird.
spgc mit dem Installationsskript installieren
Standardmäßig lädt das Installationsprogramm die neueste Version in ~/.spanner-pg-connector herunter und fügt dieses Verzeichnis Ihrem PATH hinzu.
Führen Sie den folgenden Befehl aus, um spgc unter Linux (x86_64) oder macOS (aarch64 oder x86_64) zu installieren:
curl -fsSL https://raw.githubusercontent.com/GoogleCloudPlatform/pgadapter/postgresql-dialect/spanner-pg-connector/install.sh | sh
Führen Sie den folgenden Befehl aus, um spgc unter Windows (x86_64, PowerShell) zu installieren:
irm https://raw.githubusercontent.com/GoogleCloudPlatform/pgadapter/postgresql-dialect/spanner-pg-connector/install.ps1 | iex
Führen Sie den folgenden Befehl aus, um die Installation unter Linux oder macOS mit VERSION und INSTALL_DIR anzupassen:
curl -fsSL https://raw.githubusercontent.com/GoogleCloudPlatform/pgadapter/postgresql-dialect/spanner-pg-connector/install.sh \ | VERSION=VERSION INSTALL_DIR="INSTALL_DIR" sh
Führen Sie den folgenden Befehl aus, um die Installation unter Windows (PowerShell) mit VERSION und INSTALL_DIR anzupassen:
$env:VERSION = "VERSION"; $env:INSTALL_DIR = "INSTALL_DIR"; irm https://raw.githubusercontent.com/GoogleCloudPlatform/pgadapter/postgresql-dialect/spanner-pg-connector/install.ps1 | iex
spgc manuell installieren (ohne Installationsskript)
Sie können das Release-Archiv auch direkt aus Artifact Registry herunterladen und extrahieren und dann das extrahierte Verzeichnis zu Ihrem PATH hinzufügen.
Das Archiv enthält sowohl spanner-pg-connector als auch spgc.
Führen Sie die folgenden Befehle aus, um spgc manuell unter Linux oder macOS zu installieren. Setzen Sie dabei PLATFORM auf linux-x64, mac-aarch64 oder mac-x64:
VERSION=VERSION PLATFORM=PLATFORM # linux-x64, mac-aarch64, or mac-x64 INSTALL_DIR="INSTALL_DIR" mkdir -p "${INSTALL_DIR}" curl -fsSL "https://artifactregistry.googleapis.com/v1/projects/cloud-spanner-pg-adapter/locations/us/repositories/spanner-pg-connector/files/spanner-pg-connector:${VERSION}:spanner-pg-connector-${PLATFORM}.tar.gz:download?alt=media" \ | tar -xz -C "${INSTALL_DIR}" export PATH="${INSTALL_DIR}:$PATH"
Führen Sie die folgenden Befehle aus, um spgc manuell unter Windows (PowerShell) zu installieren:
$Version = "VERSION" $InstallDir = "INSTALL_DIR" $ZipPath = Join-Path $env:TEMP "spanner-pg-connector-windows-x64.zip" New-Item -ItemType Directory -Path $InstallDir -Force | Out-Null Invoke-RestMethod -Uri "https://artifactregistry.googleapis.com/v1/projects/cloud-spanner-pg-adapter/locations/us/repositories/spanner-pg-connector/files/spanner-pg-connector:${Version}:spanner-pg-connector-windows-x64.zip:download?alt=media" -OutFile $ZipPath Expand-Archive -Path $ZipPath -DestinationPath $InstallDir -Force $env:PATH = "$env:PATH;$InstallDir"
Wenn Sie spgc auf Ihrem PATH über Terminal-Sitzungen hinweg beibehalten möchten, fügen Sie das Installationsverzeichnis Ihrem Shell-Profil (z. B. ~/.bashrc oder ~/.zshrc unter Linux und macOS) oder Ihrer Nutzer-Path-Umgebungsvariablen unter Windows hinzu.
Prüfen Sie die Installation, indem Sie die spgc-Version abfragen:
spgc --versionAuthentifizierung
spgc erfordert keinen PostgreSQL-Nutzernamen oder kein Passwort zwischen dem Clienttool und dem lokalen PGAdapter-Proxy. Zur Authentifizierung bei Spanner verwendet spgc die Google CloudStandardanmeldedaten für Anwendungen (Application Default Credentials, ADC) in der folgenden Reihenfolge:
- Umgebungsvariable
GOOGLE_APPLICATION_CREDENTIALS: Verweist auf einen Dienstkontoschlüssel oder eine JSON-Datei mit Anmeldedaten. - Nutzeranmeldedaten aus der Google Cloud CLI: Führen Sie
gcloud auth application-default loginaus, um diese Anmeldedaten einzurichten. - Angehängtes Dienstkonto:
spgcverwendet das angehängte Dienstkonto, wenn Sie es in Google Cloud -Umgebungen wie Compute Engine, Cloud Shell, Cloud Workstations, Cloud Run oder Workload Identity Federation for GKE ausführen.
Wenn Sie eine Verbindung zum Spanner-Emulator (SPANNER_EMULATOR_HOST) herstellen, deaktiviert spgc die Authentifizierung.
Nutzung und Umgebungsvariablen
Übergeben Sie den Clientbefehl und seine Argumente direkt an spgc (oder spanner-pg-connector):
spgc psql -d "projects/PROJECT_ID/instances/INSTANCE_ID/databases/DATABASE_ID"
Sie können das Projekt, die Instanz, die Standarddatenbank oder den Emulator auch mithilfe von Umgebungsvariablen konfigurieren:
GOOGLE_CLOUD_PROJECT- Google Cloud -Projekt-ID.
SPANNER_INSTANCE- Spanner-Instanz-ID.
SPANNER_DATABASE- Standard-Spanner-Datenbank-ID.
spgcverwendet diesen Wert, wenn im Befehl nicht-d,--dbnameoder--databaseangegeben ist. SPANNER_EMULATOR_HOST- Wenn festgelegt, wird eine Verbindung zum Spanner-Emulator unter
HOST:PORT(z. B.localhost:9010) anstelle von Spanner hergestellt. Heben Sie die Festlegung dieser Variable auf, wenn Sie eine Verbindung zu Spanner herstellen. GOOGLE_APPLICATION_CREDENTIALS- Optionaler Pfad zu einer JSON-Datei mit Google Cloud -Anmeldedaten.
In den folgenden Beispielen wird gezeigt, wie Sie spgc mit Umgebungsvariablen ausführen:
export GOOGLE_CLOUD_PROJECT=PROJECT_ID export SPANNER_INSTANCE=INSTANCE_ID # Start an interactive psql session spgc psql -d DATABASE_ID # Run a single query spgc psql -d DATABASE_ID -c "SELECT 1" # Connect to the Spanner emulator SPANNER_EMULATOR_HOST=localhost:9010 spgc psql -d test-database
Anleitung zur Ressourcenzuweisung für den PGAdapter-Sidecar-Proxy
Die folgenden Richtlinien können Ihnen bei der Konfiguration der CPU- und Arbeitsspeicherressourcen für den PGAdapter-Sidecar-Proxy helfen. Die optimalen Werte variieren je nach Arbeitslast.
Arbeitsspeicher
Da PGAdapter nicht viele Daten im Cache speichert, benötigt er Arbeitsspeicher, um Abfrageergebnisse vom Spanner-gRPC-Format in das PostgreSQL-Wire-Protokollformat zu konvertieren. Dies ist besonders für Arbeitslasten mit großen Binärspalten relevant, da Spanner und PostgreSQL diese Datentypen unterschiedlich verarbeiten.
Verwenden Sie die folgende Formel für die Arbeitsspeicherzuweisung, um zu bestimmen, wie viel Arbeitsspeicher zugewiesen werden soll. Dabei ist <var>number of concurrent connections</var> die Anzahl der gleichzeitigen Verbindungen, die Ihre Anwendung verarbeitet:
384 MB + (2 MB * number of concurrent connections)
Wenn Ihre Anwendung beispielsweise 200 gleichzeitige Verbindungen verarbeitet, weisen Sie etwa 784 MB Arbeitsspeicher zu:
384 MB + (2 MB * 200) = 784 MB
Beginnen Sie mit dieser grundlegenden Arbeitsspeicherzuweisung. Überwachen Sie die Nutzung unter einer realistischen Last, um den Wert für Ihre spezifischen Anforderungen zu optimieren.
CPU
PGAdapter ist nicht CPU-intensiv. Das liegt daran, dass seine Hauptaufgabe darin besteht, als Pass-Through-Proxy zu fungieren. Die CPU-Auslastung steigt jedoch mit der Menge der gesendeten und empfangenen Daten.
Berücksichtigen Sie bei der Zuweisung von CPU die folgenden Faktoren:
- Arbeitslast: Anwendungen, die Abfragen ausführen, die große Datenmengen zurückgeben, erfordern mehr CPU-Leistung pro Verbindung als Anwendungen, die nur wenige Zeilen und Spalten zurückgeben.
- Anwendungszugriffsmuster: Wenn Ihre Anwendung synchron auf Spanner zugreift, ist sie inaktiv, während sie auf Daten vom Proxy wartet. In diesem Fall ist es weniger wahrscheinlich, dass die Anwendung und der Proxy um CPU-Ressourcen konkurrieren.
Beginnen Sie mit einer Baseline-CPU-Zuweisung. Überwachen Sie die Nutzung unter einer realistischen Last, um den Wert für Ihre spezifischen Anforderungen zu optimieren.
Nächste Schritte
psqlmit einer PostgreSQL-Datenbank verbindenJDBCmit einer PostgreSQL-Datenbank verbindenpgxmit einer PostgreSQL-Datenbank verbindenpsycopg2mit einer PostgreSQL-Datenbank verbindenpsycopg3mit einer PostgreSQL-Datenbank verbindennode-postgresmit einer PostgreSQL-Datenbank verbinden- Übersicht über die für Spanner unterstützten Treiber und ORMs