Como se conectar ao Cloud SQL por aplicativos externos

Veja nesta página como estabelecer uma conexão com o Cloud SQL a partir de um aplicativo executado fora do Google Cloud Platform.

Para ver informações sobre as diversas opções de conexão com o Cloud SQL, consulte Opções de conexão para aplicativos externos. Consulte Como configurar o IP público para ver mais informações.

As conexões do banco de dados consomem recursos no servidor e no aplicativo conectado. Sempre use boas práticas de gerenciamento de conexão para minimizar o espaço ocupado pelo seu aplicativo e reduzir a probabilidade de exceder os limites de conexão do Cloud SQL. Para ver mais informações, consulte Como gerenciar conexões de banco de dados.

Antes de começar

A concessão de acesso a um aplicativo não permite automaticamente que uma conta de usuário do banco de dados se conecte à instância. Para se conectar a uma instância, é necessário ter uma conta de usuário do banco de dados com que possa se conectar. Para novas instâncias, isso significa que é preciso configurar a conta de usuário padrão. Saiba mais.

É possível se conectar a uma instância do Cloud SQL pelos seguintes métodos:

Como se conectar por um aplicativo externo que usa o proxy

Se estiver configurando o Cloud SQL Proxy para um ambiente de teste local (e não para produção), você poderá usar o Guia de início rápido do Proxy em vez de seguir estas instruções.

Se estiver usando as linguagens de programação Java ou Go, você terá algumas alternativas ao uso do Cloud SQL Proxy. Saiba mais.

1. Ativar a API

Ativar Cloud SQL Admin API.

Ativar a API

2. Instalar o cliente do proxy na máquina local

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

macOS de 64 bits

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

macOS de 32 bits

  1. Faça o download do proxy: 
    curl -o cloud_sql_proxy https://dl.google.com/cloudsql/cloud_sql_proxy.darwin.386
  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).

3. Determinar como você autenticará o proxy

Saiba mais sobre opções de autenticação do proxy.

4. Criar uma conta de serviço, caso seja exigido pelo método de autenticação

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

5. Determinar como você especificará as instâncias para o proxy

Saiba mais sobre opções de especificação da instância do proxy.

6. Iniciar o proxy

As opções passadas para o proxy dependem das opções de autenticação e de especificação da instância escolhidas anteriormente.

Dependendo da linguagem e do ambiente, inicie o proxy usando os 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 de autenticação de proxy e Opções de especificação de 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 de autenticação de proxy e Opções de especificação de instâncias.

7. Atualizar o aplicativo para se conectar ao Cloud SQL usando o proxy

A instrução do código exato obrigatória para usar o proxy na conexão com a instância do Cloud SQL depende da linguagem e da biblioteca usadas.

Você se conecta ao proxy da mesma maneira que faria a um soquete TCP ou Unix (dependendo de como invocou o proxy):

Soquetes TCP

Com soquetes TCP, o proxy está disponível como um host local:

127.0.0.1:5432

Soquetes Unix

Com soquetes Unix, o proxy permanece disponível usando-se o seguinte caminho:

<PROXY_PATH>/<INSTANCE_CONNECTION_NAME>
Em que PROXY_PATH é o caminho para o diretório definido com a opção -dir quando você iniciou o proxy. Os exemplos nesta documentação usam /cloudsql. Encontre o nome de conexão da instância na página Detalhes da instância do Console do Google Cloud Platform ou use <PROJECT-ID>:<REGION>:<INSTANCE_NAME>.

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.

Informações e exemplos específicos da linguagem

Você pode se conectar ao proxy por qualquer linguagem que permita se conectar a um soquete Unix ou TCP. Veja a seguir algumas instruções de conexão e chamada de proxy de amostra para ajudar você a entender como elas funcionam juntas no aplicativo.

Python

As instruções de chamada de proxy abaixo usam autenticação do Cloud SDK por uma questão de brevidade, e a instrução de chamada pode variar, dependendo de como você se autentica e como especifica as instâncias. Saiba mais.

