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.

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 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 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 a partir de um aplicativo externo usando 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. 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 a partir da fonte.

3. Determinar como você autenticará o proxy

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

4. Caso obrigatório pelo método de autenticação, criar uma conta de serviç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, na sigla em inglês) 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 do projeto (Visualizador, Editor e Proprietário), a conta de serviço precisará ter pelo menos o papel 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 primitivo Editor selecionando Projeto > Editor, mas esse papel inclui permissões no Google Cloud.

    Caso não veja esses papéis, talvez seu usuário do Google Cloud não tenha a permissão resourcemanager.projects.setIamPolicy. Para verificar suas permissões, acesse a página "IAM" no Console do Google Cloud e procure 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.

Dependendo da linguagem e do ambiente, inicie o proxy usando os soquetes TCP ou Unix.

Sockets 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: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 incluindo explicitamente o nome da conexão da 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 para autenticar o proxy e Opções para especificar 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 incluindo explicitamente o nome da conexão da 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 Cloud SDK e a descoberta automática de instância: 
      ./cloud_sql_proxy -dir=/cloudsql &

    É melhor iniciar o proxy em seu próprio terminal, assim você pode monitorar a saída dele sem misturá-la com a saída de outros programas.

    Para mais informações sobre as opções de proxy, consulte Opções para autenticar o proxy e Opções para especificar instâncias.

  5. Ao usar um soquete Unix para se conectar ao Cloud SQL usando o Cloud SQL Proxy, verifique se comprimento do nome de arquivo do soquete não ultrapassa o limite do sistema. Isso depende do sistema, mas geralmente varia de 91 a 108 caracteres. No Linux, o comprimento geralmente é definido como 108. Use o seguinte comando para verificar:
    cat /usr/include/linux/un.h | grep "define UNIX_PATH_MAX"

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

.NET

Após iniciar o proxy, edite o arquivo appsettings.json e defina uma string de conexão em CloudSql:ConnectionString. Exemplo: 

{
  "CloudSQL" : {
     ConnectionString": "Host=127.0.0.1;Uid=DATABASE_USER;Pwd=PASSWORD;Database=DATABASE_NAME"
  }
}

Em seguida, crie uma conexão de banco de dados no arquivo Startup.cs: 

var connectionString = new NpgsqlConnectionStringBuilder(
    Configuration["CloudSql:ConnectionString"])
{
    // Connecting to a local proxy that does not support ssl.
    SslMode = SslMode.Disable
};
NpgsqlConnection connection =
    new NpgsqlConnection(connectionString.ConnectionString);

Go

É possível usar o Cloud SQL Proxy com a linguagem de programação Go de duas maneiras:

  1. Usando a biblioteca proxy em Go.
  2. Executando o proxy como um processo complementar.

Biblioteca Go Proxy

A biblioteca é a maneira mais fácil de se conectar ao Cloud SQL com 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. Consulte Opções para autenticar o Cloud SQL Proxy.

Soquetes 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",
       DATABASE_USER,,
       PASSWORD,
       DATABASE_NAME)
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,
       DATABASE_USER,
       PASSWORD,
       DATABASE_NAME)
db, err := sql.Open("postgres", dsn)

Java

A linguagem de programação Java não dá suporte nativo para soquetes Unix. É possível usar soquetes TCP ou uma biblioteca compatível com o soquete Unix e que tem o Cloud SQL Proxy, mas a maneira mais fácil de se conectar a uma instância do PostgreSQL sem adicionar endereços de rede autorizados é usar a fábrica do soquete JDBC.

Ela oferece uma alternativa ao software de proxy do lado do cliente e exige que a API Cloud SQL Admin seja ativada, assim como faz 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. É preciso instalar e autenticar o SDK do Cloud antes de usar a fábrica de soquete.

Consulte Cloud SQL Socket Factory para drivers JDBC para ver exemplos de código Consulte o arquivo README (em inglês) para ver instruções.

PHP

PDO e TCP

Invoque o proxy:

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

Os exemplos a seguir se conectam ao Cloud SQL usando objetos de dados PHP (PDO, na sigla em inglês) [link em inglês]: 

