Conectar o cliente psql ao Compute Engine

Nesta página, descrevemos como usar o cliente psql, instalado em uma instância do Compute Engine, para se conectar ao Cloud SQL.

Use o IP particular, o IP público, o Cloud SQL Proxy ou a imagem Docker de proxy.

Antes de começar

Antes de estabelecer uma conexão com a instância do Cloud SQL, é necessário ter um usuário padrão (postgres) do banco de dados na instância.

Essa tarefa não inclui instruções para a configuração da instância do Google Compute Engine. Se você precisar de ajuda para criar e configurar uma instância do Google Compute Engine, consulte a Documentação do Google Compute Engine.

Como estabelecer uma conexão usando um IP particular

Para estabelecer uma conexão com o Cloud SQL a partir de uma instância do Compute Engine usando um IP particular, é necessário configurar o acesso a serviços particulares no ambiente e definir a instância do Cloud SQL para usar um IP particular. A instância do Compute Engine precisa estar na mesma região da instância do Cloud SQL e na rede configurada para uma conexão particular. Saiba mais.

  1. Configure a instância para o uso de IP privado. Siga as instruções em Como configurar a conectividade IP privada.
  2. Abra uma conexão de terminal com a instância do Compute Engine.

    Use as instruções apropriadas, dependendo do sistema operacional da instância:

  3. Instale o cliente psql na instância do Google Compute Engine, se ele ainda não estiver instalado.

    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. Estabeleça conexão com o cliente psql.
    psql -h [CLOUD_SQL_PRIVATE_IP_ADDR] -U postgres
    

Como estabelecer uma conexão usando um endereço IP público

  1. Adicione um endereço IPv4 estático à instância do Compute Engine, se ela ainda não tiver um. Não é possível estabelecer uma conexão com o Compute Engine usando IPv6. Para informações sobre a adição de um endereço IP estático, consulte Como reservar um novo endereço IP externo estático na documentação do Compute Engine.
  2. Autorize o endereço IP estático da instância do Google Compute Engine como uma rede com permissão para conectar-se à instância do Cloud SQL.

    Para mais informações, consulte Como configurar acesso para conexões IP.

  3. Abra uma conexão de terminal com a instância do Compute Engine.

    Use as instruções apropriadas, dependendo do sistema operacional da instância:

  4. Instale o cliente psql na instância do Google Compute Engine, se ele ainda não estiver instalado.

    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.
  5. Estabeleça conexão com o cliente psql.
    psql -h [CLOUD_SQL_PUBLIC_IP_ADDR] -U postgres
    

    Para um exemplo de como estabelecer uma conexão usando SSL, consulte Conexão com SSL.

  6. Você verá 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 ou consulte a página de suporte do Cloud SQL.

