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 Informationen zu PGAdapter finden Sie unter Informationen zu PGAdapter Informationen zum Abrufen des PGAdapter-Binärprogramms findest du unter Fordern Sie PGAdapter an.

Sie können PGAdapter so starten:

Als eigenständiger Prozess
In einem Docker-Container
In Cloud Run
PGAdapter als Sidecar-Proxy verwenden (z. B. in einer Kubernetes-Umgebung) Cluster)
In Bearbeitung mit Ihrer Java-Anwendung

Hinweise

Bevor Sie PGAdapter starten, müssen Sie sich mit entweder ein Nutzerkonto oder ein Dienstkonto auf dem Computer, auf dem PGAdapter installiert ist, 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 Geben Sie dann entweder den Pfad für die Anmeldedaten mit dem PGAdapter -c an oder die Umgebungsvariable GOOGLE_APPLICATION_CREDENTIALS festlegen.

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: Spanner-Instanzname.
-d database_name: der Name der 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 Anmeldedaten aus dem Pfad gelesen, der durch die Umgebungsvariable GOOGLE_APPLICATION_CREDENTIALS angegeben wird.

Hier erfahren Sie, wie Sie ein Dienstkonto erstellen und einen Schlüssel im JSON-Format herunterladen. erhalten 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 über die Google Cloud CLI authentifizieren mit dem folgenden Befehl:

gcloud auth application-default login

Weitere Informationen finden Sie unter Richten Sie Authentifizierung und Autorisierung ein.

-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. Weitere Informationen finden Sie unter . Treiber und Clients für eine vollständige Liste der unterstützten 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 gestartet mit den Standardanmeldedaten für Anwendungen an Port 5432 an.

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. Es ist der Standardwert 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: 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 bereitstellen auf Cloud Run. Sie können ihn jedoch als Sidecar-Proxy bereitstellen.

Die Ausführung von PGAdapter in einem Sidecar-Muster es aus folgenden Gründen als separaten Dienst auszuführen:

Verhindert einen Single Point of Failure. Der Zugriff jeder Anwendung Ihrer Datenbank sind unabhängig von den anderen, belastbar sind.
Die Anzahl der PGAdapter-Instanzen wird automatisch skaliert linear mit der Anzahl der Anwendungsinstanzen.

Das GitHub-Repository von PGAdapter enthält mehrere funktionierende Beispielanwendungen, die Cloud Run und PGAdapter als Sidecar-Proxy verwenden, für verschiedene Programmiersprachen.

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

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.

Aus den folgenden Gründen wird empfohlen, PGAdapter in einem Sidecar-Muster auszuführen, anstatt es als separaten Dienst auszuführen:

Verhindert einen Single Point of Failure. Der Zugriff jeder Anwendung auf Ihre Datenbank ist unabhängig der anderen und macht sie widerstandsfähiger.
Da der 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 GitHub-Repository für PGAdapter enthält eine detaillierte Anleitung und eine Beispielanwendung. Dieses Beispiel enthält eine Anleitung zur Verwendung der Workload Identity-Föderation für 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.

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

<dependency>
  <groupId>com.google.cloud</groupId>
  <artifactId>google-cloud-spanner-pgadapter</artifactId>
  <version>0.37.0</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

Sidecar-Proxy

Java In-Process

Nächste Schritte