PGAdapter starten

Auf dieser Seite wird beschrieben, wie Sie PGAdapter in Spanner starten. Informationen zu PGAdapter finden Sie unter Über PGAdapter. Informationen zum Abrufen der PGAdapter-Binärdatei finden Sie unter PGAdapter herunterladen.

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

Hinweise

Bevor Sie PGAdapter starten, müssen Sie sich auf dem Computer, auf dem PGAdapter ausgeführt wird, mit einem Nutzerkonto oder Dienstkonto authentifiziert haben. Wenn Sie ein Dienstkonto verwenden, müssen Sie den Speicherort der JSON-Schlüsseldatei (der Anmeldedatendatei) kennen. Sie können den Pfad zu den Anmeldedaten dann entweder mit der PGAdapter-Option -c oder durch Festlegen der Umgebungsvariable 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 oder als Verarbeitungsprozess mit Ihrer Java-Anwendung starten. Wenn Sie PGAdapter starten, geben Sie das Projekt, die Spanner-Instanz und die Datenbank an, zu denen 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_NAME -i INSTANCE_NAME -d DATABASE_NAME \
    -c CREDENTIALS_FILE_PATH \
    ADDITIONAL_OPTIONS

Folgende Optionen sind erforderlich:

-p project_name
Name des Projekts, in dem die Spanner-Datenbank ausgeführt wird.
-i instance_name
Name der Spanner-Instanz.
-d database_name
der Name der Datenbank, zu der eine Verbindung hergestellt werden soll.

Folgende Optionen sind optional:

-r databaseRole=database_role
Die 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 Anmeldedaten aus dem Pfad gelesen, der durch die Umgebungsvariable GOOGLE_APPLICATION_CREDENTIALS angegeben wird.

Informationen zum Erstellen eines Dienstkontos und zum Herunterladen einer Schlüsseldatei im JSON-Format finden Sie unter Dienstkonto erstellen.

Gewähren Sie dem Dienstkonto ausreichend Anmeldedaten für den Zugriff auf die Datenbank.

Sie können diese Option weglassen, wenn Sie sich zuerst mit der Google Cloud CLI mit dem folgenden Befehl 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

PostgreSQL-Versionsnummer, die dem Client während der Verbindung zur Verfügung gestellt werden soll. Der Standardwert ist 14,1.

Einige PostgreSQL-Anwendungen und -Treiber ermöglichen je nach 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. Nicht verwenden, wenn PGAdapter im eigenständigen Modus gestartet wird. Nur beim Starten in einem Docker-Container verwenden.

Aus Sicherheitsgründen akzeptiert PGAdapter standardmäßig Verbindungen nur vom 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_NAME -i INSTANCE_NAME -d DATABASE_NAME  \
-c /acct_credentials.json -x OTHER_PGAdapter_OPTIONS

Zusätzlich zu den PGAdapter-Optionen zum Festlegen von Projekt, Instanz, Datenbank und Anmeldedaten sind folgende 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 der Konfiguration von PGAdapter im Container entsprechen. Der Standardwert ist 5432. HOST-PORT ist der Port, den Docker außerhalb des Containers auf Verbindungsanfragen überwachen 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. Sie ordnet den Hostpfad außerhalb des Containers einem Volume (Bereitstellungspunkt) innerhalb des Containers zu. Die Host- und Containerpfade werden durch einen Doppelpunkt (:) getrennt.

Mit dieser Option kann PGAdapter auf die JSON-Anmeldedatendatei außerhalb des Containers zugreifen. Im vorherigen Beispiel verweist die Option -c auf den Bereitstellungspunkt innerhalb des Containers. In diesem Beispiel wird der im Container enthaltene Bereitstellungspunkt /acct_credentials.json genannt. 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 innerhalb des Containers, der dem Hostport zugeordnet ist, PGAdapter nicht als localhost angezeigt wird.

Folgende Optionen sind optional:

-r databaseRole=database_role
Die Datenbankrolle, die für die Sitzung verwendet werden soll. Weitere Informationen finden Sie unter Autorisierung mit PGAdapter.

Im folgenden Beispiel sind der Docker-Port und der Hostport 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 im Sidecar-Muster wird aus den 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 GitHub-Repository für PGAdapter 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 in einem Kubernetes-Cluster verwenden. Kubernetes-Sidecar-Container werden parallel zum Hauptcontainer im Pod ausgeführt.

Die Ausführung von PGAdapter im Sidecar-Muster wird aus den 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 Schritt-für-Schritt-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, achten Sie darauf, dass die Umgebungsvariable GOOGLE_APPLICATION_CREDENTIALS auf den Pfad der Datei mit den Anmeldedaten festgelegt ist.

  1. Fügen Sie Ihrem Projekt google-cloud-spanner-pgadapter als Abhängigkeit hinzu. Weitere Informationen finden Sie unter PGAdapter herunterladen.
  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.

Anleitung zur Ressourcenzuweisung für den PGAdapter-Sidecar-Proxy

Die folgenden Richtlinien können Ihnen helfen, die CPU- und Arbeitsspeicherressourcen für den PGAdapter-Sidecar-Proxy zu konfigurieren. Die optimalen Werte variieren je nach Arbeitslast.

Arbeitsspeicher

Da PGAdapter nicht viele Daten im Cache speichert, ist Arbeitsspeicher erforderlich, um Abfrageergebnisse vom Spanner-gRPC-Format in das PostgreSQL-Wire-Protocol-Format zu konvertieren. Das ist besonders relevant für Arbeitslasten mit großen binären Spalten, da Spanner und PostgreSQL diese Datentypen unterschiedlich verarbeiten.

Verwenden Sie die folgende Formel für die Speicherzuweisung, um zu ermitteln, wie viel Speicherplatz zugewiesen werden soll. Dabei steht <var>number of concurrent connections</var> für die Anzahl der gleichzeitigen Verbindungen, die von Ihrer Anwendung verarbeitet werden:

384 MB + (2 MB * number of concurrent connections)

Wenn Ihre Anwendung beispielsweise 200 gleichzeitige Verbindungen verarbeitet, sollten Sie etwa 784 MB Arbeitsspeicher zuweisen:

384 MB + (2 MB * 200) = 784 MB

Beginnen Sie mit dieser grundlegenden Speicherzuweisung. Behalten Sie die Nutzung unter einer realistischen Last im Blick, um den Wert an Ihre spezifischen Anforderungen anzupassen.

CPU

PGAdapter ist nicht CPU-intensiv. Das liegt daran, dass seine primäre Rolle darin besteht, als Pass-Through-Proxy zu fungieren. Die CPU-Nutzung 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.
  • Zugriffsmuster der Anwendung:Wenn Ihre Anwendung synchron auf Spanner zugreift, ist sie im Leerlauf, während sie auf Daten vom Proxy wartet. In diesem Fall konkurrieren die Anwendung und der Proxy weniger wahrscheinlich um CPU-Ressourcen.

Beginnen Sie mit einer CPU-Zuweisung als Baseline. Überwachen Sie die Nutzung unter einer realistischen Last, um den Wert an Ihre spezifischen Anforderungen anzupassen.

Nächste Schritte