Questa pagina spiega come avviare PGAdapter in Spanner. Per apprendere informazioni su PGAdapter, consulta Informazioni su PGAdapter. Per ottenere il file binario PGAdapter, vedi Scarica PGAdapter.
Puoi avviare PGAdapter nei seguenti modi:
- Come processo autonomo
- All'interno di un container Docker
- In Cloud Run
- Utilizzo di PGAdapter come proxy sidecar (ad esempio in un cluster Kubernetes)
- In elaborazione con la tua applicazione Java
Prima di iniziare
Prima di avviare PGAdapter, assicurati di aver eseguito l'autenticazione con
un account utente o di servizio sulla macchina in cui PGAdapter
in esecuzione. Se utilizzi un account di servizio, devi conoscere la posizione del file della chiave JSON (il file delle credenziali). Puoi
quindi specifica il percorso delle credenziali con il PGAdapter -c
oppure impostando la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS
.
Per ulteriori informazioni, vedi:
Scegli un metodo per eseguire PGAdapter
Puoi avviare PGAdapter come processo autonomo, all'interno di un container, su Cloud Run o in elaborazione con la tua applicazione Java. Quando inizi PGAdapter, specifichi il progetto, l'istanza Spanner e il database a cui connetterti. Puoi anche specificare il percorso di un file delle credenziali (file della chiave) in formato JSON.
Autonoma
Scarica PGAdapter con il seguente comando.
wget https://storage.googleapis.com/pgadapter-jar-releases/pgadapter.tar.gz \ && tar -xzvf pgadapter.tar.gz
Avvia PGAdapter con il seguente comando.
java -jar pgadapter.jar -p PROJECT_NAME -i INSTANCE_NAME -d DATABASE_NAME \ -c CREDENTIALS_FILE_PATH \ ADDITIONAL_OPTIONS
Sono necessarie le seguenti opzioni:
-
-p project_name
- Nome del progetto in cui è in esecuzione il database Spanner.
-
-i instance_name
- Nome istanza Spanner.
-
-d database_name
- Nome del database a cui connettersi.
Le seguenti opzioni sono facoltative:
-r databaseRole=database_role
- Ruolo del database da utilizzare per la sessione. Per ulteriori informazioni, vedi Autorizzazione con PGAdapter.
-
-c credentials_file_path
- Percorso completo del file delle chiavi contenente le credenziali dell'account di servizio
in formato JSON. Se questa opzione non è impostata, le credenziali vengono lette dal
percorso specificato dalla variabile di ambiente
GOOGLE_APPLICATION_CREDENTIALS
.Per scoprire come creare un account di servizio e scaricare un file della chiave in formato JSON, consulta Creare un account di servizio.
Assicurati di concedere all'account di servizio credenziali sufficienti per per accedere al database.
Puoi omettere questa opzione se ti autentichi prima con l'interfaccia a riga di comando Google Cloud con il seguente comando:
gcloud auth application-default login
Per ulteriori informazioni, consulta Configurare l'autenticazione e l'autorizzazione.
-
-s port
- Porta su cui PGAdapter è in ascolto. Il valore predefinito è 5432 (la porta PostgreSQL predefinita).
-
-v version_number
-
Numero di versione di PostgreSQL da esporre al client durante la connessione. Il valore predefinito è 14,1
Alcune applicazioni e driver PostgreSQL consentono funzioni aggiuntive, a seconda di questo numero di versione. Spanner potrebbe non supportare queste funzionalità. Per un elenco completo dei client supportati, consulta Driver e client.
-
-x
-
Abilita connessioni da host diversi da localhost. Non utilizzare quando si avvia PGAdapter in modalità autonoma. Utilizza solo quando si avvia all'interno di un container Docker.
Per impostazione predefinita, come misura di sicurezza, PGAdapter accetta connessioni solo da localhost.
Il seguente semplice esempio avvia PGAdapter in modalità autonoma sulla porta 5432 utilizzando le credenziali predefinite dell'applicazione.
java -jar pgadapter.jar \ -p my-project \ -i my-instance \ -d my-database \ -s 5432
Docker
Avvia PGAdapter con il seguente comando.
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
Oltre alle opzioni di PGAdapter per specificare il progetto, istanza, database e credenziali, le seguenti opzioni sono obbligatorio:
-
-p 127.0.0.1:HOST-PORT:DOCKER-PORT
-
Questa opzione Docker mappa la porta
DOCKER-PORT
all'interno del container Docker alla portaHOST-PORT
all'esterno del container.DOCKER-PORT
deve corrispondere alla configurazione di PGAdapter all'interno del contenitore. Il valore predefinito è 5432.HOST-PORT
è la porta su cui Docker deve rimanere in ascolto al di fuori del contenitore per le richieste di connessione. Deve sempre essere una porta disponibile su localhost.Per ulteriori informazioni, consulta Pubblicare o esporre la porta (-p, --expose) nella documentazione Docker.
-v CREDENTIALS_FILE_PATH:in_container_mount_point
-
Questa opzione Docker esegue il montaggio di un volume condiviso. L'host viene mappato percorso esterno del container a un volume (punto di montaggio) all'interno del container. I percorsi dell'host e del container sono separati dai due punti (:).
Questa opzione consente a PGAdapter di accedere al file JSON del file di credenziali esterno al container. Nell'esempio precedente, l'opzione
-c
fa riferimento al punto di montaggio all'interno del contenitore. Questo esempio nomina il punto di montaggio all'interno del contenitore/acct_credentials.json
. Puoi dare un nome tutto ciò che desideri.Per ulteriori informazioni, vedi VOLUME (file system condivisi) nella documentazione Docker.
-
-x
-
Attiva le connessioni da host diversi da localhost. Questo è necessario perché la porta interna del contenitore mappata alla porta dell'host non viene visualizzata come localhost da PGAdapter.
Le seguenti opzioni sono facoltative:
-r databaseRole=database_role
- Ruolo di database da utilizzare per la sessione. Per ulteriori informazioni, consulta Autorizzazione con PGAdapter.
Nell'esempio seguente, la porta Docker e la porta host sono entrambe impostate sulla porta predefinita del servizio di database PostgreSQL 5432.
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
Non puoi eseguire il deployment di PGAdapter come servizio autonomo su Cloud Run, ma puoi eseguirlo come proxy sidecar.
È consigliabile eseguire PGAdapter in un pattern collaterale la sua esecuzione come servizio separato per i seguenti motivi:- Impedisce un single point of failure. L'accesso di ogni applicazione al database è indipendente dalle altre, il che le rende più resilienti.
- Il numero di istanze PGAdapter scala automaticamente in modo lineare con il numero di istanze dell'applicazione.
Il repository GitHub di PGAdapter contiene diverse applicazioni di esempio funzionanti che utilizzano Cloud Run e PGAdapter come proxy sidecar per vari linguaggi di programmazione.
Il seguente file di configurazione mostra come aggiungere PGAdapter come proxy sidecar a Cloud Run:
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
Proxy sidecar
Puoi utilizzare PGAdapter come proxy sidecar, ad esempio, in un cluster Kubernetes. I container sidecar Kubernetes vengono eseguiti in parallelo con il container principale nel pod.
È consigliabile eseguire PGAdapter in un pattern sidecar anziché come servizio separato per i seguenti motivi:
- Impedisce un single point of failure. L'accesso di ogni applicazione al tuo database è indipendente degli altri, il che li rende più resilienti.
- Poiché PGAdapter consuma risorse in relazione lineare all'uso, questo pattern ti consente di definire con maggiore precisione l'ambito e la richiesta di risorse da abbinare per le tue applicazioni in termini di scalabilità.
Il seguente file di configurazione mostra come aggiungere PGAdapter come proxy sidecar al tuo cluster Kubernetes:
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"
Il repository GitHub di PGAdapter contiene una guida passo passo e un'applicazione di esempio. Questo esempio include le istruzioni per l'utilizzo della Federazione delle identità per i carichi di lavoro per GKE con PGAdapter.
Java in-process
Crea e avvia un'istanza PGAdapter con il codice Java. Questa è la configurazione consigliata per le applicazioni Java.
Se utilizzi un account di servizio per l'autenticazione, assicurati che:
la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS
è impostato sul percorso del file delle credenziali.
-
Aggiungi
google-cloud-spanner-pgadapter
come dipendenza al tuo progetto. Per maggiori dettagli, vedi Ottenere PGAdapter. - Crea un server utilizzando la classe
com.google.cloud.spanner.pgadapter.ProxyServer
. - Collegare
psql
a un database PostgreSQL - Connetti
JDBC
a un database PostgreSQL - Connetti
pgx
a un database PostgreSQL - Connetti
psycopg2
a un database PostgreSQL - Collegare
psycopg3
a un database PostgreSQL - Connetti
node-postgres
a un database PostgreSQL
/**
* 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);
}
Il repository GitHub di PGAdapter contiene un'applicazione di esempio completa.
Passaggi successivi
Salvo quando diversamente specificato, i contenuti di questa pagina sono concessi in base alla licenza Creative Commons Attribution 4.0, mentre gli esempi di codice sono concessi in base alla licenza Apache 2.0. Per ulteriori dettagli, consulta le norme del sito di Google Developers. Java è un marchio registrato di Oracle e/o delle sue consociate.
Ultimo aggiornamento 2024-10-10 UTC.