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

Nesta página, descrevemos como usar a imagem do Cloud SQL Proxy Docker para conectar um cliente psql à instância do Cloud SQL em uma máquina cliente que executa a instância do Linux ou do Compute Engine Linux.

Antes de começar

Você precisa fazer o seguinte:

  • Instalar a ferramenta de linha de comando gcloud. Saiba mais.
  • Autorizar a ferramenta gcloud. Saiba mais.
  • Definir o projeto padrão na 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 do Proxy Docker, faça o seguinte:

  1. Ative a API Cloud SQL Admin.

    Ative a API

  2. Se você usa uma instância do Compute Engine, é necessário prepará-la:
    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, atualize 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 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 básico de Editor ao selecionar Projeto > Editor. No entanto, ele inclui permissões em todo o 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 privada e confirme se o tipo de chave é JSON.
    8. 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 de 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 respectiva 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 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.16 /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 instances, é 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ê 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ê usa uma imagem otimizada para contêiner, utilize um diretório gravável em vez 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 conexão usando soquetes TCP, o endereço de acesso do proxy é 127.0.0.1.

    2. Se solicitado, digite a senha.
    3. O prompt do psql é exibido.

    Sockets 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. O prompt do psql é exibido.

Precisa de ajuda? Para ajuda na solução de problemas com o proxy, consulte Como solucionar problemas nas conexões do Cloud SQL Proxy ou consulte a página de suporte do Cloud SQL.

Como manter a imagem do Docker do Proxy 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. Você pode ver qual é a versão atual na página de lançamentos do Cloud SQL Proxy no GitHub (em inglês). 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