Nesta página, explicamos como iniciar o PGAdapter no Spanner. Para saber mais sobre o PGAdapter, consulte Sobre o PGAdapter. Para acessar o binário do PGAdapter, consulte Acessar o PGAdapter.
É possível iniciar o PGAdapter das seguintes maneiras:
- Como um processo independente
- Em um contêiner do Docker
- No Cloud Run
- Como usar o PGAdapter como um proxy sidecar (por exemplo, em um cluster do Kubernetes)
- Em processo com seu aplicativo Java
- Como usar o conector PG do Spanner (
spgc) para executar ferramentas de linha de comando do PostgreSQL
Antes de começar
Antes de iniciar o PGAdapter, verifique se você se autenticou 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,
precisa saber o local do arquivo de chave JSON (o arquivo de credenciais). Em seguida, especifique o caminho das credenciais com a opção -c do PGAdapter
ou definindo a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS.
Para mais informações, consulte:
Escolher 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, em processo com o aplicativo Java ou usando o conector PG do Spanner (spgc). Ao iniciar o PGAdapter, você especifica o projeto, o ID da instância do Spanner e o banco de dados ao qual se conectar. Também é possível especificar o caminho para um
arquivo de credenciais no formato 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_ID -i INSTANCE_ID -d DATABASE_ID \ -c CREDENTIALS_FILE_PATH \ ADDITIONAL_OPTIONS
As seguintes opções são obrigatórias:
-
-p project_id - ID do projeto em que o banco de dados do Spanner está em execução.
-
-i instance_id - ID da instância do Spanner.
-
-d database_ID - ID do banco de dados do Spanner a que você quer se conectar.
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 o PGAdapter.
-
-c credentials_file_path - Caminho completo para o 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 no caminho especificado pela
variável de ambiente
GOOGLE_APPLICATION_CREDENTIALS.Para saber como criar uma conta de serviço e fazer o download de um arquivo de chave em formato JSON, consulte Como criar uma conta de serviço.
Verifique se você concedeu à 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 usando o seguinte comando:
gcloud auth application-default loginPara mais informações, consulte Configurar a autenticação e a 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 desse número de versão. O Spanner pode não ser compatível com esses recursos. Consulte Drivers e clientes para ver uma lista completa de clientes compatíveis.
-
-x -
Ativa conexões de hosts que não sejam localhost. Não use ao iniciar o PGAdapter no modo independente. Use apenas ao iniciar em um contêiner do Docker.
Por padrão, como medida de segurança, o PGAdapter aceita conexões apenas do localhost.
O exemplo a seguir inicia o PGAdapter no modo independente 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_ID -i INSTANCE_ID -d DATABASE_ID \ -c /acct_credentials.json -x OTHER_PGAdapter_OPTIONS
Além das opções do PGAdapter para especificar projeto, instância, banco de dados e credenciais, as seguintes opções são obrigatórias:
-
-p 127.0.0.1:HOST-PORT:DOCKER-PORT -
Essa opção do Docker mapeia a porta
DOCKER-PORTdentro do contêiner do Docker para a portaHOST-PORTfora do contêiner.DOCKER-PORTprecisa corresponder à configuração do PGAdapter dentro do 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 ser sempre uma porta disponível no localhost.Para mais informações, consulte Publicar ou expor 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 de credenciais JSON que está fora do contêiner. No exemplo anterior, a opção
-cfaz referência ao ponto de montagem no contêiner. Neste exemplo, o ponto de montagem no contêiner é chamado de/acct_credentials.json. Você pode dar o nome que quiser a ela.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 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 o PGAdapter.
No exemplo a seguir, a porta do Docker e a porta do host estão definidas como a porta padrão 5432 do serviço de banco de dados 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 independente no Cloud Run, mas é possível implantá-lo como um proxy sidecar.
É recomendável executar o PGAdapter em um padrão sidecar em vez de executá-lo como um serviço separado pelos seguintes motivos:- Evita um ponto único de falha. O acesso de cada aplicativo ao seu banco de dados é independente dos outros, tornando-os mais resilientes.
- O número de instâncias do PGAdapter é escalonado automaticamente de forma linear com o número de instâncias do aplicativo.
O repositório do PGAdapter no GitHub contém vários exemplos de aplicativos funcionais que usam o Cloud Run e o PGAdapter como um proxy sidecar para várias linguagens de programação.
O arquivo de configuração a seguir mostra como adicionar o PGAdapter como um proxy sidecar ao 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
É possível usar o PGAdapter como um proxy sidecar em, por exemplo, um cluster do Kubernetes. Os contêineres secundários do Kubernetes são executados em paralelo com o contêiner principal no pod.
Recomendamos executar o PGAdapter em um padrão sidecar em vez de executá-lo como um serviço separado pelos seguintes motivos:
- Evita um ponto único de falha. O acesso de cada aplicativo ao seu banco de dados é independente dos outros, tornando-os mais resilientes.
- Como o PGAdapter consome recursos em uma relação linear com o uso, esse padrão permite que você defina o escopo e solicite recursos com mais precisão para corresponder aos seus aplicativos à medida que eles são escalonados.
O arquivo de configuração a seguir mostra como adicionar o PGAdapter como um proxy sidecar 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 do PGAdapter no GitHub contém um guia explicativo e um aplicativo de exemplo. Este exemplo inclui instruções para usar a Federação de Identidade da Carga de Trabalho para GKE 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.
-
Adicione
google-cloud-spanner-pgadaptercomo uma dependência ao seu projeto. Para mais detalhes, consulte Acessar o PGAdapter. - Crie um servidor usando a 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);
}O repositório do PGAdapter no GitHub contém um aplicativo de exemplo completo.
Conector do Spanner PG (spgc)
spanner-pg-connector (com o alias spgc) é um
wrapper de CLI independente para executar ferramentas de linha de comando do PostgreSQL
(como psql ou pg_dump) no
Spanner. Ele agrupa o PGAdapter e um ambiente de execução Java
mínimo, então você não precisa ter o Java ou o Docker instalados localmente. Quando você executa um
comando, o spgc inicia o PGAdapter em segundo plano em uma
porta localhost atribuída dinamicamente e define
PGHOST e PGPORT. Em seguida, ele executa o
comando do cliente PostgreSQL e interrompe o PGAdapter quando o
comando é encerrado.
Instalar o spgc usando o script do instalador
Por padrão, o instalador faz o download da versão mais recente em
~/.spanner-pg-connector e adiciona esse diretório ao
PATH.
Para instalar o spgc no Linux (x86_64) ou no macOS
(aarch64 ou x86_64), execute o seguinte
comando:
curl -fsSL https://raw.githubusercontent.com/GoogleCloudPlatform/pgadapter/postgresql-dialect/spanner-pg-connector/install.sh | sh
Para instalar o spgc no Windows (x86_64, PowerShell),
execute o seguinte comando:
irm https://raw.githubusercontent.com/GoogleCloudPlatform/pgadapter/postgresql-dialect/spanner-pg-connector/install.ps1 | iex
Para personalizar a instalação no Linux ou macOS com VERSION
e INSTALL_DIR, execute o seguinte comando:
curl -fsSL https://raw.githubusercontent.com/GoogleCloudPlatform/pgadapter/postgresql-dialect/spanner-pg-connector/install.sh \ | VERSION=VERSION INSTALL_DIR="INSTALL_DIR" sh
Para personalizar a instalação no Windows (PowerShell) com
VERSION e INSTALL_DIR, execute o seguinte
comando:
$env:VERSION = "VERSION"; $env:INSTALL_DIR = "INSTALL_DIR"; irm https://raw.githubusercontent.com/GoogleCloudPlatform/pgadapter/postgresql-dialect/spanner-pg-connector/install.ps1 | iex
Instalar o spgc manualmente (sem o script do instalador)
Também é possível baixar e extrair o arquivo de lançamento diretamente do
Artifact Registry e adicionar o diretório extraído ao PATH.
O arquivo inclui spanner-pg-connector e
spgc.
Para instalar o spgc manualmente no Linux ou macOS, execute os seguintes
comandos (defina PLATFORM como linux-x64,
mac-aarch64 ou 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"
Para instalar o spgc manualmente no Windows (PowerShell), execute os
seguintes comandos:
$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"
Para manter spgc no PATH em todas as sessões de terminal, adicione o diretório de instalação ao perfil do shell (como ~/.bashrc ou ~/.zshrc no Linux e no macOS) ou à variável de ambiente Path do usuário no Windows.
Para verificar a instalação, confira a versão do spgc:
spgc --versionAutenticação
O spgc não exige um nome de usuário ou uma senha do PostgreSQL entre a ferramenta cliente e o proxy local do PGAdapter. Para
autenticar com o Spanner, o spgc usa o
Google Cloud
Application Default Credentials (ADC)
na seguinte ordem:
- Variável de ambiente
GOOGLE_APPLICATION_CREDENTIALS: aponta para uma chave de conta de serviço ou um arquivo JSON de credenciais. - Credenciais do usuário da Google Cloud CLI: execute
gcloud auth application-default loginpara configurar essas credenciais. - Conta de serviço anexada: o
spgcusa a conta de serviço anexada quando é executado em ambientes do Google Cloud , como Compute Engine, Cloud Shell, Cloud Workstations, Cloud Run ou Federação de Identidade da Carga de Trabalho para GKE.
Quando você se conecta ao
emulador do Spanner
(SPANNER_EMULATOR_HOST), o spgc desativa
a autenticação.
Uso e variáveis de ambiente
Transmita o comando do cliente e os argumentos dele diretamente para spgc
(ou spanner-pg-connector):
spgc psql -d "projects/PROJECT_ID/instances/INSTANCE_ID/databases/DATABASE_ID"
Também é possível configurar o projeto, a instância, o banco de dados padrão ou o emulador usando variáveis de ambiente:
GOOGLE_CLOUD_PROJECT
ID do projeto do - Google Cloud .
SPANNER_INSTANCE- ID da instância do Spanner.
SPANNER_DATABASE- ID padrão do banco de dados do Spanner. O
spgcusará esse valor se o comando não especificar-d,--dbnameou--database. SPANNER_EMULATOR_HOST- Se definido, conecta-se ao emulador do Spanner em
HOST:PORT(por exemplo,localhost:9010) em vez do Spanner. Remova essa variável ao se conectar ao Spanner. GOOGLE_APPLICATION_CREDENTIALS- Caminho opcional para um arquivo JSON de credenciais do Google Cloud .
Os exemplos a seguir mostram como executar spgc com variáveis de 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
Orientações sobre alocação de recursos para o proxy sidecar do PGAdapter
As diretrizes a seguir podem ajudar você a configurar os recursos de CPU e memória para o proxy sidecar do PGAdapter. Os valores ideais variam de acordo com sua carga de trabalho específica.
Memória
Como o PGAdapter não armazena muitos dados em cache, ele requer memória para converter os resultados da consulta do formato gRPC do Spanner para o formato de protocolo de transmissão do PostgreSQL. Isso é especialmente relevante para cargas de trabalho com colunas binárias grandes, porque o Spanner e o PostgreSQL processam esses tipos de dados de maneira diferente.
Para determinar quanta memória alocar, use a seguinte fórmula para alocação de memória, em que <var>number of concurrent connections</var> é o número de conexões simultâneas que o aplicativo processa:
384 MB + (2 MB * number of concurrent connections)
Por exemplo, se o aplicativo processar 200 conexões simultâneas, aloque aproximadamente 784 MB de memória:
384 MB + (2 MB * 200) = 784 MB
Comece com essa alocação de memória de referência. Monitore o uso em uma carga realista para ajustar o valor de acordo com suas necessidades específicas.
CPU
O PGAdapter não usa muita CPU. Isso ocorre porque o papel principal dele é atuar como um proxy de passagem. No entanto, o uso da CPU aumenta com a quantidade de dados enviados e recebidos.
Considere os seguintes fatores ao alocar a CPU:
- Carga de trabalho: os aplicativos que executam consultas que retornam grandes quantidades de dados exigem mais capacidade de CPU por conexão do que aqueles que retornam apenas algumas linhas e colunas.
- Padrão de acesso do aplicativo: se o aplicativo acessar o Spanner de forma síncrona, ele ficará inativo enquanto aguarda os dados do proxy. Nesse caso, é menos provável que o aplicativo e o proxy disputem recursos de CPU.
Comece com uma alocação de CPU de referência. Monitore o uso dele em uma carga realista para ajustar o valor de acordo com suas necessidades específicas.
A seguir
- Conecte o
psqla um banco de dados do PostgreSQL - Conecte o
JDBCa um banco de dados do PostgreSQL - Conecte o
pgxa um banco de dados do PostgreSQL - Conecte o
psycopg2a um banco de dados do PostgreSQL - Conecte o
psycopg3a um banco de dados do PostgreSQL - Conecte o
node-postgresa um banco de dados do PostgreSQL - Confira uma visão geral dos drivers e ORMs compatíveis com o Spanner