Nesta página, descrevemos como usar o cliente psql, instalado em uma instância do Compute Engine, para se conectar ao Cloud SQL.
É possível usar IP particular, IP público, o proxy de autenticação do Cloud SQL ou a imagem Docker do proxy de autenticação do Cloud SQL.
Para instruções detalhadas sobre como executar um aplicativo da Web de amostra do Compute Engine conectado ao Cloud SQL, consulte o guia de início rápido para se conectar do Compute Engine
Antes de começar
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.
IP particular
Para se conectar ao Cloud SQL por uma instância do Compute Engine usando IP particular, o acesso a serviços particulares precisa ser configurado para o ambiente, e a instância do Cloud SQL precisa ser configurada para usar 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 usar IP privado
Siga as instruções em Como configurar a conectividade do IP privado.
2. Abrir uma conexão de terminal do Cloud Shell com a instância do Compute Engine.
Use as instruções apropriadas, dependendo do sistema operacional da instância:
- Para o Linux, consulte Como se conectar com as VMs do Linux.
- Para o Windows, consulte Como se conectar com as VMs do Windows.
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).
3. 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
- 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. - Instale o banco de dados 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_ADDRESS -U USERNAME
É possível encontrar o endereço IP privado na página de instâncias do Cloud SQL ou executando o seguinte comando gcloud
:
gcloud sql instances list
IP público
Para se conectar usando 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 como adicionar 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 Compute Engine como uma rede com permissão para conectar-se à instância do Cloud SQL.
Para mais informações, consulte Como configurar o acesso para conexões IP públicas.
3. Abrir uma conexão de terminal do Cloud Shell com a instância do Compute Engine.
Use as instruções apropriadas, dependendo do sistema operacional da instância:
- Para o Linux, consulte Como se conectar com as VMs do Linux.
- Para o Windows, consulte Como se conectar com as VMs do Windows.
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).
4. 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
- 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. - Instale o banco de dados 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 USERNAME
É possível encontrar o endereço IP privado na
página de instâncias do Cloud SQL ou executando o
seguinte comando gcloud
:
gcloud sql instances list
Para um exemplo de como estabelecer uma conexão usando SSL, consulte Como se conectar com SSL.
6. O prompt do psql é exibido.
7. Se você precisar manter as conexões não utilizadas ativas:
Configure o TCP keepalive.
Para mais informações, consulte Como estabelecer comunicação entre as suas instâncias e a Internet na documentação do Compute Engine.
As conexões são mantidas ativas automaticamente para instâncias.
Proxy do Cloud SQL Auth
Para se conectar usando o proxy de autenticação do Cloud SQL por meio do Compute Engine:1. Ative a API Cloud SQL Admin.
2. Crie uma conta de serviço
- No Console do Google Cloud, acesse a página Contas de serviço.
- Selecione o projeto que contém a instância do Cloud SQL.
- Clique em Criar conta de serviço.
- Preencha o campo Nome da conta de serviço.
- Altere o ID da conta de serviço para um valor exclusivo e facilmente reconhecível, depois clique em Criar e continuar.
-
Clique no campo Selecionar papel e escolha um dos seguintes papéis:
- Cloud SQL > Cliente do Cloud SQL
- Cloud SQL > Editor do Cloud SQL
- Cloud SQL > Administrador do Cloud SQL
- Clique em Concluído para terminar a criação da conta de serviço.
- Clique no menu de ações da sua nova conta de serviço e selecione Gerenciar chaves.
- Clique no menu suspenso Adicionar chave e clique em Criar nova chave.
-
Confirme se o tipo de chave é JSON e clique em Criar.
O arquivo da chave privada é transferido para sua máquina. Você pode movê-lo para outro local. Mantenha-o protegido.
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:
- Acesse a listagem de instâncias do Compute Engine no Console do Google Cloud.
- Se necessário, selecione o projeto associado à instância do Compute Engine.
- Selecione a instância do Compute Engine para exibir as propriedades dela.
- Nas propriedades da instância do Compute Engine, copie o nome da conta de serviço.
- Acesse a página Projetos do IAM e do administrador no Console do Google Cloud.
- Selecione o projeto que contém a instância do Cloud SQL.
- Procure o nome da conta de serviço.
-
Se a conta de serviço já estiver lá e tiver um papel que inclua a permissão
cloudsql.instances.connect
, prossiga para a etapa 4.Os papéis
Cloud SQL Client
,Cloud SQL Editor
eCloud SQL Admin
fornecem a permissão necessária, assim como os papéis de projetoEditor
eOwner
herdados. - Caso contrário, clique em Adicionar para adicioná-la.
Na caixa de diálogo Adicionar membros , forneça o nome da conta de serviço e selecione uma função que inclua a permissão
cloudsql.instances.connect
(qualquer papel predefinido do Cloud SQL que não seja o Leitor funcionará).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.- Clique em Adicionar.
Você verá a conta de serviço listada com o papel especificado.
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:
- Para o Linux, consulte Como se conectar com instâncias do Linux.
- Para o Windows, consulte Como se conectar com instâncias do Windows.
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).
4. 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
- 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. - Instale o banco de dados PostgreSQL de acordo com as orientações contidas na página de download.
5. Instale o proxy de autenticação do Cloud SQL na instância do Compute Engine.
Linux de 64 bits
- 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
- Torne o proxy do Cloud SQL Auth executável:
chmod +x cloud-sql-proxy
Linux de 32 bits
- 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
- Se o comando
curl
não for encontrado, executesudo apt install curl
e repita o comando de download. - 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 paracloud-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 paracloud-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.6. Inicie o proxy de autenticação do Cloud SQL.
Dependendo da linguagem e do ambiente, é possível iniciar o proxy de autenticação do Cloud SQL usando soquetes TCP, soquetes Unix ou a respectiva imagem Docker. O binário do proxy de autenticação do Cloud SQL se conecta a uma ou mais instâncias do Cloud SQL especificadas na linha de comando e abre uma conexão local tanto como um soquete TCP como um soquete Unix. Outros aplicativos e serviços, como o código do aplicativo ou as ferramentas de cliente de gerenciamento de banco de dados, podem se conectar a instâncias do Cloud SQL por meio dessas conexões de soquete TCP ou Unix.
Soquetes TCP
Para conexões TCP, o proxy de autenticação do Cloud SQL faz a detecção em localhost
(127.0.0.1
) por padrão.
Portanto, quando você especifica --port PORT_NUMBER
para uma instância, a conexão local é em 127.0.0.1:PORT_NUMBER
.
Como alternativa, você pode especificar um endereço diferente para a conexão local.
Por exemplo, confira como fazer o proxy de autenticação do Cloud SQL realizar as detecções em 0.0.0.0:1234
para a
conexão local:
./cloud-sql-proxy --address 0.0.0.0 --port 1234 INSTANCE_CONNECTION_NAME
Copie o INSTANCE_CONNECTION_NAME. Isso pode ser encontrado na página Visão geral da instância no console do Google Cloud ou executando o seguinte comando: .
gcloud sql instances describe INSTANCE_NAME --format='value(connectionName)'
.Por exemplo, myproject:myregion:myinstance.
- Se a instância tiver IP público e privado configurados e você quiser que o
proxy de autenticação do Cloud SQL use o endereço IP privado,
forneça a seguinte opção ao iniciar o proxy de autenticação do Cloud SQL:
--private-ip
- Se você estiver usando uma conta de serviço para autenticar o proxy de autenticação do Cloud SQL, anote o local em que o arquivo da chave privada foi criado na máquina do cliente durante a criação da conta de serviço.
- Inicie o proxy de autenticação do Cloud SQL.
Algumas strings de invocação possíveis do proxy de autenticação do Cloud SQL:
- Usando autenticação do SDK do Cloud:
./cloud-sql-proxy --port 5432 INSTANCE_CONNECTION_NAME
A porta especificada não pode estar em uso, por exemplo, por um servidor de banco de dados local. - Usar uma conta de serviço e incluir explicitamente o nome da conexão da instância
(recomendado para ambientes de produção):
./cloud-sql-proxy \ --credentials-file PATH_TO_KEY_FILE INSTANCE_CONNECTION_NAME &
Para mais informações sobre as opções do proxy de autenticação do Cloud SQL, consulte Opções de autenticação do proxy de autenticação do Cloud SQL e Opções para especificar instâncias.
- Usando autenticação do SDK do Cloud:
Soquetes Unix
O proxy de autenticação do Cloud SQL também pode fazer detecções em um soquete Unix, um mecanismo padrão do Posix para usar uma pasta a fim de gerenciar a comunicação entre dois processos em execução no mesmo host. As vantagens de usar soquetes Unix são a segurança aprimorada e a latência menor. No entanto, não é possível acessar um soquete Unix de uma máquina externa.
Para criar e usar um soquete Unix, o diretório de destino precisa existir e o proxy de autenticação do Cloud SQL e o aplicativo precisam ter acesso de leitura e gravação a ele.
- Se você estiver usando a especificação explícita de instâncias, copie a INSTANCE_CONNECTION_NAME.
Isso está disponível na página Visão geral da
instância no console do Google Cloud ou executando o
seguinte comando:
gcloud sql instances describe INSTANCE_NAME --format='value(connectionName)'
Por exemplo, myproject:myregion:myinstance.
- Crie o diretório onde ficarão os soquetes do proxy de autenticação do Cloud SQL:
sudo mkdir /cloudsql; sudo chmod 777 /cloudsql
- Se você estiver usando uma conta de serviço para autenticar o proxy de autenticação do Cloud SQL, anote o local em que o arquivo da chave privada foi criado na máquina do cliente durante a criação da conta de serviço.
- Abra uma nova janela de terminal do Cloud Shell e inicie o proxy de autenticação do Cloud SQL.
Algumas strings de invocação possíveis do proxy de autenticação do Cloud SQL:
- Usar uma conta de serviço e incluir explicitamente o nome da conexão da instância
(recomendado para ambientes de produção):
./cloud-sql-proxy --unix-socket /cloudsql --credentials-file PATH_TO_KEY_FILE INSTANCE_CONNECTION_NAME &
- Usando a autenticação do SDK do Cloud e a descoberta automática de instâncias:
./cloud-sql-proxy --unix-socket /cloudsql &
Inicie o proxy de autenticação do Cloud SQL no próprio terminal do Cloud Shell para monitorar a saída dele sem misturá-la com a saída de outros programas.
Para mais informações sobre as opções do proxy de autenticação do Cloud SQL, consulte Opções de autenticação do proxy de autenticação do Cloud SQL e Opções para especificar instâncias.
- Usar uma conta de serviço e incluir explicitamente o nome da conexão da instância
(recomendado para ambientes de produção):
Docker
Para executar o proxy de autenticação do Cloud SQL em um contêiner do Docker, use a respectiva imagem Docker disponível no Google Container Registry.
Inicie o proxy de autenticação do Cloud SQL usando soquetes TCP ou Unix, com os comandos mostrados abaixo. As opções usam uma INSTANCE_CONNECTION_NAME como a string de conexão para identificar uma instância do Cloud SQL. Encontre o INSTANCE_CONNECTION_NAME na página Visão geral da instância no console do Google Cloud ou executando este comando:
gcloud sql instances describe INSTANCE_NAME.
Por exemplo, myproject:myregion:myinstance
.
Dependendo da linguagem e do ambiente, inicie o proxy de autenticação do Cloud SQL 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.
Como usar soquetes TCP
docker run -d \\ -v PATH_TO_KEY_FILE:/path/to/service-account-key.json \\ -p 127.0.0.1:5432:5432 \\ gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.11.2 \\ --address 0.0.0.0 --port 5432 \\ --credentials-file /path/to/service-account-key.json INSTANCE_CONNECTION_NAME
Se você usa as credenciais fornecidas pela instância do Compute Engine, não inclua o parâmetro --credentials-file
e a linha -v PATH_TO_KEY_FILE:/path/to/service-account-key.json
.
Sempre especifique o prefixo 127.0.0.1
em -p para que o proxy de autenticação do Cloud SQL 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.
Como usar soquetes Unix
docker run -d -v /cloudsql:/cloudsql \\ -v PATH_TO_KEY_FILE:/path/to/service-account-key.json \\ gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.11.2 --unix-socket=/cloudsql \\ --credentials-file /path/to/service-account-key.json INSTANCE_CONNECTION_NAME
Se você usa as credenciais fornecidas pela instância do Compute Engine, não inclua o parâmetro --credentials-file
e a linha -v PATH_TO_KEY_FILE:/path/to/service-account-key.json
.
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 do proxy de autenticação do Cloud SQL.
7. Inicie a sessão psql.
A string de conexão usada depende de como você iniciou o proxy de autenticação do Cloud SQL, ou seja, usando um soquete TCP, um soquete Unix ou o Docker.
Soquetes TCP
- Inicie o cliente psql:
psql "host=127.0.0.1 sslmode=disable dbname=DB_NAME user=USERNAME"
Mesmo que o parâmetro
sslmode
esteja definido comodisable
, o proxy de autenticação do Cloud SQL fornece uma conexão criptografada.Quando você se conecta usando soquetes TCP, o proxy de autenticação do Cloud SQL é acessado por meio de
127.0.0.1
. - Se solicitado, digite a senha.
- O prompt do psql é exibido.
Como usar soquetes Unix
- Inicie o cliente psql:
psql "sslmode=disable host=/cloudsql/INSTANCE_CONNECTION_NAME dbname=DB_NAME user=USERNAME"
Mesmo que o parâmetro
sslmode
esteja definido comodisable
, o proxy de autenticação do Cloud SQL fornece uma conexão criptografada. - Digite a senha.
- O prompt do psql é exibido.
Precisa de ajuda? Para receber ajuda na solução de problemas do proxy, consulte Solução de problemas de conexões do proxy de autenticação do Cloud SQL ou a página Suporte do Cloud SQL.
A seguir
- Receba ajuda para solucionar problemas de conexão do proxy de autenticação do Cloud SQL.
- Crie usuários e bancos de dados.
- Saiba mais sobre IP particular.
- Saiba mais sobre as opções de conexão à instância do aplicativo.
- Saiba mais sobre o cliente psql.
- Conheça as opções de suporte.