Psycopg2 e TCP

Chame o proxy:

./cloud_sql_proxy -instances=<INSTANCE_CONNECTION_NAME>=tcp:5432 &

Instrução de conexão:

import psycopg2
conn = psycopg2.connect(user=<USER>, password=<PASSWORD>,
                        host='localhost', port='5432')

Psycopg2 e Unix

Chame o proxy:

./cloud_sql_proxy -instances=<INSTANCE_CONNECTION_NAME> -dir=/cloudsql &

Instrução de conexão:

import psycopg2
conn = psycopg2.connect(user=<USER>, password=<PASSWORD>,
                        host='/cloudsql/<INSTANCE_CONNECTION_NAME>')

SQLAlchemy e TCP

Chame o proxy:

./cloud_sql_proxy -instances=<INSTANCE_CONNECTION_NAME>=tcp:5432 &

Instrução de conexão:

from sqlalchemy import create_engine
engine = create_engine('postgresql+psycopg2://<USER>:<PASSWORD>@localhost:5432/')

SQLAlchemy e Unix

Chame o proxy:

./cloud_sql_proxy -instances=<INSTANCE_CONNECTION_NAME> -dir=/cloudsql &

Instrução de conexão:

from sqlalchemy import create_engine
engine = create_engine('postgresql+psycopg2://<USER>:<PASSWORD>@/?host=/cloudsql/<INSTANCE_CONNECTION_NAME>')

Java

A linguagem de programação Java não oferece suporte nativo para soquetes Unix. Você pode usar soquetes TCP ou uma biblioteca compatível com o soquete Unix com o Cloud SQL Proxy, mas a maneira mais fácil de se conectar a uma instância de PostgreSQL sem colocar os endereços IP na lista de permissões é usar a fábrica de soquetes JDBC.

A fábrica de soquete JDBC oferece uma alternativa ao software de proxy do lado do cliente e exige que a API Cloud SQL esteja ativada, assim como o Cloud SQL Proxy. Essa fábrica oferece o mesmo nível de criptografia do proxy e se autentica com as credenciais do SDK do Cloud. Sendo assim, o SDK do Cloud precisa estar instalado e autenticado.

Consulte Cloud SQL Socket Factory para drivers JDBC para ver exemplos de código e o arquivo README para ver instruções.

Go

Você pode usar o Cloud SQL Proxy com a linguagem de programação Go de duas maneiras:

  • biblioteca Go Proxy
  • processo complementar
Biblioteca Go Proxy

A biblioteca é a maneira mais fácil de usar o proxy a partir de um programa Go, porque você não precisa iniciar explicitamente o proxy como o próprio processo.

import (
    "github.com/GoogleCloudPlatform/cloudsql-proxy/proxy/dialers/postgres"
)
...
dsn := fmt.Sprintf("host=%s dbname=%s user=%s password=%s sslmode=disable",
                   <INSTANCE_CONNECTION_NAME>,
                   <DATABASE_NAME>,
                   <DATABASE_USER>,
                   <PASSWORD>)
db, err := sql.Open("cloudsqlpostgres", dsn)

Para saber mais, consulte a página do GitHub sobre Cloud SQL Proxy (em inglês).

Processo complementar

Você também pode executar o proxy como um processo complementar e se conectar a ele de seu aplicativo.

As instruções de chamada de proxy abaixo usam autenticação do Cloud SDK por uma questão de brevidade, e a instrução de chamada pode variar, dependendo de como você se autentica e como especifica as instâncias. Saiba mais.

TCP

Instrução de chamada de proxy: 

./cloud_sql_proxy -instances=<INSTANCE_CONNECTION_NAME>=tcp:5432 &

Instrução de conexão: 

import (
       "database/sql"
        _ "github.com/lib/pq"
)

