Como se conectar ao Cloud SQL usando aplicativos externos

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

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

Opções de conexão

A tabela a seguir compara as opções de conexão a uma instância do Cloud SQL a partir de um aplicativo externo:

Opção de conexão Protegida, criptografada? Mais informações Observações
Endereço IP público com SSL Sim Requer gerenciamento de certificado SSL.
Endereço IP público sem SSL Não Não recomendado para instâncias de produção.
Cloud SQL Proxy Sim
Imagem do Cloud SQL Proxy Docker Sim
Biblioteca de soquetes JDBC Sim Somente a linguagem de programação Java.
Biblioteca Go Proxy Sim Somente a linguagem de programação Go.
Cloud Shell Não Usa o Cloud SQL Proxy para se conectar a partir do Console do Google Cloud. Melhor opção para tarefas de administração que exigem a ferramenta de linha de comando sqlcmd.
Apps Script Sim O Apps Script consegue se conectar a bancos de dados externos pelo serviço JDBC, um wrapper que usa a tecnologia Java Database Connectivity padrão.

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 linguagem de programação Java ou Go, você terá algumas alternativas ao uso do Cloud SQL Proxy. Saiba mais.

1. Ative a API

Ative a API Cloud SQL Admin.

Ative 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

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

Windows de 32 bits

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

3. Determinar como você autenticará o proxy

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

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

Caso queira usar uma conta de serviço para fornecer as credenciais ao proxy, você precisará criá-la com permissões suficientes. Se você estiver usando os papéis mais detalhados de gerenciamento de identidade e acesso (IAM) para gerenciar suas permissões do Cloud SQL, atribua à conta de serviço um papel que inclua a permissão cloudsql.instances.connect. Os papéis predefinidos do Cloud SQL que incluem essa permissão são os seguintes:

  • Cliente do Cloud SQL
  • Editor do Cloud SQL
  • Administrador do Cloud SQL

Se você estiver usando os papéis legados (visualizador, editor e proprietário) do projeto, a conta de serviço precisará ter pelo menos o papel de editor.

  1. Acesse a página Contas de serviço no Console do Google Cloud.

    Acessar a página "Contas de serviço"

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

    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.

  6. Altere o ID da conta de serviço para um valor exclusivo e facilmente reconhecível.
  7. Clique em Fornecer uma nova chave privada e confirme se o tipo de chave é JSON.
  8. 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.

É possível iniciar o proxy usando soquetes TCP.

Soquetes TCP

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

    Por exemplo, myproject:myregion: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:1433
      
      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 -instances=<INSTANCE_CONNECTION_NAME>=tcp:1433 \
                        -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.

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 forma que se conectaria a um soquete TCP.

Soquetes TCP

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

127.0.0.1:1433

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

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. Consulte Opções para autenticar o proxy do Cloud SQL.

A seguir