Conexão pelo Cloud SQL Proxy

  1. Ativar Cloud SQL Admin API.

    Ativar a API

  2. Crie uma conta de serviço para o proxy.
    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 protegido.

  3. Se a instância do Google Compute Engine estiver em um projeto diferente da instância do Cloud SQL, verifique se a respectiva conta de serviço tem as permissões adequadas no projeto que contém a instância do Cloud SQL:
    1. Acesse a listagem de instâncias do Google Compute Engine no Console do Google Cloud Platform.

      Acessar a listagem de instâncias do Compute Engine

    2. Se necessário, selecione o projeto associado à instância do Compute Engine.
    3. Selecione a instância do Compute Engine para exibir as propriedades dela.
    4. Nas propriedades da instância do Compute Engine, copie o nome da conta de serviço.
    5. Acesse a página Projetos de "IAM e Admin" no Console do Google Cloud Platform.

      Acessar a página "Projetos do IAM e do administrador"

    6. Selecione o projeto que contém a instância do Cloud SQL.
    7. Procure o nome da conta de serviço.
    8. Se a conta de serviço já existir e tiver um papel que inclua a permissão cloudsql.instances.connect, avance para a etapa 4.

      Os papéis Cloud SQL Client, Cloud SQL Editor e Cloud SQL Admin fornecem a permissão necessária, assim como os papéis legados Editor e Owner do projeto.

    9. Caso contrário, clique em Adicionar para incluir a conta.
    10. Na caixa de diálogo Adicionar membros, insira o nome da conta de serviço e selecione um papel que inclua a permissão cloudsql.instances.connect. Qualquer papel predefinido do Cloud SQL funcionará, exceto o de Leitor.

      Também é possível usar o papel primário 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.

    11. Clique em Adicionar.

      Você verá a conta de serviço listada com o papel especificado.

  4. Abra uma conexão de terminal com a instância do Compute Engine.

    Use as instruções apropriadas, dependendo do sistema operacional da instância:

  5. Se a instância do Compute Engine estiver executando uma imagem pública do RHEL ou do CentOS, o SELinux poderá bloquear a conexão de proxy. Se isso acontecer, será necessário configurar o recurso SELinux para permitir a conexão.

    Para mais informações sobre o SELinux para RHEL, consulte a documentação do RHEL (em inglês). Para mais informações sobre o SELinux para CentOS, consulte a documentação do CentOS (em inglês).

  6. Instale o cliente psql na instância do Compute Engine, se ele ainda não estiver instalado.

    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.
  7. Instale o Cloud SQL Proxy na instância do Compute Engine.

    Linux de 64 bits

    1. Faça o download do proxy:
      wget https://dl.google.com/cloudsql/cloud_sql_proxy.linux.amd64 -O cloud_sql_proxy
      
    2. Torne o proxy executável:
      chmod +x cloud_sql_proxy
      

    Linux de 32 bits

    1. Faça o download do proxy:
      wget https://dl.google.com/cloudsql/cloud_sql_proxy.linux.386 -O cloud_sql_proxy
      
    2. Torne o proxy executável:
      chmod +x cloud_sql_proxy
      

    Windows de 64 bits

    Clique com o botão direito do mouse em https://dl.google.com/cloudsql/cloud_sql_proxy_x64.exe e selecione Salvar link como para fazer o download do proxy. Renomeie o arquivo para cloud_sql_proxy.exe.

    Windows de 32 bits

    Clique com o botão direito do mouse em https://dl.google.com/cloudsql/cloud_sql_proxy_x86.exe e selecione Salvar link como para fazer o download do proxy. Renomeie o arquivo para cloud_sql_proxy.exe.
    Caso seu sistema operacional não esteja incluído aqui, compile o proxy a partir da fonte (em inglês).

  8. Inicie o proxy.

    Dependendo da linguagem de programação e do ambiente, você pode iniciar o proxy usando soquetes TCP ou Unix.

    Soquetes TCP

    1. Copie o nome de conexão da instância da página Detalhes da instância.

      Por exemplo: myproject:us-central1:myinstance.

    2. Se você estiver usando uma conta de serviço para autenticar o proxy, anote o local em que a chave privada foi criada na máquina cliente durante a criação da conta de serviço.
    3. Inicie o proxy.

      Algumas strings possíveis de chamada do proxy:

      • Usando autenticação do SDK do Cloud:
        ./cloud_sql_proxy -instances=<INSTANCE_CONNECTION_NAME>=tcp:5432
        
        A porta especificada não pode estar em uso, por exemplo, por um servidor de banco de dados local.
      • Usando uma conta de serviço e a especificação explícita de uma instância (recomendado para ambientes de produção):
        ./cloud_sql_proxy -instances=<INSTANCE_CONNECTION_NAME>=tcp:5432 \
                          -credential_file=<PATH_TO_KEY_FILE> &
        

      Para mais informações sobre as opções de proxy, consulte Opções para autenticar o proxy e Opções para especificar instâncias.

    Soquetes Unix

    1. Se estiver usando a especificação explícita de instâncias, copie o nome de conexão da instância da página Detalhes da instância.
    2. Crie o diretório em que os soquetes do proxy ficarão:
      sudo mkdir /cloudsql; sudo chmod 777 /cloudsql
    3. Se você estiver usando uma conta de serviço para autenticar o proxy, anote o local em que a chave privada foi criada na máquina cliente durante a criação da conta de serviço.
    4. Abra uma nova janela de terminal e inicie o proxy.

      Algumas strings possíveis de chamada do proxy:

      • Usando uma conta de serviço e a especificação explícita de uma instância (recomendado para ambientes de produção):
        ./cloud_sql_proxy -dir=/cloudsql -instances=<INSTANCE_CONNECTION_NAME> \
                          -credential_file=<PATH_TO_KEY_FILE> &
      • Usando a autenticação do SDK do Cloud e a descoberta automática de instâncias:
        ./cloud_sql_proxy -dir=/cloudsql &

      É melhor iniciar o proxy em seu próprio terminal, assim você pode monitorar as respostas dele sem misturá-las com as respostas de outros programas.

      Para mais informações sobre as opções de proxy, consulte Opções para autenticar o proxy e Opções para especificar instâncias.

  9. Inicie a sessão psql.

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

    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 ou consulte a página de suporte do Cloud SQL.

Próximas etapas

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

Enviar comentários sobre…

Cloud SQL para PostgreSQL