PGAdapter starten

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_CREDENTIALS angegeben 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 login

Weitere 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-PORT im Docker-Container dem Port HOST-PORT außerhalb des Containers zugeordnet. DOCKER-PORT muss mit der Konfiguration von PGAdapter im Container übereinstimmen. Die Standardeinstellung ist 5432. HOST-PORT ist 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 -c auf den Bereitstellungspunkt im Container. In diesem Beispiel wird der Bereitstellungspunkt im Container mit /acct_credentials.json benannt. 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.

  1. Fügen Sie google-cloud-spanner-pgadapter als Abhängigkeit zu Ihrem Projekt hinzu. Weitere Informationen finden Sie unter PGAdapter abrufen.
  2. Erstellen Sie einen Server mit der Klasse com.google.cloud.spanner.pgadapter.ProxyServer.
  3. /**
    * 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 --version

Authentifizierung

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:

  1. Umgebungsvariable GOOGLE_APPLICATION_CREDENTIALS: Verweist auf einen Dienstkontoschlüssel oder eine JSON-Datei mit Anmeldedaten.
  2. Nutzeranmeldedaten aus der Google Cloud CLI: Führen Sie gcloud auth application-default login aus, um diese Anmeldedaten einzurichten.
  3. Angehängtes Dienstkonto: spgc verwendet 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. spgc verwendet diesen Wert, wenn im Befehl nicht -d, --dbname oder --database angegeben 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