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.

Você pode se conectar a uma instância do Cloud SQL usando os 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:3306
      
      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:3306 \
                        -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:3306

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.

PyMySQL e TCP

Chame o proxy:

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

Instrução de conexão:

import pymysql
connection = pymysql.connect(host='127.0.0.1',
                             user='<USER>',
                             password='<PASSWORD>',
                             db='<DATABASE>')

PyMySQL e Unix

Chame o proxy:

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

Instrução de conexão:

import pymysql
connection = pymysql.connect(unix_socket='/cloudsql/' + <INSTANCE_CONNECTION_NAME>,
                             user='<USER>',
                             password='<PASSWORD>',
                             db='<DATABASE>')

SQLAlchemy e TCP

Chame o proxy:

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

Instrução de conexão:

from sqlalchemy import create_engine
engine = create_engine('mysql+pymysql://<USER>:<PASSWORD>@127.0.0.1/<DATABASE>')

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('mysql+pymysql://<USER>:<PASSWORD>@/<DATABASE>?unix_socket=/cloudsql/<INSTANCE_CONNECTION_NAME>')

Java

A linguagem de programação Java não oferece suporte nativo para soquetes Unix. Use 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 segunda geração sem colocar na lista de permissões endereços IP é usar a fábrica de soquete JDBC.

A fábrica de soquete JDBC oferece uma alternativa ao software de proxy do lado do cliente e exige que a Cloud SQL API esteja habilitada, 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/mysql"
)
...
cfg := mysql.Cfg(<INSTANCE_CONNECTION_NAME>, <DATABASE_USER>, <PASSWORD>)
cfg.DBName = <DATABASE_NAME>
db, err := mysql.DialCfg(cfg)

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:3306 &

Instrução de conexão:

import (
       "database/sql"
        _ "github.com/go-sql-driver/mysql"
)

dsn := fmt.Sprintf("%s:%s@tcp(%s)/%s",
       dbUser,
       dbPassword,
       "127.0.0.1:3306",
       dbName)
db, err := sql.Open("mysql", 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/go-sql-driver/mysql"
)

dsn := fmt.Sprintf("%s:%s@unix(/cloudsql/%s)/%s",
       dbUser,
       dbPassword,
       INSTANCE_CONNECTION_NAME,
       dbName)
db, err := sql.Open("mysql", 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.

Endereços IP para instâncias da Segunda geração:

  • IPv6: as instâncias da Segunda geração não dão suporte a IPv6.
  • IPv4: as instâncias da Segunda geração têm um endereço IPv4 estático atribuído automaticamente. Há uma pequena cobrança pelo endereço IP sempre que a instância é desativada.

Endereços IP para instâncias da Primeira geração:

Para instâncias da Primeira geração, o Cloud SQL aceita conexões de IP público por meio dos endereços IPv4 e IPv6. Conecte usando qualquer um dos protocolos ou ambos. Porém, não misture as versões de endereço IP em uma única conexão.

  • IPv6: cada instância da Primeira geração tem um endereço IPv6 atribuído automaticamente. Você não precisa atribuí-lo à instância.
  • IPv4: se você estiver se conectando a uma instância de primeira geração por IPv4, será preciso atualizar a instância para ter um endereço IPv4 público atribuído a ela. Esse endereço IP é estático. Há uma pequena cobrança pelo endereço IPv4 sempre que a instância é desativada.

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. Se você estiver se conectando à instância da Primeira geração via IPv4, atribua um endereço IPv4 à instância caso ainda não tenha feito isso:
    1. Acesse a página "Instâncias do Cloud SQL" no Console do Google Cloud Platform.

      Acessar a página "Instâncias" do Cloud SQL

    2. Clique no nome da instância para abrir a página Visão geral correspondente.
    3. Selecione a guia Endereço IP.
    4. Clique em Solicitar endereço IPv4.

      A cobrança por um endereço IPv4 acontece quando a instância permanece desativada. Para mais informações, consulte a página de preços.

  4. 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. Caso esteja se conectando a uma instância da Primeira geração e queira usar IPv4, você deverá atribuir um endereço IPv4 à instância:
    gcloud sql instances patch [INSTANCE_NAME] --assign-ip
    
  4. 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. Caso esteja se conectando a uma instância da Primeira geração e queira usar IPv4, você deverá atribuir um endereço IPv4 à instância:
    curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
           --header 'Content-Type: application/json' \
           --data '{"settings" : {"ipConfiguration" :
                                  {"ipv4Enabled" : "true"}}}' \
           -X PATCH \
           https://www.googleapis.com/sql/v1beta4/projects/[PROJECT-ID]/instances/[INSTANCE_NAME]
    
  4. 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]
    

    Observe o valor para ipv6Address (apenas instâncias da Primeira geração) ou ipAddresses.ipAddress para IPv4. 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, na sigla em inglês), entre outros.

A melhor solução para esses aplicativos é usar uma instância do Cloud SQL Segunda geração e se conectar usando o Cloud SQL Proxy. Essa solução oferece o melhor controle de acesso para a instância.

Caso você não consiga usar uma instância da Segunda geração, instale o próprio proxy ou abra o firewall e aplique SSL. Porém, nenhum desses métodos oferece a segurança e o controle das soluções de conectividade fornecidas por instâncias da Segunda geração.

Teste da conexão

Você pode usar o cliente MySQL para testar sua capacidade de se conectar do seu ambiente local. Para mais informações, consulte Como conectar o cliente MySQL usando endereços IP e Como conectar o cliente MySQL 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…

Cloud SQL para MySQL