Diese Seite wurde von der Cloud Translation API übersetzt.

PGAdapter starten

Auf dieser Seite wird erläutert, wie Sie PGAdapter in Spanner starten. Weitere Informationen zu PGAdapter finden Sie unter PGAdapter. Informationen zum Abrufen des Binärprogramms „PGAdapter“ 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)
Wird in Ihrer Java-Anwendung verarbeitet

Hinweise

Bevor Sie PGAdapter starten, müssen Sie sich mit einem Nutzer- oder Dienstkonto auf dem Computer authentifiziert haben, auf dem PGAdapter ausgeführt wird. Wenn Sie ein Dienstkonto verwenden, müssen Sie den Speicherort der JSON-Schlüsseldatei (die Datei mit den Anmeldedaten) kennen. Sie können den Anmeldedatenpfad 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 im Prozess 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 Anmeldedatendatei (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

Für die Sitzung zu verwendende Datenbankrolle. 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 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

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 Features 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 einfachen Beispiel wird PGAdapter im eigenständigen Modus auf Port 5432 mit den standardmäßigen Anwendungsanmeldedaten 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. Er 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: Für die Sitzung zu verwendende Datenbankrolle. 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.

Es empfiehlt sich, PGAdapter in einem Sidecar-Muster auszuführen, anstatt es als separaten Dienst auszuführen. Dies hat folgende Gründe:

Verhindert einen Single Point of Failure. Der Zugriff jeder Anwendung auf Ihre Datenbank ist unabhängig von den anderen, sodass sie robuster sind.
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 verwenden, und zwar für verschiedene Programmiersprachen.

Die folgende Konfigurationsdatei zeigt, wie PGAdapter als Sidecar-Proxy zu Cloud Run hinzugefügt wird:

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

Beiwagen-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.

Es empfiehlt sich, PGAdapter in einem Sidecar-Muster auszuführen, anstatt es als separaten Dienst auszuführen. Dies hat folgende Gründe:

Verhindert einen Single Point of Failure. Der Zugriff jeder Anwendung auf Ihre Datenbank ist unabhängig von den anderen, sodass sie robuster sind.
Da PGAdapter Ressourcen in einem linearen Verhältnis zur Nutzung verbraucht, können Sie mit diesem Muster Ressourcen genauer eingrenzen und anfordern, damit sie Ihren Anwendungen bei der Skalierung entsprechen.

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 GitHub-Repository für PGAdapter enthält eine detaillierte Anleitung und eine Beispielanwendung. Dieses Beispiel enthält eine Anleitung zur Verwendung von Workload Identity mit PGAdapter.

Java In-Process

Erstellen und starten Sie eine PGAdapter-Instanz mit Ihrem Java-Code. Diese Konfiguration wird für Java-Anwendungen empfohlen.

Wenn Sie ein Dienstkonto zur Authentifizierung verwenden, achten Sie darauf, dass die Umgebungsvariable GOOGLE_APPLICATION_CREDENTIALS auf den Pfad der Datei mit den Anmeldedaten festgelegt ist.

Fügen Sie Ihrem Projekt google-cloud-spanner-pgadapter als Abhängigkeit hinzu. Weitere Informationen finden Sie unter PGAdapter herunterladen.

<dependency>
  <groupId>com.google.cloud</groupId>
  <artifactId>google-cloud-spanner-pgadapter</artifactId>
  <version>0.33.2</version>
</dependency>

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 GitHub-Repository für PGAdapter enthält eine vollständige Beispielanwendung.

PGAdapter starten

Hinweise

Methode zum Ausführen von PGAdapter auswählen

Eigenständig

Folgende Optionen sind erforderlich:

Folgende Optionen sind optional:

Docker

Cloud Run

Beiwagen-Proxy

Java In-Process

Nächste Schritte