Conectar usando o proxy de autenticação do AlloyDB

Para fazer conexões autorizadas e criptografadas com instâncias do AlloyDB para PostgreSQL, use o proxy de autenticação do AlloyDB. Para mais informações, consulte Sobre o proxy de autenticação do AlloyDB.

Para usar o proxy de autenticação do AlloyDB, siga várias etapas de configuração única, inicie o cliente do proxy de autenticação e use-o para se conectar a um banco de dados.

Antes de começar

O host do cliente precisa atender a estes requisitos:

• O cliente precisa ter um caminho de rede para a instância do AlloyDB com base no método de conexão:

  • Acesso a serviços particulares (padrão): o cliente precisa ter visibilidade de rede para a rede de nuvem privada virtual (VPC) em que as instâncias residem. Os hosts de cliente (como instâncias do Compute Engine) nessa rede VPC têm essa visibilidade de rede por padrão. Os hosts de cliente em redes externas (redes locais ou redes VPC diferentes) têm essa visibilidade se a rede VPC da instância do AlloyDB estiver conectada à rede externa usando um túnel do Cloud VPN ou um anexo da VLAN para Interconexão dedicada ou Interconexão por parceiro.
  • Private Service Connect: a rede VPC do cliente precisa ter um endpoint do Private Service Connect e um registro DNS particular correspondente, e você precisa iniciar o cliente do proxy de autenticação com a flag --psc.
  • IP público: a instância precisa ter o IP público ativado, e você precisa iniciar o cliente do proxy de autenticação com a flag --public-ip. Ao se conectar usando o proxy de autenticação, não é necessário adicionar o endereço IP do host do cliente às redes externas autorizadas.

• Se o host do cliente tiver uma política de firewall de saída, ele precisará permitir conexões de saída com a porta 5433 nos endereços IP das instâncias do AlloyDB e permitir conexões de saída com a porta 443 (a porta HTTPS padrão) para todos os endereços IP.

• Se você estiver usando uma instância do Compute Engine como host do cliente, ela precisará ter o escopo de acesso https://www.googleapis.com/auth/cloud-platform para usar a API AlloyDB. Se necessário, altere o escopo de acesso para incluir esse escopo.

Fazer o download do cliente do proxy de autenticação

A máquina em que você faz o download do cliente do proxy de autenticação depende de você querer se conectar às instâncias do AlloyDB de dentro da rede VPC ou de fora dela.

Se você quiser se conectar ao cluster usando o acesso a serviços particulares, faça o download do cliente do proxy de autenticação em uma instância de máquina virtual (VM) do Compute Engine em execução na rede VPC que tem acesso a serviços particulares ao cluster.

Se você pretende se conectar ao cluster de fora da VPC, a máquina em que ele será instalado depende da estratégia de conexão externa usada. Por exemplo, é possível instalar o cliente do proxy de autenticação em uma máquina macOS ou Windows local para o aplicativo e usar um servidor SOCKS em execução na rede VPC do AlloyDB como um intermediário de conexão. Para mais informações, consulte Conectar-se a um cluster de fora da VPC.

Observação :verifique se você está usando a versão mais recente do cliente do proxy de autenticação. O Google lança novas versões do cliente do proxy de autenticação mensalmente. Para encontrar a versão atual, acesse a página de versões do cliente do proxy de autenticação no GitHub.

Linux

64 bits (AMD)

1. Faça o download do cliente do proxy de autenticação:

   wget https://storage.googleapis.com/alloydb-auth-proxy/v1.17.2/alloydb-auth-proxy.linux.amd64 -O alloydb-auth-proxy

2. Torne o cliente do proxy de autenticação executável:

   chmod +x alloydb-auth-proxy

3. Adicione o cliente do proxy de autenticação ao PATH:

   mkdir -p ~/.local/bin
   mv alloydb-auth-proxy ~/.local/bin/
   export PATH="$HOME/.local/bin:$PATH"

   Para manter essas mudanças em todas as sessões, adicione export PATH="$HOME/.local/bin:$PATH" ao arquivo ~/.bashrc ou ~/.zshrc.

32 bits (AMD)

1. Faça o download do cliente do proxy de autenticação:

   wget https://storage.googleapis.com/alloydb-auth-proxy/v1.17.2/alloydb-auth-proxy.linux.386 -O alloydb-auth-proxy

