PGAdapter starten

Auf dieser Seite wird beschrieben, wie Sie PGAdapter starten. Informationen zu PGAdapter finden Sie unter Über PGAdapter. Informationen zum Abrufen des Binärprogramms „PGAdapter“ finden Sie unter PGAdapter abrufen.

Hinweise

Bevor Sie PGAdapter starten, müssen Sie sich mit einem Nutzer- 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 (die Datei mit den Anmeldedaten) kennen. Sie können dann entweder den Dateipfad mit den Anmeldedaten mit der PGAdapter-Option -c angeben oder die Umgebungsvariable GOOGLE_APPLICATION_CREDENTIALS festlegen.

Weitere Informationen finden Sie unter:

• Authentifizierung
• gcloud CLI autorisieren

Methode zum Ausführen von PGAdapter auswählen

Sie können PGAdapter als eigenständigen Prozess, in einem Docker-Container, in Cloud Run oder in Bearbeitung mit Ihrer Java-Anwendung starten. Wenn Sie PGAdapter starten, geben Sie das Projekt, die Cloud Spanner-Instanz und die Datenbank an, zu der eine Verbindung hergestellt werden soll. Außerdem geben Sie den Pfad für eine JSON-formatierte Anmeldedatendatei (Schlüsseldatei) an.

Eigenständig

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

der Name des Projekts, in dem die Cloud Spanner-Datenbank ausgeführt wird.

-i instance_name

der Name der Cloud Spanner-Instanz.

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

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 auslassen, wenn Sie sich zuerst mit dem folgenden Befehl bei der Google Cloud CLI authentifizieren:

gcloud auth application-default login

Weitere Informationen findest du 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. Cloud 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.

-j translation_file_path

Der vollständige Pfad für eine Datei mit einem JSON-Objekt, um eine SQL-Übersetzung basierend auf dem Austausch regulärer Ausdrücke durchzuführen. Dies ist eine erweiterte Option. Verwenden Sie diese Option, wenn Sie eine Abfrage für den PostgreSQL-Dialekt übersetzen möchten, aber entweder keinen Zugriff auf den Abfragequellcode haben oder den Quellcode nicht ändern möchten.

Zu den Schlüsseln im JSON-Objekt gehören input_pattern, output_pattern und matcher_array. Jedes Element, das mit input_pattern übereinstimmt, wird durch den String output_pattern ersetzt. Gruppen zur Erfassung regulärer Ausdrücke sind zulässig und ihre Reihenfolge wird mithilfe von matcher_array angegeben. Verwenden Sie %s im String output_pattern, um die Ersetzung der Übereinstimmung zu definieren. Legen Sie matcher_array auf [] fest, wenn input_pattern und output_pattern keine Übereinstimmungen angeben.

Alternativ können Sie die Java-Regeln vom Typ matcher.replaceAll() verwenden, um die übereinstimmenden Gruppennamen direkt im String output_pattern zu platzieren. Setzen Sie das Element in geschweifte Klammern mit vorangestelltem Dollarzeichen und lassen Sie matcher_array leer.

Benutzerdefinierte Muster werden internen Übereinstimmungen vorangestellt. Die Escapezeichen und die allgemeine Syntax für reguläre Ausdrücke stimmen mit der Java-Syntax für reguläre Ausdrücke überein. Weitere Informationen zur Syntax von regulären Ausdrücken für Java finden Sie unter Klassenmuster.

Dazu ein Beispiel:

{
  "commands":
    [
      {
        "input_pattern": "^SELECT * FROM users;$",
        "output_pattern": "SELECT 1;",
        "matcher_array": []
      },
      {
        "input_pattern": "^ab(?\\d)(?\\d)$",
        "output_pattern": "second number: %s, first number: %s",
        "matcher_array": ["secondgroup", "firstgroup"]
      },
      {
        "input_pattern": "^cd(?\\d)(?\\d)$",
        "output_pattern": "second number: ${secondgroup}, first number: ${firstgroup}",
        "matcher_array": []
      }
    ]
}
                  

In diesem Beispiel wird davon ausgegangen, dass die Eingabeabfragen so aussehen:

"SELECT * FROM users;"
"ab12"
"cd34"

Die Ausgabeabfragen wären dann:

"SELECT 1;"
"second number: 2, first number: 1"
"second number: 4, first number: 3"

