Avvia PGAdapter

Questa pagina spiega come avviare PGAdapter in Spanner. Per ulteriori informazioni 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 ambiente Kubernetes cluster)
• 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 di 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:

• Panoramica dell'autenticazione
• Autorizzazione di gcloud CLI

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 PGAdapter, specifichi il progetto, l'istanza Spanner e database a cui connetterti. Puoi anche specificare il percorso per un file in formato JSON delle credenziali (file chiave).

Autonoma

Scarica PGAdapter con il comando seguente.

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 esecuzione dal database Spanner in.

-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 di 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 viene impostata, le credenziali vengono lette dalla percorso specificato dall'ambiente GOOGLE_APPLICATION_CREDENTIALS .

per scoprire come creare un account di servizio e scaricare una chiave in formato JSON. consulta la sezione Creazione di un account di servizio.

Assicurati di concedere all'account di servizio credenziali sufficienti per 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 login

Per ulteriori informazioni, vedi Configura l'autenticazione e l'autorizzazione.

-s port

Porta su cui PGAdapter rimane in ascolto. Il valore predefinito è 5432 (il valore predefinito porta PostgreSQL).

-v version_number

Numero di versione di PostgreSQL da esporre al client durante connessione. Il valore predefinito è 14,1

Alcune applicazioni e driver PostgreSQL consentono funzioni aggiuntive, a seconda di questo numero di versione. Spanner potrebbero non supportare queste funzionalità. Vedi Driver e client per un elenco completo dei client supportati.

-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 dell'applicazione predefinite.

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 HOST-PORT all'esterno del container. DOCKER-PORT deve corrispondere al metodo PGAdapter è configurato all'interno del container. it il valore predefinito è 5432. HOST-PORT è la porta Docker deve rimanere in ascolto all'esterno del container per rilevare la connessione richieste. 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 associa 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 container. In questo esempio viene assegnato un nome il punto di montaggio all'interno del container /acct_credentials.json. Puoi dare un nome tutto ciò che desideri.

Per ulteriori informazioni, vedi VOLUME (file system condivisi) nella documentazione Docker.

-x

Abilita connessioni da host diversi da localhost. Questo è necessaria perché la porta all'interno del container mappato alla porta dell'host non sembra PGAdapter come localhost.

Le seguenti opzioni sono facoltative:

-r databaseRole=database_role

Ruolo di database da utilizzare per la sessione. Per ulteriori informazioni, vedi Autorizzazione con PGAdapter.

Nell'esempio seguente, la porta dell'host e la porta Docker sono entrambe impostate alla 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 eseguirne il deployment 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 tuo database sono indipendenti dagli altri, il che li rende resiliente.
• Il numero di istanze PGAdapter scala automaticamente in modo lineare con il numero di istanze dell'applicazione.

Il repository GitHub di PGAdapter contiene diverse di utilizzare le applicazioni di esempio con Cloud Run PGAdapter come proxy sidecar per vari programmi lingue diverse.

Il seguente file di configurazione mostra come aggiungere PGAdapter come proxy sidecar per 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. Sidecar di Kubernetes i container vengono eseguiti in parallelo al container principale nel pod.

Ti consigliamo di eseguire PGAdapter in un pattern collaterale prima di eseguirlo 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 di Workload Identity 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 è impostato sul percorso del file delle credenziali.

1. Aggiungi google-cloud-spanner-pgadapter come dipendenza al tuo progetto. Per maggiori dettagli, vedi Scaricare PGAdapter.

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

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

Passaggi successivi

• Connetti psql a un database PostgreSQL
• Connetti JDBC a un database PostgreSQL
• Connetti pgx a un database PostgreSQL
• Connetti psycopg2 a un database PostgreSQL
• Connetti psycopg3 a un database PostgreSQL
• Connetti node-postgres a un database PostgreSQL