2. Torne o cliente do proxy de autenticação executável:

   chmod +x alloydb-auth-proxy

3. Adicione o cliente do proxy de autenticação ao PATH:

   mkdir -p ~/.local/bin
   mv alloydb-auth-proxy ~/.local/bin/
   export PATH="$HOME/.local/bin:$PATH"

   Para manter essas mudanças em todas as sessões, adicione export PATH="$HOME/.local/bin:$PATH" ao arquivo ~/.bashrc ou ~/.zshrc.

64 bits (ARM)

1. Faça o download do cliente do proxy de autenticação:

   wget https://storage.googleapis.com/alloydb-auth-proxy/v1.17.2/alloydb-auth-proxy.linux.arm64 -O alloydb-auth-proxy

2. Torne o cliente do proxy de autenticação executável:

   chmod +x alloydb-auth-proxy

3. Adicione o cliente do proxy de autenticação ao PATH:

   mkdir -p ~/.local/bin
   mv alloydb-auth-proxy ~/.local/bin/
   export PATH="$HOME/.local/bin:$PATH"

   Para manter essas mudanças em todas as sessões, adicione export PATH="$HOME/.local/bin:$PATH" ao arquivo ~/.bashrc ou ~/.zshrc.

32 bits (ARM)

1. Faça o download do cliente do proxy de autenticação:

   wget https://storage.googleapis.com/alloydb-auth-proxy/v1.17.2/alloydb-auth-proxy.linux.arm -O alloydb-auth-proxy

2. Torne o cliente do proxy de autenticação executável:

   chmod +x alloydb-auth-proxy

3. Adicione o cliente do proxy de autenticação ao PATH:

   mkdir -p ~/.local/bin
   mv alloydb-auth-proxy ~/.local/bin/
   export PATH="$HOME/.local/bin:$PATH"

   Para manter essas mudanças em todas as sessões, adicione export PATH="$HOME/.local/bin:$PATH" ao arquivo ~/.bashrc ou ~/.zshrc.

macOS

ARM64

1. Faça o download do cliente do proxy de autenticação:

   curl -o alloydb-auth-proxy https://storage.googleapis.com/alloydb-auth-proxy/v1.17.2/alloydb-auth-proxy.darwin.arm64

2. Torne o cliente do proxy de autenticação executável:

   chmod +x alloydb-auth-proxy

3. Adicione o cliente do proxy de autenticação ao PATH:

   mkdir -p ~/.local/bin
   mv alloydb-auth-proxy ~/.local/bin/
   export PATH="$HOME/.local/bin:$PATH"

   Para manter essas mudanças em todas as sessões, adicione export PATH="$HOME/.local/bin:$PATH" ao arquivo ~/.bashrc ou ~/.zshrc.

AMD64

1. Faça o download do cliente do proxy de autenticação:

   curl -o alloydb-auth-proxy https://storage.googleapis.com/alloydb-auth-proxy/v1.17.2/alloydb-auth-proxy.darwin.amd64

2. Torne o cliente do proxy de autenticação executável:

   chmod +x alloydb-auth-proxy

3. Adicione o cliente do proxy de autenticação ao PATH:

   mkdir -p ~/.local/bin
   mv alloydb-auth-proxy ~/.local/bin/
   export PATH="$HOME/.local/bin:$PATH"

   Para manter essas mudanças em todas as sessões, adicione export PATH="$HOME/.local/bin:$PATH" ao arquivo ~/.bashrc ou ~/.zshrc.

Windows

64 bits

1. Clique com o botão direito do mouse em https://storage.googleapis.com/alloydb-auth-proxy/v1.17.2/alloydb-auth-proxy-x64.exe e selecione Salvar link como para baixar o cliente do proxy de autenticação. Renomeie o arquivo para alloydb-auth-proxy.exe.

2. Adicione o cliente do proxy de autenticação ao PATH:

   New-Item -ItemType Directory -Force -Path "$HOME\bin"
   Move-Item -Path .\alloydb-auth-proxy.exe -Destination "$HOME\bin"
   $userPath = [Environment]::GetEnvironmentVariable("Path", "User")
   [Environment]::SetEnvironmentVariable("Path", "$userPath;$HOME\bin", "User")
   

32 bits

