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 PortHOST-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. - Erstellen Sie einen Server mit der Klasse
com.google.cloud.spanner.pgadapter.ProxyServer
. psql
mit einer PostgreSQL-Datenbank verbindenJDBC
mit einer PostgreSQL-Datenbank verbindenpgx
mit einer PostgreSQL-Datenbank verbindenpsycopg2
mit einer PostgreSQL-Datenbank verbindenpsycopg3
mit einer PostgreSQL-Datenbank verbindennode-postgres
mit einer PostgreSQL-Datenbank verbinden
/**
* 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.
Nächste Schritte
Sofern nicht anders angegeben, sind die Inhalte dieser Seite unter der Creative Commons Attribution 4.0 License und Codebeispiele unter der Apache 2.0 License lizenziert. Weitere Informationen finden Sie in den Websiterichtlinien von Google Developers. Java ist eine eingetragene Marke von Oracle und/oder seinen Partnern.
Zuletzt aktualisiert: 2024-09-12 (UTC).