Iniciar o PGAdapter

Nesta página, explicamos como iniciar o PGAdapter no Spanner. Para saber mais sobre o PGAdapter, consulte Sobre o PGAdapter. Para fazer o download do binário do PGAdapter, consulte Acessar o PGAdapter.

Você pode iniciar o PGAdapter das seguintes maneiras:

  • Como um processo autônomo
  • Em um contêiner do Docker
  • No Cloud Run
  • Usar o PGAdapter como um proxy de arquivo secundário (por exemplo, em um cluster do Kubernetes)
  • No processo com o aplicativo Java

Antes de começar

Antes de iniciar o PGAdapter, verifique se você fez a autenticação com uma conta de usuário ou de serviço na máquina em que o PGAdapter será executado. Se você estiver usando uma conta de serviço, precisará saber a localização do arquivo de chave JSON (o arquivo de credenciais). Em seguida, é possível especificar o caminho das credenciais com a opção -c do PGAdapter ou definindo a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS.

Confira mais informações:

Escolha um método para executar o PGAdapter

É possível iniciar o PGAdapter como um processo independente, em um contêiner do Docker, no Cloud Run ou no processo com seu aplicativo Java. Ao iniciar o PGAdapter, você especifica o projeto, a instância do Spanner e o banco de dados para se conectar. Também é possível especificar o caminho para um arquivo de credenciais formatado em JSON (arquivo de chave).

Independente

Faça o download do PGAdapter com o comando a seguir.

wget https://storage.googleapis.com/pgadapter-jar-releases/pgadapter.tar.gz \
  && tar -xzvf pgadapter.tar.gz

Inicie o PGAdapter com o comando a seguir.

java -jar pgadapter.jar -p PROJECT_NAME -i INSTANCE_NAME -d DATABASE_NAME \
  -c CREDENTIALS_FILE_PATH \
  ADDITIONAL_OPTIONS

As seguintes opções são obrigatórias:

-p project_name
Nome do projeto em que o banco de dados do Spanner está sendo executado.
-i instance_name
Nome da instância do Spanner.
-d database_name
Nome do banco de dados a ser conectado.

As seguintes opções são opcionais:

-r databaseRole=database_role
Papel do banco de dados a ser usado na sessão. Para mais informações, consulte Autorização com PGAdapter.
-c credentials_file_path
Caminho completo do arquivo de chaves que contém as credenciais da conta de serviço no formato JSON. Se essa opção não for definida, as credenciais serão lidas do caminho especificado pela variável de ambiente GOOGLE_APPLICATION_CREDENTIALS.

Para aprender a criar uma conta de serviço e fazer o download de um arquivo de chave formatado em JSON, consulte Como criar uma conta de serviço.

Certifique-se de conceder à conta de serviço credenciais suficientes para acessar o banco de dados.

É possível omitir essa opção se você se autenticar primeiro com a Google Cloud CLI com o seguinte comando:

gcloud auth application-default login

Para mais informações, consulte Configurar autenticação e autorização.

-s port
Porta que o PGAdapter detecta. O padrão é 5432 (a porta padrão do PostgreSQL).
-v version_number

Número da versão do PostgreSQL a ser exposto ao cliente durante a conexão. O valor padrão é 14,1

Alguns aplicativos e drivers do PostgreSQL ativam outros recursos dependendo do número da versão. É possível que o Spanner não aceite esses recursos. Consulte Drivers e clientes para ver uma lista completa dos clientes compatíveis.

-x

Ativa conexões de hosts que não sejam localhost. Não use ao iniciar o PGAdapter no modo autônomo. Use somente ao começar em um contêiner do Docker.

Por padrão, como medida de segurança, o PGAdapter aceita conexões apenas do localhost.

Este exemplo simples inicia o PGAdapter no modo autônomo na porta 5432 usando as credenciais padrão do aplicativo.

java -jar pgadapter.jar \
  -p my-project \
  -i my-instance \
  -d my-database \
  -s 5432
            

Docker

Inicie o PGAdapter com o comando a seguir.

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

Além das opções de PGAdapter para especificar projeto, instância, banco de dados e credenciais, as seguintes opções são necessárias:

-p 127.0.0.1:HOST-PORT:DOCKER-PORT