1. Clique com o botão direito do mouse em https://storage.googleapis.com/alloydb-auth-proxy/v1.17.2/alloydb-auth-proxy-x86.exe e selecione Salvar link como para baixar o cliente do proxy de autenticação. Renomeie o arquivo para alloydb-auth-proxy.exe.

2. Adicione o cliente do proxy de autenticação ao PATH:

   New-Item -ItemType Directory -Force -Path "$HOME\bin"
   Move-Item -Path .\alloydb-auth-proxy.exe -Destination "$HOME\bin"
   $userPath = [Environment]::GetEnvironmentVariable("Path", "User")
   [Environment]::SetEnvironmentVariable("Path", "$userPath;$HOME\bin", "User")
   

Imagem Docker

Por conveniência, várias imagens de contêiner que contêm o cliente do proxy de autenticação estão disponíveis no Artifact Registry.

É possível extrair a imagem mais recente na sua máquina local usando o Docker com o seguinte comando:

docker pull gcr.io/alloydb-connectors/alloydb-auth-proxy:latest

Outros SOs

Para outros sistemas operacionais não incluídos aqui, compile o cliente do proxy de autenticação a partir do código-fonte.

Escolha o principal do Identity and Access Management (IAM) e prepare-o para autorização

O proxy de autenticação do AlloyDB permite o uso desses tipos de principais do IAM para autorizar conexões entre o cliente e uma instância do AlloyDB:

• Uma conta de serviço anexada. Se o host do cliente for executado no Google Cloud, por exemplo, em uma instância do Compute Engine, será possível autorizar conexões usando a conta de serviço anexada a esse recurso.

  Recomendamos que você use uma conta de serviço para autorização em ambientes de produção. Uma conta de serviço anexada é a opção mais segura, porque não requer uma chave salva.

• Sua conta de usuário. É possível usar sua própria conta de usuário do IAM para autorizar conexões.

  Usar sua própria conta de usuário é conveniente em ambientes de desenvolvimento em que você gerencia recursos do AlloyDB usando a CLI gcloud, desenvolve o banco de dados usando uma ferramenta como o psql e desenvolve o código do aplicativo no mesmo host.

• Uma conta de serviço gerenciado pelo usuário. É possível criar uma conta de serviço do IAM para seu aplicativo e autorizar conexões usando essa conta.

  Use uma conta de serviço gerenciado pelo usuário quando o host do cliente for executado fora do Google Cloud e não puder usar uma conta de serviço anexada.

Depois de escolher qual principal do IAM usar, verifique se ele tem as permissões do IAM necessárias e se as credenciais dele estão disponíveis no host do cliente.

Permissões do IAM obrigatórias

O principal do IAM usado para autorizar conexões precisa ter as permissões fornecidas pelos papéis predefinidos roles/alloydb.client (cliente do AlloyDB) e roles/serviceusage.serviceUsageConsumer (consumidor do Service Usage).

Observação :o papel roles/alloydb.admin (administrador do AlloyDB) também fornece as permissões necessárias.

Para atribuir o papel de cliente do AlloyDB a um principal do IAM:

• A API Cloud Resource Manager precisa estar ativada no projeto do Google Cloud .

• Você precisa ter o papel básico do IAM roles/owner (Proprietário) no projeto doGoogle Cloud ou um papel que conceda estas permissões:

  • resourcemanager.projects.get
  • resourcemanager.projects.getIamPolicy
  • resourcemanager.projects.setIamPolicy

  Para receber essas permissões seguindo o princípio de menor privilégio, peça ao administrador para conceder a você o papel roles/resourcemanager.projectIamAdmin (Administrador do IAM do projeto).

Disponibilizar as credenciais do IAM no host do cliente

O cliente do proxy de autenticação usa o Application Default Credentials (ADC) para localizar as credenciais do IAM no host do cliente. Na maioria dos ambientes, essas credenciais já estão presentes, então não é necessário configurar nada. O cliente do proxy de autenticação procura as seguintes fontes de credenciais, em ordem:

• Sua conta de usuário. Ao desenvolver localmente, autentique-se com sua própria conta de usuário executando o seguinte comando da CLI gcloud:

  gcloud auth application-default login
  

  O cliente do proxy de autenticação detecta e usa essas credenciais. Não é necessário fazer o download de uma chave de conta de serviço.

• Uma conta de serviço anexada. Quando o host do cliente é executado no Google Cloud, por exemplo, em uma instância do Compute Engine, o servidor de metadados do ambiente fornece credenciais da conta de serviço anexada. O cliente do proxy de autenticação descobre e usa essas credenciais sem configuração extra.