Im folgenden einfachen Beispiel wird PGAdapter im eigenständigen Modus gestartet.

java -jar pgadapter.jar -p my-project -i my-instance -d my-database \
    -c /tmp/credentials.json -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

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 Sie können PGAdapter mit Ihrer Anwendung verpacken und gemeinsam in Cloud Run bereitstellen. In den folgenden Beispielen wird gezeigt, wie Sie mit Ihrer Anwendung und dem PGAdapter ein Docker-Image erstellen, das in Cloud Run bereitgestellt werden kann.

Java

Fügen Sie PGAdapter als Abhängigkeit zu Ihrem Projekt hinzu.

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

Führen Sie PGAdapter während der Verarbeitung mit Ihrer Java-Anwendung aus.

/**
  * Starts PGAdapter in-process and returns a reference to the server.
  * Use this reference to get the port number that was dynamically assigned to
  * PGAdapter, and 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 Cloud Spanner instance that PGAdapter should
  *        connect to
  */
static ProxyServer PGAdapter(String project, String instance) {
  OptionsMetadata options =
      new OptionsMetadata(
          new String[] {
            "-p", project,
            "-i", instance,
            "-s", "0" // Start PGAdapter on any available port.
          });
  ProxyServer server = new ProxyServer(options);
  server.startServer();

  return server;
}
            

Das PGAdapter-GitHub-Repository enthält die vollständige Beispielanwendung zum Erstellen und Bereitstellen einer Java-Anwendung mit PGAdapter für Cloud Run.

Einfach loslegen (Go)

Fügen Sie dem Docker-Container-Image Ihrer Anwendung PGAdapter hinzu.

# Start with a Docker image that includes a JRE. This is needed for PGAdapter.
FROM eclipse-temurin:17-jre AS jre

# Use the official golang image to build the binary.
FROM golang:1.19-buster as builder

# Create and change to the app directory.
WORKDIR /app

# Retrieve application dependencies.
COPY go.* ./
RUN go mod download

# Copy local code to the container image.
COPY . ./

# Build the binary.
RUN go build -v -o server

# Use the official Debian slim image for a lean production container.
FROM debian:buster-slim

# Copy the JRE into the Go Docker image.
ENV JAVA_HOME=/opt/java/openjdk
COPY --from=jre $JAVA_HOME $JAVA_HOME
ENV PATH="${JAVA_HOME}/bin:${PATH}"

# Copy the app-server binary to the production image from the builder stage.
COPY --from=builder /app/server /app/server

# Add the latest version of PGAdapter to the container.
ADD https://storage.googleapis.com/pgadapter-jar-releases/pgadapter.tar.gz /pgadapter.tar.gz
RUN mkdir /pgadapter
RUN tar -xzf /pgadapter.tar.gz -C /pgadapter

# Copy the startup script that will start both PGAdapter and the app-server.
COPY ./startup.sh /startup.sh
RUN chmod +x /startup.sh

ENTRYPOINT ["/bin/bash", "/startup.sh"]
            

Starten Sie PGAdapter zusammen mit Ihrer Anwendung.

#!/bin/bash

# Start PGAdapter in the background.
java -jar /pgadapter/pgadapter.jar -dir= &

# Start the app server as the main application of the Docker container.
exec "/app/server"
            

Das PGAdapter-GitHub-Repository enthält die vollständige Beispielanwendung zum Erstellen und Bereitstellen einer Go-Anwendung mit PGAdapter für Cloud Run.

Node.js

Fügen Sie dem Docker-Container-Image Ihrer Anwendung PGAdapter hinzu.

# Start with a Docker image that includes a JRE. This is needed for PGAdapter.
FROM eclipse-temurin:17-jre AS jre

# Use the official lightweight Node.js image.
FROM node:18-slim

# Copy the JRE into the Node.js image.
ENV JAVA_HOME=/opt/java/openjdk
COPY --from=jre $JAVA_HOME $JAVA_HOME
ENV PATH="${JAVA_HOME}/bin:${PATH}"

# Create and change to the app directory.
WORKDIR /usr/src/app

# Copy application dependency manifests to the container image.
COPY package*.json ./

# Install production dependencies.
RUN npm install --only=production

# Copy local code to the container image.
COPY . ./