// Use a Data source name (DSN) to connect to Cloud SQL through the proxy
$dsn = 'pgsql:host=127.0.0.1;port=5432;dbname=DATABASE_NAME';
// Instantiate your DB using the DSN, username, and password
$dbUser = 'DATABASE_USER';
$dbPass = 'PASSWORD';
$db = new PDO($dsn, $dbUser, $dbPass);

Soquetes PDO e Unix

Invoque o proxy:

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

Os exemplos a seguir se conectam ao Cloud SQL usando o PDO (em inglês): 

// Use a Data source name (DSN) to connect to Cloud SQL through the proxy
$dsn = 'pgsql:host=/cloudsql/INSTANCE_CONNECTION_NAME;dbname=DATABASE_NAME';
// Instantiate your DB using the DSN, username, and password
$dbUser = 'DATABASE_USER';
$dbPass = 'PASSWORD';
$db = new PDO($dsn, $dbUser, $dbPass);

pgsql e TCP

Invoque o proxy:

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

Os exemplos a seguir se conectam ao Cloud SQL usando o mysqli (em inglês):

// Instantiate your DB using the database host, port, name, username, and password
$conn = pg_connect(sprintf('host=127.0.0.1 port=5432 dbname=%s user=%s password=%s',
    'DATABASE_NAME',
    'DATABASE_USER',
    'PASSWORD'
));

pgsql e soquetes Unix

Invoque o proxy:

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

Os exemplos a seguir se conectam ao Cloud SQL usando o mysqli (em inglês):

// Instantiate your DB using the database name, socket, username, and password
$conn = pg_connect(sprintf('host=/cloudsql/%s dbname=%s user=%s password=%s',
    'INSTANCE_CONNECTION_NAME',
    'DATABASE_NAME',
    'DATABASE_USER',
    'PASSWORD'
));

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

Invoque o proxy:

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

Instrução de conexão:

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

Psycopg2 e Unix

Invoque o proxy:

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

Instrução de conexão:

import psycopg2
conn = psycopg2.connect(user=DATABASE_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://DATABASE_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://DATABASE_USER:PASSWORD@/?host=/cloudsql/INSTANCE_CONNECTION_NAME')

Ruby

Ruby pg e TCP

Invoque o proxy:

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

Os exemplos a seguir se conectam ao Cloud SQL usando o Ruby pg do RubyGem (em inglês):

require "pg"
begin
    con = PG.connect host: "127.0.0.1", port: 5432,
        dbname: "DATABASE_NAME", user: "DB_USER",
        password: "PASSWORD"
    puts con.server_version
rescue PG::Error => e
    puts e.message
ensure
    con.close if con
end

Ruby pg e soquetes Unix

Invoque o proxy:

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

Os exemplos a seguir se conectam ao Cloud SQL usando o Ruby pg do RubyGem (em inglês):

require "pg"
begin
    con = PG.connect host: "/cloudsql/CONNECTION_NAME",
        dbname: "DATABASE_NAME", user: "DB_USER",
        password: "PASSWORD"
    puts con.server_version
rescue PG::Error => e
    puts e.message
ensure
    con.close if con
end

Rails e TCP

Invoque o proxy:

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

Em config/databases.yml, use a seguinte configuração: 

postgresql_settings: &postgresql_settings
  adapter: postgresql
  encoding: unicode
  pool: 5
  username: DATABASE_USER
  password: PASSWORD
  database: DATABASE_NAME
  host: 127.0.0.1:5432

Rails e soquetes Unix

Invoque o proxy:

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

Em config/databases.yml, use a seguinte configuração:

postgresql_settings: &postgresql_settings
  adapter: postgresql
  encoding: unicode
  pool: 5
  username: DATABASE_USER
  password: PASSWORD
  database: DATABASE_NAME
  socket: /cloudsql/INSTANCE_CONNECTION_NAME

Como configurar o acesso para conexões de 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 em conexões de IP públicas, siga estas instruções:

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: 
    gcloud auth login
ACCESS_TOKEN="$(gcloud auth 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 veja 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.

Teste da 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 veja 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.

A seguir