Outras fontes de credenciais

Use os métodos a seguir somente quando o Application Default Credentials não estiver disponível, por exemplo, ao executar o cliente do proxy de autenticação fora do Google Cloudou quando precisar substituir as credenciais no ambiente.

• Uma chave de conta de serviço. Use uma chave de conta de serviço quando o host do cliente for executado fora do Google Cloud, por exemplo, em um data center local ou em outro provedor de nuvem, e não for possível usar a federação de identidade de carga de trabalho.

  Crie uma chave de conta de serviço no formato JSON e faça o download dela no host do cliente. Em seguida, defina a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS como o caminho do arquivo de chave:

  export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account-key.json"
  

  Se quiser, especifique o caminho com a flag --credentials-file ao iniciar o cliente do proxy de autenticação:

  alloydb-auth-proxy --credentials-file /path/to/service-account-key.json INSTANCE_URI
  

  Atenção: as chaves de conta de serviço poderão causar problemas de segurança se não forem gerenciadas corretamente. Antes de criar uma chave, considere uma alternativa mais segura.

• Um token de acesso do OAuth 2.0. Use um token de acesso quando outro sistema já emitir tokens de curta duração para você, por exemplo, um pipeline de integração contínua que recebe um token antes de iniciar o cliente do proxy de autenticação.

  Se você já tiver um token de acesso OAuth 2.0 válido, transmita-o diretamente ao iniciar o cliente do proxy de autenticação:

  alloydb-auth-proxy --token "ACCESS_TOKEN" INSTANCE_URI
  

• Credenciais da CLI gcloud. Use a flag --gcloud-auth somente quando precisar reutilizar uma sessão gcloud auth login atual e não for possível executar gcloud auth application-default login.

  A flag --gcloud-auth faz com que o cliente do proxy de autenticação use a conta que você autenticou com gcloud auth login em vez de usar o Application Default Credentials. Não recomendamos essa flag. Execute gcloud auth application-default login.

Coletar URIs de conexão para as instâncias do AlloyDB

Ao iniciar o cliente do proxy de autenticação, identifique as instâncias do AlloyDB com que você quer se conectar usando este formato de URI de conexão:

projects/PROJECT_ID/locations/REGION_ID/clusters/CLUSTER_ID/instances/INSTANCE_ID

Para ver uma lista de todos os URIs de conexão das instâncias, use o comando alloydb instances list da CLI gcloud:

gcloud alloydb instances list \
    --region=REGION_ID \
    --cluster=CLUSTER_ID \
    --project=PROJECT_ID

Substitua:

• REGION_ID: a região em que as instâncias estão localizadas.
• CLUSTER_ID: o ID do cluster em que as instâncias estão localizadas
• PROJECT_ID: o ID do projeto em que o cluster está localizado.

Colete o URI de conexão de cada instância que você quer acessar.

Iniciar o cliente do proxy de autenticação

Ao iniciar o cliente do proxy de autenticação, você fornece informações sobre as instâncias do AlloyDB às quais se conectar e, se necessário, informações de credenciais para usar ao autorizar essas conexões.

Quando ele é iniciado, o cliente do proxy de autenticação:

• Autoriza conexões com instâncias do AlloyDB usando as credenciais e as permissões do IAM do principal do IAM que você configurou. Ele procura credenciais seguindo uma sequência específica de etapas.
• Autoriza automaticamente as conexões por IP público com a rede de origem, se a instância tiver o IP público ativado.
• Configura uma conexão mTLS 1.3 particular com o servidor proxy de autenticação de cada instância.
• Começa a detectar solicitações de conexão de clientes locais.

Por padrão, o cliente do proxy de autenticação detecta conexões TCP no endereço IP 127.0.0.1, começando na porta 5432 e incrementando um número de porta para cada instância do AlloyDB além da primeira. É possível especificar um endereço de listener diferente e portas diferentes ao iniciar o cliente do proxy de autenticação.

Aviso: tenha cuidado ao vincular o cliente do proxy de autenticação a uma interface externa. Qualquer pessoa com acesso a essa interface ou porta está autorizada a se conectar à instância.

Observação: o Google recomenda que você execute o cliente do proxy de autenticação como um serviço persistente em ambientes de produção.

