Como conectar um cliente psql usando a imagem do Cloud SQL Proxy Docker

Nesta página, veja como conectar um cliente psql à instância do Cloud SQL em uma máquina cliente executando a instância do Linux ou do Compute Engine Linux usando a imagem do Cloud SQL Proxy Docker.

Antes de começar

Você precisa:

  • instalar a ferramenta de linha de comando gcloud. Saiba mais;
  • autorizar a ferramenta gcloud. Saiba mais;
  • definir o projeto padrão para a ferramenta gcloud. Saiba mais;
  • configurar um usuário de banco de dados na instância do Cloud SQL. Saiba mais.

Como conectar um cliente psql usando a imagem do Proxy Docker

Para conectar usando a imagem Docker do proxy, faça o seguinte:

  1. Ativar Administrador do Cloud SQL API.

    Ativar a API

  2. Se você usa uma instância do Compute Engine, prepare-a:
    1. Exiba as propriedades dessa instância:
      gcloud compute instances describe [GCE_INSTANCE_NAME]
    2. Verifique os escopos ativados nela.

      A autenticação com escopos requer os seguintes escopos:

      • https://www.googleapis.com/auth/sqlservice.admin
      • https://www.googleapis.com/auth/devstorage.read_write

      Como alternativa, o escopo https://www.googleapis.com/auth/cloud-platform ativa todas as APIs do Google Cloud Platform.

      Se sua instância do Compute Engine não tiver os escopos adequados, você pode atualizar a instância para incluí-los. Para mais informações, consulte a documentação do Compute Engine.

    3. Abra uma conexão de terminal com a instância, seguindo as instruções em Como conectar-se a instâncias do Linux.
  3. Instale o cliente psql na instância do Compute Engine ou na máquina cliente, se isso ainda não foi feito.

    Debian/Ubuntu

    Instale o cliente psql do gerenciador de pacotes:

    sudo apt-get update
    sudo apt-get install postgresql-client
    

    CentOS/RHEL

    Instale o cliente psql do gerenciador de pacotes:

    sudo yum install postgresql
    

    openSUSE

    Instale o cliente psql do gerenciador de pacotes:

    sudo zypper install postgresql
    

    Outras plataformas

    1. Faça o download do PostgreSQL Core Distribution referente à sua plataforma na página de downloads do PostgreSQL (em inglês).
      O Core Distribution inclui o cliente psql.
    2. Instale o banco de dados do PostgreSQL de acordo com as orientações contidas na página de download.
  4. Se necessário, instale o cliente Docker:
    curl https://get.docker.com | sh
    sudo usermod -aG docker $USER
    

    Se você usa uma instância do Compute Engine otimizada para contêineres, ela já tem o cliente Docker instalado.

  5. Instale a imagem do Proxy Docker do Google Container Registry.
    docker pull gcr.io/cloudsql-docker/gce-proxy:1.12
  6. Se você executa a imagem do Proxy Docker em uma máquina local (e não em uma instância do Compute Engine) ou se a instância do Compute Engine não tem os escopos apropriados, crie uma conta de serviço do Google Cloud Platform.
    1. Acesse a página Contas de serviço do Console do Google Cloud Platform.

      Acessar a página "Contas de serviço"

    2. Se necessário, selecione o projeto que contém a instância do Cloud SQL.
    3. Clique em Criar conta de serviço.
    4. Na caixa de diálogo "Criar conta de serviço", forneça um nome descritivo para a conta.
    5. Em Papel, selecione um dos seguintes papéis:
      • Cloud SQL > Cliente do Cloud SQL
      • Cloud SQL > Editor do Cloud SQL
      • Cloud SQL > Administrador do Cloud SQL

      Também é possível usar o papel primitivo de editor ao selecionar Projeto > Editor. No entanto, ele inclui permissões em todo o Google Cloud Platform.

      Se esses papéis não estiverem sendo exibidos, é provável que seu usuário do Google Cloud Platform não tenha a permissão resourcemanager.projects.setIamPolicy. Para verificar suas permissões, acesse a página "IAM" no Console do Google Cloud Platform e procure seu código de usuário.

    6. Altere o código da conta de serviço com um valor exclusivo que você reconhecerá para que possa facilmente encontrar essa conta de serviço mais tarde, se necessário.
    7. Clique em Fornecer uma nova chave privada.
    8. O tipo de chave padrão é JSON, que é o valor correto a ser usado.
    9. Clique em Criar.

      O arquivo da chave privada é transferido para sua máquina. Você pode movê-lo para outro local. Mantenha-o seguro.

    Forneça o caminho para o arquivo da chave como "PATH_TO_KEY_FILE" quando iniciar o proxy.

  7. Acesse a página "Instâncias" do Cloud SQL no Console do Google Cloud Platform.

    Acessar a página "Instâncias" do Cloud SQL

  8. Selecione a instância para abrir a página Detalhes da instância e copie o Nome da conexão da instância.

    Por exemplo: myinstance:us-central1:myproject.

  9. Inicie o proxy.

    Dependendo da linguagem e do ambiente, inicie o proxy usando os soquetes TCP ou Unix. Os soquetes Unix não são compatíveis com aplicativos desenvolvidos na linguagem de programação Java ou com o ambiente Windows.

    Soquetes TCP

    docker run -d \
      -v <PATH_TO_KEY_FILE>:/config \
      -p 127.0.0.1:5432:5432 \
      gcr.io/cloudsql-docker/gce-proxy:1.12 /cloud_sql_proxy \
      -instances=<INSTANCE_CONNECTION_NAME>=tcp:0.0.0.0:5432 -credential_file=/config
    

    Se você usa as credenciais fornecidas pela instância do Compute Engine, não inclua o parâmetro credential_file e a linha -v <PATH_TO_KEY_FILE>:/config.

    Sempre especifique o prefixo 127.0.0.1 em -p para que o proxy não seja exposto fora do host local. O "0.0.0.0" no parâmetro das instâncias é necessário para tornar a porta acessível de fora do contêiner do Docker.

    Soquetes Unix

    docker run -d -v /cloudsql:/cloudsql \
      -v <PATH_TO_KEY_FILE>:/config \
      gcr.io/cloudsql-docker/gce-proxy /cloud_sql_proxy -dir=/cloudsql \
      -instances=<INSTANCE_CONNECTION_NAME> -credential_file=/config
    

    Se você usa as credenciais fornecidas pela instância do Compute Engine, não inclua o parâmetro credential_file e a linha -v <PATH_TO_KEY_FILE>:/config.

    Se você estiver usando uma imagem otimizada do contêiner, use um diretório gravável no lugar de /cloudsql. Por exemplo:

    -v /mnt/stateful_partition/cloudsql:/cloudsql

    É possível especificar mais de uma instância, separadas por vírgulas. Também é possível usar metadados do Compute Engine para determinar dinamicamente a quais instâncias se conectar. Saiba mais sobre os parâmetros de proxy.

  10. Inicie o cliente:

    A inicialização do proxy usando um soquete TCP ou UNIX determina a string de conexão a ser usada.

    Soquetes TCP

    1. Inicie o cliente psql:
      psql "host=127.0.0.1 sslmode=disable dbname=<DB_NAME> user=<USER_NAME>"
      

      Mesmo que o parâmetro sslmode esteja definido como disable, o proxy fornece uma conexão criptografada.

      Quando você estabelece a conexão com soquetes TCP, o endereço de acesso do proxy é 127.0.0.1.

    2. Digite a senha.
    3. Aparecerá o prompt do psql.

    Soquetes Unix

    1. Inicie o cliente psql:
      psql "sslmode=disable host=/cloudsql/<INSTANCE_CONNECTION_NAME> user=<USERNAME>"
      

      Mesmo que o parâmetro sslmode esteja definido como disable, o proxy fornece uma conexão criptografada.

    2. Digite a senha.
    3. Aparecerá o prompt do psql.

Precisa de ajuda? Para ajuda na solução de problemas com o proxy, consulte Como solucionar problemas nas conexões do Cloud SQL Proxy Você também pode consultar a página de suporte do Cloud SQL.

Como manter a imagem do Proxy Docker atualizada

A imagem do Proxy Docker é baseada em uma versão específica do Cloud SQL Proxy. Quando uma nova versão do Cloud SQL Proxy estiver disponível, você deverá extrair a nova versão da imagem do Proxy Docker para manter seu ambiente atualizado. Você pode ver qual é a versão atual na página de versões do Cloud SQL Proxy no GitHub. As futuras versões de proxy também serão divulgadas no fórum de anúncios do Cloud SQL nos Grupos dos Google (em inglês).

A seguir

Esta página foi útil? Conte sua opinião sobre:

Enviar comentários sobre…

Cloud SQL para PostgreSQL