Conectar-se ao Cloud SQL para PostgreSQL usando o proxy do Cloud SQL Auth

Nesta página, você verá como se conectar ao Cloud SQL de um ambiente de teste local usando o proxy do Cloud SQL Auth. O proxy do Cloud SQL Auth fornece acesso seguro à instância do Cloud SQL sem a necessidade de redes autorizadas ou de configuração do SSL. Ao usar o proxy do Cloud SQL Auth, é possível se conectar à instância do Cloud SQL com segurança.

As instruções nesta página são apenas para um ambiente de teste e não podem ser usadas em ambientes de produção. Para mais informações sobre a configuração necessária para ambientes de produção, consulte Usar o proxy do Cloud SQL Auth em um ambiente de produção e Conectar-se usando o proxy do Cloud SQL Auth.

Antes de começar

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  3. Make sure that billing is enabled for your Google Cloud project.

  4. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  5. Make sure that billing is enabled for your Google Cloud project.

  6. Ative as APIs do Google Cloud necessárias.

    Console

    No console do Google Cloud, acesse a página APIs.

    Acesse APIs

    Ative a API Cloud SQL Admin.

    gcloud

    Clique no botão a seguir para abrir o Cloud Shell, que fornece acesso de linha de comando aos recursos do Google Cloud diretamente no navegador. O Cloud Shell pode ser usado para executar os comandos gcloud apresentados neste guia de início rápido.

    Abra o Cloud Shell

    Execute o comando gcloud services enable da seguinte maneira usando o Cloud Shell para ativar as APIs necessárias para este guia de início rápido:

    gcloud services enable sqladmin.googleapis.com

    Esse comando ativa as seguintes APIs:

    • API Cloud SQL Admin

Criar uma instância do Cloud SQL

Neste guia de início rápido, você usa o console do Google Cloud. Para usar a CLI gcloud, o cURL ou o PowerShell, consulte Criar instâncias.

  1. No console do Google Cloud, acesse a página Instâncias do Cloud SQL.

    Acesse "Instâncias do Cloud SQL"

  2. Clique em Criar instância.
  3. Clique em Escolher PostgreSQL.
  4. Insira myinstance para o ID da instância.
  5. Digite a senha do usuário postgres.

  6. Clique em Criar.

    Você retornará à lista de instâncias. É possível clicar na nova instância imediatamente para ver os detalhes, mas ela não estará disponível para outras operações até que seja inicializada.

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 da PostgreSQL Core Distribution referente à sua plataforma na página de downloads do PostgreSQL (em inglês).
    A 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.

Instalar o cliente do proxy de autenticação do Cloud SQL

O binário do proxy de autenticação do Cloud SQL a ser baixado depende do sistema operacional e do uso de um kernel de 32 ou 64 bits. Os modelos de hardware mais recentes usam kernel de 64 bits. Se você não tiver certeza se a máquina está executando um kernel de 32 ou 64 bits, use o comando uname -a para Linux ou macOS. Para o Windows, consulte a documentação do Windows.

Linux de 64 bits

  1. Faça o download do proxy de autenticação do Cloud SQL: 
    curl -o cloud-sql-proxy https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.11.2/cloud-sql-proxy.linux.amd64
  2. Torne o proxy do Cloud SQL Auth executável: 
    chmod +x cloud-sql-proxy

Linux de 32 bits

  1. Faça o download do proxy de autenticação do Cloud SQL: 
    curl -o cloud-sql-proxy https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.11.2/cloud-sql-proxy.linux.386
  2. Se o comando curl não for encontrado, execute sudo apt install curl e repita o comando de download.
  3. Torne o proxy do Cloud SQL Auth executável: 
    chmod +x cloud-sql-proxy

macOS de 64 bits

  1. Faça o download do proxy de autenticação do Cloud SQL: 
    curl -o cloud-sql-proxy https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.11.2/cloud-sql-proxy.darwin.amd64
  2. Torne o proxy do Cloud SQL Auth executável: 
    chmod +x cloud-sql-proxy