Linha de comando

alloydb-auth-proxy INSTANCE_URI... \
    [ --credentials-file PATH_TO_KEY_FILE \ ]
    [ --token OAUTH_ACCESS_TOKEN \ ]
    [ --port INITIAL_PORT_NUMBER \ ]
    [ --address LOCAL_LISTENER_ADDRESS \ ]
    [ --auto-iam-authn \ ]
    [ --psc \ ]
    [ --public-ip \ ]
    [ --disable-built-in-telemetry ]

Substitua:

• INSTANCE_URI: o URI de conexão da instância do AlloyDB a que você quer se conectar, especificado usando este formato:

  projects/PROJECT_ID/locations/REGION_ID/clusters/CLUSTER_ID/instances/INSTANCE_ID

  É possível substituir a porta do listener local padrão que o cliente do proxy de autenticação usará para a instância adicionando o parâmetro de consulta port ao URI:

  "projects/PROJECT_ID/locations/REGION_ID/clusters/CLUSTER_ID/instances/INSTANCE_ID?port=PORT"

• Opcional: PATH_TO_KEY_FILE: o caminho para o arquivo de chave JSON da conta de serviço gerenciado pelo usuário a ser usada para autorização de conexão.

• Opcional: OAUTH_ACCESS_TOKEN: um valor de token OAuth2 a ser usado para autorização de conexão.

• Opcional: INITIAL_PORT_NUMBER: o número da porta inicial a ser usado em vez da porta padrão 5432 ao detectar conexões TCP locais.

• Opcional: LOCAL_LISTENER_ADDRESS: o endereço do listener a ser usado em vez do padrão 127.0.0.1 ao detectar conexões TCP locais.

A flag opcional --auto-iam-authn permite que você se autentique automaticamente na instância. Isso funciona apenas para o usuário do banco de dados associado à conta do IAM que está executando o cliente do proxy de autenticação. Para mais informações, consulte Autenticar automaticamente usando o proxy de autenticação.

A flag opcional --psc permite que o proxy de autenticação se conecte a uma instância com o Private Service Connect ativado. Para mais informações sobre como configurar o DNS com o Private Service Connect, consulte Configurar uma zona gerenciada de DNS e um registro DNS.

A flag opcional --public-ip permite que o proxy de autenticação se conecte a uma instância com IP público ativado usando o endereço IP público da instância. Para mais informações sobre IP público, consulte Conectar usando IP público.

A flag opcional --disable-built-in-telemetry desativa o gerador de relatórios de métricas internas que o proxy de autenticação usa para informar sobre a integridade da conexão e da rede. Por padrão, o proxy de autenticação informa as operações internas ao prefixo de métrica do sistema alloydb.googleapis.com. Essas métricas ajudam o AlloyDB a melhorar o desempenho e identificar problemas de conectividade do cliente. Essa opção é útil para aplicativos que operam em ambientes em que a exportação de métricas de saída é restrita. Para desativar essa telemetria, use esta flag.

Contêiner do Docker

Inicie o cliente do Auth Proxy usando o comando docker run.

Se você usa as credenciais fornecidas pela instância do Compute Engine, pode usar um comando semelhante ao seguinte:

docker run \
  --publish 127.0.0.1:PORT:PORT \
  gcr.io/alloydb-connectors/alloydb-auth-proxy:latest \
  --address 0.0.0.0 \
  --port PORT \
  INSTANCE_URI

Substitua:

• PORT: a porta a ser usada para conexões locais com o cliente do proxy de autenticação. O padrão é 5432.

• INSTANCE_URI: o URI de conexão da instância do AlloyDB a que você quer se conectar, especificado usando o seguinte formato:

  projects/PROJECT_ID/locations/REGION_ID/clusters/CLUSTER_ID/instances/INSTANCE_ID

  É possível substituir a porta do listener local padrão que o cliente do proxy de autenticação usa para a instância adicionando o parâmetro de consulta port ao URI:

  "projects/PROJECT_ID/locations/REGION_ID/clusters/CLUSTER_ID/instances/INSTANCE_ID?port=PORT"

Sempre especifique o prefixo 127.0.0.1 na flag --publish para que o cliente do proxy de autenticação não seja exposto fora do host local.

O valor 0.0.0.0 na flag --address é necessário para tornar o listener acessível de fora do contêiner do Docker.

