Nesta página, explicamos como iniciar o PGAdapter no Spanner. Para saber sobre PGAdapter, consulte Sobre o PGAdapter Para acessar o binário PGAdapter, consulte Instalar o PGAdapter.
É possível iniciar o PGAdapter das seguintes maneiras:
- Como um processo independente
- Em um contêiner do Docker
- No Cloud Run
- Usar o PGAdapter como um proxy sidecar (por exemplo, em um ambiente do cluster)
- Em processamento com seu 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 PGAdapter
serão executados. Se você estiver usando uma conta de serviço,
é preciso saber o local do arquivo de chave JSON (o arquivo de credenciais). Você pode
Depois especifique o caminho das credenciais com o -c
do PGAdapter
ou configurando a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS
.
Veja mais informações em:
Escolha um método para executar o PGAdapter
É possível iniciar o PGAdapter como um processo autônomo em um ambiente do Docker no Cloud Run ou em andamento com seu aplicativo Java. Quando você iniciar o PGAdapter, especifica o projeto, a instância do Spanner e um banco de dados para se conectar. Também é possível especificar o caminho para um arquivo de credenciais (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 que o banco de dados do Spanner está executando
-
-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 de 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 saber como criar uma conta de serviço e fazer o download de uma chave no formato 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ê fizer a autenticação pela primeira vez com a Google Cloud CLI pelo seguinte comando:
gcloud auth application-default login
Para obter 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 do número da versão. Spanner podem não ter suporte para esses recursos. Consulte Drivers e clientes para ver a lista completa de clientes compatíveis.
-
-x
-
Ativa conexões de hosts que não sejam localhost. Não usar ao iniciar o PGAdapter no modo independente. 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.
O exemplo simples a seguir inicia o PGAdapter de forma independente na porta 5432 usando as credenciais de aplicativo padrão.
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 portaHOST-PORT
fora do contêiner.DOCKER-PORT
precisa corresponder à forma como o PGAdapter é configurado no contêiner. Ela o padrão é 5432.HOST-PORT
é a porta que o Docker precisa detectar fora do contêiner para solicitações de conexão. Precisa ser sempre uma porta 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 de 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 independente em o Cloud Run, mas é possível implantá-lo como um proxy sidecar.
É recomendável executar o PGAdapter em um padrão de arquivo secundário. executando-o 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, o que os torna resilientes.
- O número de instâncias do PGAdapter é escalonado automaticamente linearmente com o número de instâncias do aplicativo.
O repositório PGAdapter no GitHub contém várias aplicativos de amostra funcionais usando o Cloud Run e PGAdapter como proxy secundário para diversas funções idiomas.
O arquivo de configuração a seguir mostra como adicionar o PGAdapter como um proxy sidecar para o 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 do arquivo secundário
É possível usar o PGAdapter como um proxy secundário, por exemplo, em um cluster do Kubernetes. Arquivo secundário do Kubernetes contêineres 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 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 um dos outros, o que os torna mais resilientes.
- Como o PGAdapter consome recursos em uma relação de uso linear, esse padrão permite definir o escopo com mais precisão e solicitar recursos para corresponder dos aplicativos conforme eles são escalonados.
O arquivo de configuração a seguir mostra como adicionar o PGAdapter como um proxy 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 do PGAdapter no GitHub contém um guia explicativo e um aplicativo de exemplo (em inglês). Este exemplo inclui instruções para usar a Identidade da carga de trabalho com o PGAdapter.
Java no 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
na variável de ambiente GOOGLE_APPLICATION_CREDENTIALS
;
está definido como o caminho do arquivo de credenciais.
-
No projeto, adicione
google-cloud-spanner-pgadapter
como uma dependência. Veja mais detalhes em Instalar o PGAdapter. - Crie um servidor usando a classe
com.google.cloud.spanner.pgadapter.ProxyServer
. - Conecte o
psql
a um banco de dados do PostgreSQL - Conecte o
JDBC
a um banco de dados do PostgreSQL - Conecte o
pgx
a um banco de dados do PostgreSQL - Conecte o
psycopg2
a um banco de dados do PostgreSQL - Conecte o
psycopg3
a um banco de dados do PostgreSQL - Conecte o
node-postgres
a um banco de dados do 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);
}
O repositório PGAdapter do GitHub contém um aplicativo de exemplo completo (link em inglês).
A seguir
Exceto em caso de indicação contrária, o conteúdo desta página é licenciado de acordo com a Licença de atribuição 4.0 do Creative Commons, e as amostras de código são licenciadas de acordo com a Licença Apache 2.0. Para mais detalhes, consulte as políticas do site do Google Developers. Java é uma marca registrada da Oracle e/ou afiliadas.
Última atualização 2024-08-21 UTC.