Mac M1

  1. Faça o download do proxy do Cloud SQL Auth: 
      curl -o cloud-sql-proxy https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.11.2/cloud-sql-proxy.darwin.arm64
  2. Torne o proxy do Cloud SQL Auth executável: 
      chmod +x cloud-sql-proxy

Windows de 64 bits

Clique com o botão direito do mouse em https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.11.2/cloud-sql-proxy.x64.exe e selecione Salvar link como para baixar o proxy do Cloud SQL Auth. Renomeie o arquivo para cloud-sql-proxy.exe.

Windows de 32 bits

Clique com o botão direito do mouse em https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.11.2/cloud-sql-proxy.x86.exe e selecione Salvar link como para baixar o proxy do Cloud SQL Auth. Renomeie o arquivo para cloud-sql-proxy.exe.

Imagem Docker do proxy do Cloud SQL Auth

O proxy do Cloud SQL Auth tem imagens de contêiner diferentes, como distroless, alpine e buster. A imagem de contêiner padrão do proxy do Cloud SQL Auth usa distroless, que não contém shell. Se você precisar de um shell ou de ferramentas relacionadas, faça o download de uma imagem baseada em alpine ou buster. Para mais informações, consulte Imagens de contêiner do proxy do Cloud SQL Auth.

Você pode extrair a imagem mais recente para sua máquina local usando o Docker usando o seguinte comando:

docker pull gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.11.2

Outros SOs

Para outros sistemas operacionais não incluídos aqui, compile o proxy do Cloud SQL Auth a partir do código-fonte.

Ver o nome da conexão da instância

  1. No console do Google Cloud, acesse a página Instâncias do Cloud SQL.

    Acesse "Instâncias do Cloud SQL"

  2. Clique no nome da instância para abrir a página Visão geral correspondente.
  3. Na seção Conectar-se a esta instância, copie o Nome da conexão. O nome da conexão está no formato projectID:region:instanceID.

Iniciar o proxy do Cloud SQL Auth.

Inicie o proxy do Cloud SQL Auth em um terminal próprio para você monitorar a saída. Substitua INSTANCE_CONNECTION_NAME pelo nome da conexão da instância copiado no passo anterior.

Para ambientes Linux, use este comando para iniciar o proxy do Cloud SQL Auth: 

./cloud-sql-proxy INSTANCE_CONNECTION_NAME

No PowerShell no Windows, use este comando para iniciar o proxy do Cloud SQL: 

.\cloud-sql-proxy.exe INSTANCE_CONNECTION_NAME

Você verá uma mensagem semelhante a esta:

Listening on 127.0.0.1:5432 for INSTANCE_CONNECTION_NAME
Ready for new connections

Execute o seguinte comando depois de substituir DB_NAME pelo nome do banco de dados do Cloud SQL:

psql "host=127.0.0.1 port=5432 sslmode=disable dbname=DB_NAME user=postgres"

No prompt "Inserir senha", insira a senha da conta do PostgreSQL.

Verifique se o prompt do PostgreSQL é exibido. Você se conectou ao banco de dados usando o cliente psql.

Volte para a janela do terminal em que você iniciou o proxy do Cloud SQL Auth. Você verá uma mensagem semelhante a esta:

New connection for myInstance

Limpar

Para evitar cobranças na conta do Google Cloud pelos recursos usados nesta página, siga estas etapas.

  1. No console do Google Cloud, acesse a página Instâncias do Cloud SQL.

    Acesse "Instâncias do Cloud SQL"

  2. Selecione a instância do myinstance para abrir a página Detalhes da instância.
  3. Na barra de ícones na parte superior da página, clique em Excluir.
  4. Na janela Excluir instância, digite o nome da instância e clique em Excluir.

Etapas de limpeza opcionais

Se você não estiver usando as APIs que foram ativadas como parte deste guia de início rápido, é possível desativá-las.

  • APIs que foram ativadas neste guia de início rápido:
    • API Cloud SQL Admin

  1. No console do Google Cloud, acesse a página APIs.

    Acesse APIs

  2. Selecione a API Cloud SQL Admin e clique no botão Desativar API.

A seguir