Para fornecer credenciais armazenadas em um arquivo JSON local, inclua as flags --volume e --credentials-file ao executar o comando docker run:

docker run \
  --volume PATH_TO_KEY_FILE:/key.json \
  --publish 127.0.0.1:PORT:PORT \
  gcr.io/alloydb-connectors/alloydb-auth-proxy:latest \
  --address 0.0.0.0 \
  --port PORT \
  --credentials-file=/key.json \
  INSTANCE_URI

Substitua PATH_TO_KEY_FILE pelo caminho para o arquivo de chave JSON da conta de serviço gerenciado pelo usuário a ser usada para autorização de conexão.

Exemplos de startups

Os exemplos a seguir mostram várias maneiras de iniciar o cliente do proxy de autenticação. Eles usam estes URIs de conexão de instância de exemplo:

projects/myproject/locations/us-central1/clusters/mycluster/instances/myprimary

projects/myproject/locations/us-central1/clusters/mycluster/instances/myreadpool

Inicialização básica

alloydb-auth-proxy \
  "projects/myproject/locations/us-central1/clusters/mycluster/instances/myprimary"

Neste exemplo, o cliente do proxy de autenticação autoriza a conexão seguindo a sequência normal de etapas de autorização e, em seguida, começa a detectar conexões locais com a instância myprimary em 127.0.0.1:5432.

Inicialização usando uma conta serviço gerenciado pelo usuário

alloydb-auth-proxy \
  "projects/myproject/locations/us-central1/clusters/mycluster/instances/myprimary" \
  --credentials-file "myappaccount/key.json"

Neste exemplo, o cliente do proxy de autenticação autoriza a conexão usando a chave JSON da conta de serviço gerenciado pelo usuário armazenada em myappaccount/key.json e começa a detectar conexões locais com a instância myprimary em 127.0.0.1:5432.

Startup se conectando a várias instâncias

alloydb-auth-proxy \
  "projects/myproject/locations/us-central1/clusters/mycluster/instances/myprimary" \
  "projects/myproject/locations/us-central1/clusters/mycluster/instances/myreadpool"

Neste exemplo, o cliente do proxy de autenticação autoriza a conexão seguindo a sequência normal de etapas de autorização e, em seguida, começa a detectar conexões locais com a instância myprimary em 127.0.0.1:5432 e com a instância myreadpool em 127.0.0.1:5433.

Detectar inicialização em portas personalizadas

O uso de portas personalizadas para o cliente do proxy de autenticação pode ser útil quando você precisa reservar a porta 5432 para outras conexões do PostgreSQL.

alloydb-auth-proxy \
  "projects/myproject/locations/us-central1/clusters/mycluster/instances/myprimary?port=5000" \
  "projects/myproject/locations/us-central1/clusters/mycluster/instances/myreadpool?port=5001"

Neste exemplo, o cliente do proxy de autenticação autoriza a conexão seguindo a sequência normal de etapas de autorização e, em seguida, começa a detectar conexões locais com a instância myprimary em 127.0.0.1:5000 e com a instância myreadpool em 127.0.0.1:5001.

Como essas portas personalizadas são sequenciais, o mesmo efeito pode ser alcançado usando este comando de inicialização:

alloydb-auth-proxy \
  "projects/myproject/locations/us-central1/clusters/mycluster/instances/myprimary" \
  "projects/myproject/locations/us-central1/clusters/mycluster/instances/myreadpool" \
  --port 5000

Inicialização de detecção em um endereço IP personalizado

alloydb-auth-proxy \
  "projects/myproject/locations/us-central1/clusters/mycluster/instances/myprimary" \
  --address "0.0.0.0"

Neste exemplo, o cliente do proxy de autenticação autoriza a conexão seguindo a sequência normal de etapas de autorização e, em seguida, começa a detectar conexões locais com a instância myprimary em 0.0.0.0:5432.

Conectar um aplicativo a um banco de dados usando o proxy de autenticação do AlloyDB

Os exemplos a seguir mostram como conectar um aplicativo a um banco de dados usando o proxy de autenticação do AlloyDB.

O exemplo psql mostra como conectar uma ferramenta de linha de comando.

A conexão com uma instância do AlloyDB usando o proxy de autenticação é, para várias linguagens de programação, idêntica à conexão com uma instância do Cloud SQL para PostgreSQL usando o proxy de autenticação do Cloud SQL. Portanto, os exemplos de linguagem são os mesmos do Cloud SQL para PostgreSQL.