Essa opção do Docker mapeia a porta DOCKER-PORT dentro do contêiner do Docker para a porta HOST-PORT fora do contêiner. DOCKER-PORT precisa corresponder à forma como o PGAdapter é configurado no contêiner. O padrão é 5432. HOST-PORT é a porta que o Docker precisa detectar fora do contêiner para solicitações de conexão. Ela precisa estar sempre disponível no localhost.

Para mais informações, consulte Publicar ou expor a porta (-p, --expose) na documentação do Docker.

-v CREDENTIALS_FILE_PATH:in_container_mount_point

Essa vinculação de opção do Docker ativa um volume compartilhado. Ele mapeia o caminho do host fora do contêiner para um volume (ponto de montagem) dentro do contêiner. Os caminhos de host e contêiner são separados por dois pontos (:).

Essa opção permite que o PGAdapter acesse o arquivo JSON de credenciais fora do contêiner. No exemplo anterior, a opção -c faz referência ao ponto de montagem no contêiner. Nesse exemplo, o nome do ponto de montagem no contêiner é /acct_credentials.json. Você pode denominá-lo como quiser.

Para mais informações, consulte VOLUME (sistemas de arquivos compartilhados) (em inglês) na documentação do Docker.

-x

Ativa conexões de hosts que não sejam localhost. Isso é necessário porque a porta de dentro do contêiner que é mapeada para a porta do host não aparece para o PGAdapter como localhost.

As seguintes opções são opcionais:

-r databaseRole=database_role
Papel do banco de dados a ser usado na sessão. Para mais informações, consulte Autorização com PGAdapter.

No exemplo a seguir, as portas do Docker e do host estão definidas como a porta padrão 5432 do serviço de banco de dados do 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

Não é possível implantar o PGAdapter como um serviço autônomo no Cloud Run, mas ele pode ser implantado como um proxy de arquivo secundário.

Recomendamos executar o PGAdapter em um padrão de arquivo secundário em vez de um serviço separado pelos seguintes motivos:
  • Evita um único ponto de falha. O acesso de cada aplicativo ao seu banco de dados é independente dos outros, o que os torna mais resilientes.
  • O número de instâncias de PGAdapter é escalonado automaticamente de maneira linear com o número de instâncias do aplicativo.

O repositório PGAdapter do GitHub contém vários aplicativos de amostra funcionais que usam o Cloud Run e o PGAdapter como um proxy de arquivo secundário para várias linguagens de programação.

O arquivo de configuração a seguir mostra como adicionar o PGAdapter como um proxy de arquivo secundário no 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 de arquivo secundário

É possível usar o PGAdapter como um proxy de arquivo secundário em, por exemplo, um cluster do Kubernetes. Os contêineres de arquivos secundários do Kubernetes são executados em paralelo com o contêiner principal no pod.

Recomendamos executar o PGAdapter em um padrão de arquivo secundário em vez de um serviço separado pelos seguintes motivos:

  • Evita um único ponto de falha. O acesso de cada aplicativo ao seu banco de dados é independente dos outros, o que os torna mais resilientes.
  • Como o PGAdapter consome recursos em uma relação linear ao uso, esse padrão permite que você defina o escopo e solicite recursos para corresponder aos seus aplicativos conforme eles são escalonados com mais precisão.

O arquivo de configuração a seguir mostra como adicionar o PGAdapter como um proxy de arquivo secundário ao cluster do 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"

O repositório PGAdapter do GitHub contém um guia explicativo e um aplicativo de exemplo (link em inglês). Este exemplo inclui instruções para usar a Identidade da carga de trabalho com o PGAdapter.

Java em processo

Crie e inicie uma instância do PGAdapter com seu código Java. Essa é a configuração recomendada para aplicativos Java.

Se você estiver usando uma conta de serviço para autenticação, verifique se a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS está definida como o caminho do arquivo de credenciais.

  1. No projeto, adicione google-cloud-spanner-pgadapter como uma dependência. Para saber mais, consulte Instalar o PGAdapter.
  2. <dependency>
      <groupId>com.google.cloud</groupId>
      <artifactId>google-cloud-spanner-pgadapter</artifactId>
      <version>0.32.0</version>
    </dependency>
  3. Crie um servidor usando a classe com.google.cloud.spanner.pgadapter.ProxyServer.
  4. /**
      * 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);
    }
                  

O repositório PGAdapter do GitHub contém um aplicativo de exemplo completo (link em inglês).

A seguir