dsn := fmt.Sprintf("host=localhost port=5432 user=%s password=%s dbname=%s sslmode=disable",
       dbUser,
       dbPassword,
       dbName)
db, err := sql.Open("postgres", dsn)

Soquetes Unix

Instrução de chamada de proxy: 

./cloud_sql_proxy -instances=<INSTANCE_CONNECTION_NAME> -dir=/cloudsql &

Instrução de conexão: 

import (
       "database/sql"
        _ "github.com/lib/pq"
)

dsn := fmt.Sprintf("host=/cloudsql/%s user=%s password=%s dbname=%s sslmode=disable",
       INSTANCE_CONNECTION_NAME,
       dbUser,
       dbPassword,
       dbName)
db, err := sql.Open("postgres", dsn)

Como configurar o acesso para conexões IP públicas

Conceda qualquer acesso ao aplicativo para uma instância do Cloud SQL autorizando os endereços IP públicos que o aplicativo usa para se conectar.

Não é possível especificar uma rede privada (por exemplo, 10.x.x.x) como uma rede autorizada.

As instâncias do PostgreSQL são compatíveis apenas com endereços IPv4. Elas são configuradas automaticamente com um endereço IP estático.

Para configurar o acesso por meio de conexões IP:

Console

  1. Determine o endereço IP do aplicativo. Saiba mais.
  2. Autorize o endereço IP do aplicativo para se conectar à sua instância.

    Para mais informações, consulte Como adicionar um endereço autorizado.

  3. Você pode encontrar o endereço IP atribuído à sua instância na página Detalhes da instância. Esse é o valor que você precisa para a string de conexão do aplicativo.

gcloud

  1. Determine o endereço IP da máquina cliente. Saiba mais.
  2. Autorize o endereço IP do aplicativo para se conectar à sua instância.

    Para mais informações, consulte Como adicionar um endereço autorizado.

  3. Recupere o endereço IP da instância: 
    gcloud sql instances describe [INSTANCE_NAME]

    Na saída, encontre o campo ipAddress. Esse é o valor que você precisa para a string de conexão do aplicativo.

cURL

  1. Determine o endereço IP do aplicativo. Saiba mais.
  2. Autorize o endereço IP do aplicativo para se conectar à sua instância.

    Para mais informações, consulte Como adicionar um endereço autorizado.

  3. Recupere o endereço IP da instância: 
    ACCESS_TOKEN="$(gcloud auth application-default print-access-token)"
curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
       -X GET \
       https://www.googleapis.com/sql/v1beta4/projects/[PROJECT-ID]/instances/[INSTANCE_NAME]

    Anote o valor de ipAddresses.ipAddress. Esse é o valor que você precisa para a string de conexão do aplicativo.

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 configurar o acesso para aplicativos com endereços IP atribuídos dinamicamente

Alguns aplicativos precisam se conectar à instância do Cloud SQL usando um endereço IP atribuído dinamicamente (temporário). Esse é o caso dos aplicativos Platform as a Service (PaaS), entre outros.

Nesses casos, é necessário usar o Cloud SQL Proxy.

Como testar sua conexão

É possível usar o cliente psql para testar sua capacidade de se conectar do seu ambiente local. Para saber mais, consulte Como conectar o cliente psql usando endereços IP e Como conectar o cliente psql usando o Cloud SQL Proxy.

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 determinar o endereço IP do aplicativo

Para determinar o endereço IP de um computador que executa seu aplicativo com o objetivo de autorizar o acesso à sua instância do Cloud SQL desse endereço, use uma das seguintes opções:

  • Se o computador não estiver por trás de um proxy, faça login nele e use este link para determinar o endereço IP.
  • Se o computador estiver por trás de um proxy, faça login nele e use uma ferramenta ou serviço como o Teste de proxy para determinar o verdadeiro endereço IP.

Próximas etapas

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

Enviar comentários sobre…

Esta página
Comentários sobre a documentação
Cloud SQL para PostgreSQL
Comentários sobre o produto