Questa pagina spiega come avviare PGAdapter in Spanner. Per scoprire di più su PGAdapter, consulta Informazioni su PGAdapter. Per ottenere il file binario di PGAdapter, consulta Scarica PGAdapter.
Puoi avviare PGAdapter nei seguenti modi:
- Come processo autonomo
- All'interno di un container Docker
- Su Cloud Run
- Utilizzo di PGAdapter come proxy sidecar (ad esempio in un cluster Kubernetes)
- In-process con l'applicazione Java
- Utilizzo di Spanner PG Connector (
spgc) per eseguire gli strumenti a riga di comando PostgreSQL
Prima di iniziare
Prima di avviare PGAdapter, assicurati di aver eseguito l'autenticazione con un account utente o un account di servizio sulla macchina su cui verrà eseguito PGAdapter. Se utilizzi un account di servizio, devi conoscere la posizione del file della chiave JSON (il file delle credenziali). Puoi quindi specificare il percorso delle credenziali con l'opzione -c di PGAdapter o impostando la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS.
Per saperne di più, vedi:
Scegli un metodo per eseguire PGAdapter
Puoi avviare PGAdapter come processo autonomo, all'interno di un container Docker, su Cloud Run, in-process con la tua applicazione Java o utilizzando Spanner PG Connector (spgc). Quando avvii PGAdapter, specifichi il progetto, l'ID istanza Spanner e il database a cui connetterti. Puoi anche specificare il percorso di un file delle credenziali in formato JSON (file della chiave).
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_ID -i INSTANCE_ID -d DATABASE_ID \ -c CREDENTIALS_FILE_PATH \ ADDITIONAL_OPTIONS
Sono richieste le seguenti opzioni:
-
-p project_id - ID del progetto in cui è in esecuzione il database Spanner.
-
-i instance_id - ID istanza Spanner.
-
-d database_ID - ID del database Spanner a cui connettersi.
Le seguenti opzioni sono facoltative:
-r databaseRole=database_role- Ruolo del database da utilizzare per la sessione. Per saperne di più, consulta 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 di chiavi in formato JSON, consulta Creazione di un service account.
Assicurati di concedere al account di servizio credenziali sufficienti per accedere al database.
Puoi omettere questa opzione se esegui prima l'autenticazione con Google Cloud CLI con il seguente comando:
gcloud auth application-default loginPer saperne di più, consulta Configura l'autenticazione e l'autorizzazione.
-
-s port - Porta su cui PGAdapter rimane 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 abilitano funzionalità aggiuntive in base a questo numero di versione. Spanner potrebbe non supportare queste funzionalità. Consulta Driver e client per un elenco completo dei client supportati.
-
-x -
Abilita le connessioni da host diversi da localhost. Non utilizzare quando avvii PGAdapter in modalità autonoma. Utilizzalo solo quando l'avvio avviene all'interno di un container Docker.
Per impostazione predefinita, come misura di sicurezza, PGAdapter accetta connessioni solo da localhost.
L'esempio seguente 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_ID -i INSTANCE_ID -d DATABASE_ID \ -c /acct_credentials.json -x OTHER_PGAdapter_OPTIONS
Oltre alle opzioni di PGAdapter per specificare progetto, istanza, database e credenziali, sono necessarie le seguenti opzioni:
-
-p 127.0.0.1:HOST-PORT:DOCKER-PORT -
Questa opzione Docker mappa la porta
DOCKER-PORTall'interno del container Docker alla portaHOST-PORTall'esterno del container.DOCKER-PORTdeve corrispondere alla configurazione di PGAdapter all'interno del container. Il valore predefinito è 5432.HOST-PORTè la porta su cui Docker deve rimanere in ascolto all'esterno del container per le richieste di connessione. Deve essere sempre una porta disponibile su localhost.Per saperne di più, consulta Pubblica o esponi la porta (-p, --expose) nella documentazione di Docker.
-v CREDENTIALS_FILE_PATH:in_container_mount_point-
Questa opzione Docker monta un volume condiviso. Mappa il percorso host all'esterno del container a un volume (punto di montaggio) all'interno del container. I percorsi dell'host e del container sono separati da due punti (:).
Questa opzione consente a PGAdapter di accedere al file delle credenziali JSON che si trova all'esterno del container. Nell'esempio precedente, l'opzione
-cfa riferimento al punto di montaggio all'interno del container. In questo esempio, il punto di montaggio all'interno del container è denominato/acct_credentials.json. Puoi assegnargli il nome che preferisci.Per saperne di più, consulta VOLUME (file system condivisi) nella documentazione di Docker.
-
-x -
Abilita le connessioni da host diversi da localhost. Questo è necessario perché la porta all'interno del container mappata alla porta host non viene visualizzata da PGAdapter come localhost.
Le seguenti opzioni sono facoltative:
-r databaseRole=database_role- Ruolo del database da utilizzare per la sessione. Per saperne di più, consulta Autorizzazione con PGAdapter.
Nell'esempio seguente, la porta Docker e la porta host sono entrambe impostate sulla porta predefinita 5432 del servizio di database PostgreSQL.
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.
L'esecuzione di PGAdapter in un pattern sidecar è consigliata rispetto all'esecuzione come servizio separato per i seguenti motivi:- Previene 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 viene scalato 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 di Kubernetes vengono eseguiti in parallelo con il container principale nel pod.
L'esecuzione di PGAdapter in un pattern sidecar è consigliata rispetto all'esecuzione come servizio separato per i seguenti motivi:
- Previene un single point of failure. L'accesso di ogni applicazione al database è indipendente dagli altri, il che le rende più resilienti.
- Poiché PGAdapter consuma risorse in relazione lineare all'utilizzo, questo pattern ti consente di definire l'ambito e richiedere le risorse in modo più accurato per adattarle alle tue applicazioni man mano che scalano.
Il seguente file di configurazione mostra come aggiungere PGAdapter come proxy sidecar al 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 istruzioni per l'utilizzo di Workload Identity Federation for GKE con PGAdapter.
Java in-process
Crea e avvia un'istanza PGAdapter con il tuo 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 sia impostata sul percorso del file delle credenziali.
-
Aggiungi
google-cloud-spanner-pgadaptercome dipendenza al tuo progetto. Per maggiori dettagli, vedi Scarica PGAdapter. - Crea un server utilizzando la classe
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);
}Il repository GitHub di PGAdapter contiene un'applicazione di esempio completa.
Connettore Spanner PG (spgc)
spanner-pg-connector (con alias spgc) è un wrapper CLI autonomo per l'esecuzione di strumenti a riga di comando PostgreSQL (come psql o pg_dump) su Spanner. Raggruppa PGAdapter e un runtime Java minimo, quindi non è necessario installare Java o Docker localmente. Quando esegui un comando, spgc avvia PGAdapter in background su una porta localhost assegnata in modo dinamico e imposta PGHOST e PGPORT. Quindi esegue il comando del client PostgreSQL e arresta PGAdapter quando il comando viene chiuso.
Installa spgc utilizzando lo script del programma di installazione
Per impostazione predefinita, il programma di installazione scarica l'ultima release in ~/.spanner-pg-connector e aggiunge la directory a PATH.
Per installare spgc su Linux (x86_64) o macOS (aarch64 o x86_64), esegui questo comando:
curl -fsSL https://raw.githubusercontent.com/GoogleCloudPlatform/pgadapter/postgresql-dialect/spanner-pg-connector/install.sh | sh
Per installare spgc su Windows (x86_64, PowerShell),
esegui questo comando:
irm https://raw.githubusercontent.com/GoogleCloudPlatform/pgadapter/postgresql-dialect/spanner-pg-connector/install.ps1 | iex
Per personalizzare l'installazione su Linux o macOS con VERSION
e INSTALL_DIR, esegui questo comando:
curl -fsSL https://raw.githubusercontent.com/GoogleCloudPlatform/pgadapter/postgresql-dialect/spanner-pg-connector/install.sh \ | VERSION=VERSION INSTALL_DIR="INSTALL_DIR" sh
Per personalizzare l'installazione su Windows (PowerShell) con VERSION e INSTALL_DIR, esegui questo comando:
$env:VERSION = "VERSION"; $env:INSTALL_DIR = "INSTALL_DIR"; irm https://raw.githubusercontent.com/GoogleCloudPlatform/pgadapter/postgresql-dialect/spanner-pg-connector/install.ps1 | iex
Installa spgc manualmente (senza lo script del programma di installazione)
Puoi anche scaricare ed estrarre l'archivio della release direttamente da Artifact Registry, quindi aggiungere la directory estratta alla tua PATH.
L'archivio include sia spanner-pg-connector sia
spgc.
Per installare spgc manualmente su Linux o macOS, esegui i seguenti comandi (imposta PLATFORM su linux-x64, mac-aarch64 o mac-x64):
VERSION=VERSION PLATFORM=PLATFORM # linux-x64, mac-aarch64, or mac-x64 INSTALL_DIR="INSTALL_DIR" mkdir -p "${INSTALL_DIR}" curl -fsSL "https://artifactregistry.googleapis.com/v1/projects/cloud-spanner-pg-adapter/locations/us/repositories/spanner-pg-connector/files/spanner-pg-connector:${VERSION}:spanner-pg-connector-${PLATFORM}.tar.gz:download?alt=media" \ | tar -xz -C "${INSTALL_DIR}" export PATH="${INSTALL_DIR}:$PATH"
Per installare spgc manualmente su Windows (PowerShell), esegui i seguenti comandi:
$Version = "VERSION" $InstallDir = "INSTALL_DIR" $ZipPath = Join-Path $env:TEMP "spanner-pg-connector-windows-x64.zip" New-Item -ItemType Directory -Path $InstallDir -Force | Out-Null Invoke-RestMethod -Uri "https://artifactregistry.googleapis.com/v1/projects/cloud-spanner-pg-adapter/locations/us/repositories/spanner-pg-connector/files/spanner-pg-connector:${Version}:spanner-pg-connector-windows-x64.zip:download?alt=media" -OutFile $ZipPath Expand-Archive -Path $ZipPath -DestinationPath $InstallDir -Force $env:PATH = "$env:PATH;$InstallDir"
Per mantenere spgc su PATH tra le sessioni del terminale, aggiungi la directory di installazione al tuo profilo della shell (ad esempio ~/.bashrc o ~/.zshrc su Linux e macOS) o alla variabile di ambiente Path dell'utente su Windows.
Per verificare l'installazione, controlla la versione di spgc:
spgc --versionAutenticazione
spgc non richiede un nome utente o una password PostgreSQL tra lo strumento client e il proxy PGAdapter locale. Per eseguire l'autenticazione in Spanner, spgc utilizza le Google CloudCredenziali predefinite dell'applicazione (ADC) nel seguente ordine:
- Variabile di ambiente
GOOGLE_APPLICATION_CREDENTIALS: punta a un file JSON di credenziali o chiave dell'account di servizio. - Credenziali utente di Google Cloud CLI: esegui
gcloud auth application-default loginper configurare queste credenziali. - Service account collegato:
spgcutilizza il account di servizio collegato quando lo esegui in ambienti Google Cloud come Compute Engine, Cloud Shell, Cloud Workstations, Cloud Run o Workload Identity Federation for GKE.
Quando ti connetti all'emulatore Spanner (SPANNER_EMULATOR_HOST), spgc disattiva l'autenticazione.
Utilizzo e variabili di ambiente
Passa il comando client e i relativi argomenti direttamente a spgc
(o spanner-pg-connector):
spgc psql -d "projects/PROJECT_ID/instances/INSTANCE_ID/databases/DATABASE_ID"
Puoi anche configurare il progetto, l'istanza, il database predefinito o l'emulatore utilizzando le variabili di ambiente:
GOOGLE_CLOUD_PROJECT- Google Cloud ID progetto.
SPANNER_INSTANCE- ID istanza Spanner.
SPANNER_DATABASE- ID database Spanner predefinito.
spgcutilizza questo valore se il comando non specifica-d,--dbnameo--database. SPANNER_EMULATOR_HOST- Se impostato, si connette all'emulatore Spanner all'indirizzo
HOST:PORT(ad esempio,localhost:9010) anziché a Spanner. Annulla l'impostazione di questa variabile quando ti connetti a Spanner. GOOGLE_APPLICATION_CREDENTIALS- Percorso facoltativo di un file JSON Google Cloud delle credenziali.
I seguenti esempi mostrano come eseguire spgc con le variabili di ambiente:
export GOOGLE_CLOUD_PROJECT=PROJECT_ID export SPANNER_INSTANCE=INSTANCE_ID # Start an interactive psql session spgc psql -d DATABASE_ID # Run a single query spgc psql -d DATABASE_ID -c "SELECT 1" # Connect to the Spanner emulator SPANNER_EMULATOR_HOST=localhost:9010 spgc psql -d test-database
Indicazioni per l'allocazione delle risorse per il proxy sidecar PGAdapter
Le seguenti linee guida possono aiutarti a configurare le risorse di CPU e memoria per il proxy sidecar PGAdapter. I valori ottimali variano a seconda del tuo workload specifico.
Memoria
Poiché PGAdapter non memorizza nella cache molti dati, richiede memoria per convertire i risultati delle query dal formato gRPC di Spanner al formato del protocollo di rete PostgreSQL. Questo è particolarmente importante per i workload con colonne binarie di grandi dimensioni, perché Spanner e PostgreSQL gestiscono questi tipi di dati in modo diverso.
Per determinare la quantità di memoria da allocare, utilizza la seguente formula per l'allocazione della memoria, dove <var>number of concurrent connections</var> è il numero di connessioni simultanee gestite dalla tua applicazione:
384 MB + (2 MB * number of concurrent connections)
Ad esempio, se la tua applicazione gestisce 200 connessioni contemporanee, alloca circa 784 MB di memoria:
384 MB + (2 MB * 200) = 784 MB
Inizia con questa allocazione della memoria di base. Monitora l'utilizzo con un carico realistico per ottimizzare il valore in base alle tue esigenze specifiche.
CPU
PGAdapter non utilizza molta CPU. Questo perché il suo ruolo principale è quello di fungere da proxy pass-through. Tuttavia, l'utilizzo della CPU aumenta con la quantità di dati inviati e ricevuti.
Quando allochi la CPU, tieni presente i seguenti fattori:
- Workload: le applicazioni che eseguono query che restituiscono grandi quantità di dati richiedono più potenza della CPU per connessione rispetto a quelle che restituiscono solo poche righe e colonne.
- Pattern di accesso dell'applicazione: se l'applicazione accede a Spanner in modo sincrono, rimane inattiva in attesa dei dati dal proxy. In questo caso, è meno probabile che l'applicazione e il proxy competano per le risorse della CPU.
Inizia con un'allocazione della CPU di base. Monitora l'utilizzo con un carico realistico per ottimizzare il valore in base alle tue esigenze specifiche.
Passaggi successivi
- Connetti
psqla un database PostgreSQL - Connetti
JDBCa un database PostgreSQL - Connetti
pgxa un database PostgreSQL - Connetti
psycopg2a un database PostgreSQL - Connetti
psycopg3a un database PostgreSQL - Connetti
node-postgresa un database PostgreSQL - Visualizza una panoramica dei driver e degli ORM supportati per Spanner