# Add the latest version of PGAdapter to the container.
ADD https://storage.googleapis.com/pgadapter-jar-releases/pgadapter.tar.gz /pgadapter.tar.gz
RUN mkdir /pgadapter
RUN tar -xzf /pgadapter.tar.gz -C /pgadapter

# Copy the startup script that will start both PGAdapter and the web service.
COPY ./startup.sh /startup.sh
RUN chmod +x /startup.sh

ENTRYPOINT ["/bin/bash", "/startup.sh"]
            

Starten Sie PGAdapter zusammen mit Ihrer Anwendung.

#!/bin/bash

# Start PGAdapter in the background.
java -jar /pgadapter/pgadapter.jar -dir= &

# Run the web service on container startup.
node index.js
            

Das PGAdapter-GitHub-Repository enthält die vollständige Beispielanwendung zum Erstellen und Bereitstellen einer Node.js-Anwendung mit PGAdapter für Cloud Run.

Python

Fügen Sie dem Docker-Container-Image Ihrer Anwendung PGAdapter hinzu.

# Start with a Docker image that includes a JRE. This is needed for PGAdapter.
FROM eclipse-temurin:17-jre AS jre

# Use the official lightweight Python image.
FROM python:3.11-slim

# Copy the JRE into the Pyton image.
ENV JAVA_HOME=/opt/java/openjdk
COPY --from=jre $JAVA_HOME $JAVA_HOME
ENV PATH="${JAVA_HOME}/bin:${PATH}"

# Allow statements and log messages to immediately appear in the logs
ENV PYTHONUNBUFFERED True

# Copy local code to the container image.
ENV APP_HOME /app
WORKDIR $APP_HOME
COPY . ./

# Install production dependencies.
RUN pip install --no-cache-dir -r requirements.txt

# Add the latest version of PGAdapter to the container.
ADD https://storage.googleapis.com/pgadapter-jar-releases/pgadapter.tar.gz /pgadapter.tar.gz
RUN mkdir /pgadapter
RUN tar -xzf /pgadapter.tar.gz -C /pgadapter

# Copy the startup script that will start both PGAdapter and the web service.
COPY ./startup.sh /startup.sh
RUN chmod +x /startup.sh

ENTRYPOINT ["/bin/bash", "/startup.sh"]
            

Starten Sie PGAdapter zusammen mit Ihrer Anwendung.

#!/bin/bash

# Start PGAdapter in the background.
java -jar /pgadapter/pgadapter.jar -dir= &

# Run the web service on container startup.
port="${PORT:-8080}"
exec gunicorn --bind ":$port" --workers 1 --threads 8 --timeout 0 main:app
            

Das PGAdapter-GitHub-Repository enthält die vollständige Beispielanwendung zum Erstellen und Bereitstellen einer Python-Anwendung mit PGAdapter für Cloud Run.

Sidecar-Proxy

Sie können PGAdapter beispielsweise als Sidecar-Proxy in einem Kubernetes-Cluster verwenden. Kubernetes-Sidecar-Container werden parallel zum Hauptcontainer im Pod ausgeführt.

Aus 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 die Datenbank ist unabhängig von den anderen, wodurch sie robuster sind.
• Da PGAdapter Ressourcen in einem linearen Verhältnis zur Nutzung verbraucht, können Sie mit diesem Muster Ressourcen genauer festlegen 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 PGAdapter-GitHub-Repository 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 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.

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

2. 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 Cloud Spanner instance that PGAdapter should connect to
  * @param credentials the full path of a credentials file that PGAdapter should use
  */
static ProxyServer startPGAdapter(String project, String instance, String credentials) {
  OptionsMetadata options =
      new OptionsMetadata(
          new String[] {
            "-p", project,
            "-i", instance,
            "-c", credentials,
            "-s", "0" // Start PGAdapter on any available port.
          });
  ProxyServer server = new ProxyServer(options);
  server.startServer();

  return server;
}
              

Das PGAdapter-GitHub-Repository enthält eine vollständige Beispielanwendung.

Nächste Schritte

• psql mit einer PostgreSQL-Datenbank verbinden
• JDBC mit einer PostgreSQL-Datenbank verbinden
• pgx mit einer PostgreSQL-Datenbank verbinden
• psycopg2 mit einer PostgreSQL-Datenbank verbinden
• psycopg3 mit einer PostgreSQL-Datenbank verbinden
• node-postgres mit einer PostgreSQL-Datenbank verbinden