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

Nesta página, você verá 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. Ative a API Cloud SQL Admin.

    Ative a API

  2. Se você estiver usando 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, é possível 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.
      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.16
  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.

    Caso queira usar uma conta de serviço para fornecer as credenciais ao proxy, você precisará criá-la com permissões suficientes. Se você estiver usando os papéis mais detalhados de gerenciamento de identidade e acesso (IAM) para gerenciar suas permissões do Cloud SQL, atribua à conta de serviço um papel que inclua a permissão cloudsql.instances.connect. Os papéis predefinidos do Cloud SQL que incluem essa permissão são os seguintes:

    • Cliente do Cloud SQL
    • Editor do Cloud SQL
    • Administrador do Cloud SQL

    Se você estiver usando os papéis legados (visualizador, editor e proprietário) do projeto, a conta de serviço precisará ter pelo menos o papel de editor.

    1. Acesse a página Contas de serviço no Console do Google Cloud.

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

    2. 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

      Como alternativa, é possível usar o papel primitivo de editor selecionando Projeto > Editor, mas esse papel inclui permissões no Google Cloud.

      Caso não veja esses papéis, talvez o usuário do Google Cloud não tenha a permissão resourcemanager.projects.setIamPolicy. Para verificar suas permissões, acesse a página do IAM no Console do Google Cloud e pesquise seu ID de usuário.

    6. Altere o ID da conta de serviço para um valor exclusivo e facilmente reconhecível.
    7. Clique em Fornecer uma nova chave particular e confirme se o tipo de chave é JSON.
    8. Clique em Criar.

      O arquivo da chave particular é transferido para sua máquina. É possível 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.

    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, myproject:us-central1:myinstance.

  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 para 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.16 /cloud_sql_proxy \
          -instances=<INSTANCE_CONNECTION_NAME>=tcp:0.0.0.0:5432 -credential_file=/config
        

    Se você estiver usando 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:1.16 /cloud_sql_proxy -dir=/cloudsql \
          -instances=<INSTANCE_CONNECTION_NAME> -credential_file=/config
        

    Se você estiver usando 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 para 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>"
          

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

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

    2. Se solicitado, 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>"
          

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

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

Precisa de ajuda? Para receber ajuda na solução de problemas com o proxy, consulte Como solucionar problemas nas conexões do Cloud SQL Proxy ou veja 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, extraia a nova versão da imagem do Proxy Docker para manter seu ambiente atualizado. Veja 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 do Google.

A seguir