Esses exemplos se baseiam em uma inicialização padrão do cliente do proxy de autenticação para que ele detecte conexões TCP locais em 127.0.0.1:5432.

Observação :com um novo cluster, é possível se conectar como o usuário postgres usando a senha que você especificou ao criar o cluster.

psql

psql -h 127.0.0.1 -p 5432 -U DB_USER

Substitua DB_USER pelo usuário do banco de dados que você quer usar para se conectar, por exemplo, postgres.

Será necessário inserir a senha do usuário DB_USER.

Python

import os

import sqlalchemy


# connect_tcp_socket initializes a TCP connection pool
# for an AlloyDB instance.
def connect_tcp_socket() -> sqlalchemy.engine.base.Engine:
    # Note: Saving credentials in environment variables is convenient, but not
    # secure - consider a more secure solution such as
    # Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
    # keep secrets safe.
    INSTANCE_HOST = os.environ[
        "INSTANCE_HOST"
    ]  # e.g. '127.0.0.1' ('172.17.0.1' if deployed to GAE Flex)
    db_user = os.environ["DB_USER"]  # e.g. 'my-db-user'
    db_pass = os.environ["DB_PASS"]  # e.g. 'my-db-password'
    db_name = os.environ["DB_NAME"]  # e.g. 'my-database'
    db_port = os.environ["DB_PORT"]  # e.g. 5432

    pool = sqlalchemy.create_engine(
        # Equivalent URL:
        # postgresql+pg8000://<db_user>:<db_pass>@<INSTANCE_HOST>:<db_port>/<db_name>
        sqlalchemy.engine.url.URL.create(
            drivername="postgresql+pg8000",
            username=db_user,
            password=db_pass,
            host=INSTANCE_HOST,
            port=db_port,
            database=db_name,
        ),
        # ...
    )
    return pool

Java

import com.zaxxer.hikari.HikariConfig;
import com.zaxxer.hikari.HikariDataSource;
import javax.sql.DataSource;

public class TcpConnectionPoolFactory extends ConnectionPoolFactory {

  // Note: Saving credentials in environment variables is convenient, but not
  // secure - consider a more secure solution such as
  // Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
  // keep secrets safe.
  private static final String DB_USER = System.getenv("DB_USER");
  private static final String DB_PASS = System.getenv("DB_PASS");
  private static final String DB_NAME = System.getenv("DB_NAME");

  private static final String INSTANCE_HOST = System.getenv("INSTANCE_HOST");
  private static final String DB_PORT = System.getenv("DB_PORT");


  public static DataSource createConnectionPool() {
    // The configuration object specifies behaviors for the connection pool.
    HikariConfig config = new HikariConfig();

    // The following URL is equivalent to setting the config options below:
    // jdbc:postgresql://<INSTANCE_HOST>:<DB_PORT>/<DB_NAME>?user=<DB_USER>&password=<DB_PASS>l

    // Configure which instance and what database user to connect with.
    config.setJdbcUrl(String.format("jdbc:postgresql://%s:%s/%s", INSTANCE_HOST, DB_PORT, DB_NAME));
    config.setUsername(DB_USER); // e.g. "root", "postgres"
    config.setPassword(DB_PASS); // e.g. "my-password"



    // ... Specify additional connection properties here.
    // ...

    // Initialize the connection pool using the configuration object.
    return new HikariDataSource(config);
  }
}

Node.js

const Knex = require('knex');
const fs = require('fs');

// createTcpPool initializes a TCP connection pool for an AlloyDB cluster.
const createTcpPool = async config => {
  // Note: Saving credentials in environment variables is convenient, but not
  // secure - consider a more secure solution such as
  // Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
  // keep secrets safe.
  const dbConfig = {
    client: 'pg',
    connection: {
      host: process.env.INSTANCE_HOST, // e.g. '127.0.0.1'
      port: process.env.DB_PORT, // e.g. '5432'
      user: process.env.DB_USER, // e.g. 'my-user'
      password: process.env.DB_PASS, // e.g. 'my-user-password'
      database: process.env.DB_NAME, // e.g. 'my-database'
    },
    // ... Specify additional properties here.
    ...config,
  };
  // Establish a connection to the database.
  return Knex(dbConfig);
};

Go

Para conferir esse snippet no contexto de um aplicativo da Web, consulte os exemplos do Go no GitHub.

package alloydb

import (
	"database/sql"
	"fmt"
	"log"
	"os"

	// Note: If connecting using the App Engine Flex Go runtime, use
	// "github.com/jackc/pgx/stdlib" instead, since v4 requires
	// Go modules which are not supported by App Engine Flex.
	_ "github.com/jackc/pgx/v5/stdlib"
)

// connectTCPSocket initializes a TCP connection pool for an AlloyDB cluster.
func connectTCPSocket() (*sql.DB, error) {
	mustGetenv := func(k string) string {
		v := os.Getenv(k)
		if v == "" {
			log.Fatalf("Warning: %s environment variable not set.", k)
		}
		return v
	}
	// Note: Saving credentials in environment variables is convenient, but not
	// secure - consider a more secure solution such as
	// Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
	// keep secrets safe.
	var (
		dbUser    = mustGetenv("DB_USER")       // e.g. 'my-db-user'
		dbPwd     = mustGetenv("DB_PASS")       // e.g. 'my-db-password'
		dbTCPHost = mustGetenv("INSTANCE_HOST") // e.g. '127.0.0.1' or IP Address of Cluster
		dbPort    = mustGetenv("DB_PORT")       // e.g. '5432'
		dbName    = mustGetenv("DB_NAME")       // e.g. 'my-database'
	)

	dbURI := fmt.Sprintf("host=%s user=%s password=%s port=%s database=%s",
		dbTCPHost, dbUser, dbPwd, dbPort, dbName)

	// dbPool is the pool of database connections.
	dbPool, err := sql.Open("pgx", dbURI)
	if err != nil {
		return nil, fmt.Errorf("sql.Open: %v", err)
	}

	// ...

	return dbPool, nil
}

C#

Para conferir esse snippet no contexto de um aplicativo da Web, consulte o README no GitHub.

using Npgsql;
using System;

namespace CloudSql
{
    public class PostgreSqlTcp
    {
        public static NpgsqlConnectionStringBuilder NewPostgreSqlTCPConnectionString()
        {
            // Equivalent connection string:
            // "Uid=<DB_USER>;Pwd=<DB_PASS>;Host=<INSTANCE_HOST>;Database=<DB_NAME>;"
            var connectionString = new NpgsqlConnectionStringBuilder()
            {
                // Note: Saving credentials in environment variables is convenient, but not
                // secure - consider a more secure solution such as
                // Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
                // keep secrets safe.
                Host = Environment.GetEnvironmentVariable("INSTANCE_HOST"),     // e.g. '127.0.0.1'
                // Set Host to 'cloudsql' when deploying to App Engine Flexible environment
                Username = Environment.GetEnvironmentVariable("DB_USER"), // e.g. 'my-db-user'
                Password = Environment.GetEnvironmentVariable("DB_PASS"), // e.g. 'my-db-password'
                Database = Environment.GetEnvironmentVariable("DB_NAME"), // e.g. 'my-database'

                // The Cloud SQL proxy provides encryption between the proxy and instance.
                SslMode = SslMode.Disable,
            };
            connectionString.Pooling = true;
            // Specify additional properties here.
            return connectionString;
        }
    }
}

Ruby

Para conferir esse snippet no contexto de um aplicativo da Web, consulte o README no GitHub.

development:
  adapter: postgresql
  # Configure additional properties here.
  username: <%= ENV["DB_USER"] %>  # e.g. "my-database-user"
  password: <%= ENV["DB_PASS"] %> # e.g. "my-database-password"
  database: <%= ENV.fetch("DB_NAME") { "vote_development" } %>
  host: <%= ENV.fetch("DB_HOST") { "127.0.0.1" }%> # '172.17.0.1' if deployed to GAE Flex
  port: <%= ENV.fetch("DB_PORT")  { 5432 }%>

PHP

Para conferir esse snippet no contexto de um aplicativo da Web, consulte o README no GitHub.

// $username = 'your_db_user';
// $password = 'yoursupersecretpassword';
// $dbName = 'your_db_name';
// $dbHost = "127.0.0.1";

// Connect using TCP
$dsn = sprintf('pgsql:dbname=%s;host=%s', $dbName, $dbHost);

// Connect to the database
$conn = new PDO($dsn, $username, $password, $connConfig);