Conexão pelo Cloud SQL Proxy

MySQL | PostgreSQL | SQL Server

Nesta página, descrevemos como conectar um cliente psql (em inglês) à sua instância do Cloud SQL usando o Cloud SQL Proxy, em vez de IP.

Para informações sobre como conectar um cliente psql a uma instância do Cloud SQL usando um IP público, consulte esta página.

Para mais informações sobre como o proxy funciona, consulte Sobre o Cloud SQL Proxy.

Antes de começar

Antes de conectar um psql a uma instância do Cloud SQL, é necessário:

Ativar a API Cloud SQL Admin

Ative a API
Criar uma instância do Cloud SQL, incluindo a configuração do usuário padrão.

Para mais informações sobre como criar instâncias, consulte Como criar instâncias.

Para mais informações sobre como configurar o usuário padrão, consulte Como configurar a conta de usuário padrão.
Instalar o cliente psql.
Instalar e inicializar o Cloud SDK.
Se necessário, instalar o cliente Docker.

Opções para autenticar o Cloud SQL Proxy

Todas essas opções usam um INSTANCE_CONNECTION_NAME como a string de conexão para identificar uma instância do Cloud SQL. Encontre o INSTANCE_CONNECTION_NAME na Visão geral da sua instância no Google Cloud Console ou executando o comando a seguir:

gcloud sql instances describe INSTANCE_NAME

Por exemplo, myproject:myregion:myinstance.

Algumas dessas opções usam um arquivo de credenciais JSON que inclui a chave privada RSA da conta. Para instruções sobre como criar um arquivo de credenciais JSON para uma conta de serviço, consulte Como criar uma conta de serviço.

O Cloud SQL Proxy fornece várias alternativas para autenticação, dependendo do seu ambiente. O proxy verifica cada um dos itens a seguir, na ordem a seguir, usando o primeiro item encontrado para tentar autenticar:

Credenciais fornecidas pela sinalização credential_file.
Use uma conta de serviço para criar e fazer o download do arquivo JSON associado e defina a sinalização -credential_file para o caminho do arquivo quando iniciar o Cloud SQL Proxy. A conta de serviço precisa ter as permissões necessárias para a instância do Cloud SQL.
Para usar essa opção na linha de comando, invoque o comando cloud_sql_proxy com a sinalização -credential_file definida para o caminho e o nome de um arquivo de credencial JSON. O caminho pode ser absoluto ou relativo ao diretório de trabalho atual. Exemplo:
```
./cloud_sql_proxy -credential_file=PATH_TO_KEY_FILE -instances=INSTANCE_CONNECTION_NAME
  
```
Para instruções detalhadas sobre como adicionar papéis do IAM a uma conta de serviço, consulte Como conceder papéis a contas de serviço.
Para mais informações sobre os papéis compatíveis com o Cloud SQL, consulte Controle de acesso do projeto para o Cloud SQL.
Credenciais fornecidas por um token de acesso.
Crie um token de acesso e invoque o comentário cloud_sql_proxy com a sinalização -token definida como um token de acesso do OAuth 2.0. Exemplo:
```
./cloud_sql_proxy -token=ACCESS_TOKEN -instances=INSTANCE_CONNECTION_NAME
  
```
Credenciais fornecidas por uma variável de ambiente.
Essa opção é semelhante a usar a sinalização -credential_file, mas, neste caso você especifica o arquivo de credencial JSON definido na variável de ambiente GOOGLE_APPLICATION_CREDENTIALS, em vez de usar o argumento de linha de comando -credential_filecode>.
Credenciais de um cliente autenticado do Cloud SDK.
Se você tiver instalado a ferramenta de linha de comando do Cloud e tiver autenticado sua conta pessoal, o Cloud SQL Proxy poderá usar as mesmas credenciais da conta. Esse método é especialmente útil para você usar um dos outros métodos de autenticação. ambiente de desenvolvimento em funcionamento. Para um ambiente de produção,
para permitir que o proxy use as credenciais do SDK do Cloud, use o comando gcloud auth login para autenticar o SDK do Cloud.
É possível determinar quais são as credenciais atuais do SDK do Cloud usando o comando gcloud auth list.

Se nenhuma conta foi selecionada para gcloud auth login, o proxy verifica se há uma conta selecionada para gcloud application-default login.
Credenciais associadas à instância do Compute Engine
Se você estiver usando uma instância do Compute Engine para se conectar ao Cloud SQL, o proxy poderá usar a conta de serviço associada a essa instância. Se a conta de serviço tiver as permissões necessárias para a instância do Cloud SQL, o proxy será autenticado com êxito.
Se a instância do Compute Engine estiver no mesmo projeto que a instância do Cloud SQL, a conta de serviço padrão da primeira terá as permissões necessárias para autenticar o proxy. Se as duas instâncias estiverem em projetos diferentes, adicione a conta de serviço da instância do Compute Engine ao projeto que contém a instância do Cloud SQL.
Conta de serviço padrão do ambiente
Se o proxy não conseguir encontrar credenciais em nenhum dos locais cobertos anteriormente, ele seguirá a lógica documentada em Como configurar a autenticação para aplicativos de produção de servidor para servidor. Alguns ambientes (como Compute Engine, App Engine e outros) fornecem uma conta de serviço padrão que o aplicativo pode usar para autenticar por padrão. Para usar uma conta de serviço padrão, ela precisa ter as permissões descritas em papéis e permissões. Para mais informações sobre a abordagem do Google Cloud para autenticação, consulte Visão geral da autenticação.

Crie uma conta de serviço

Se você estiver se conectando do Compute Engine, verifique se a VM tem o scope apropriado para se conectar usando a API Cloud SQL Admin.

Configure a conta de serviço para ter um dos seguintes escopos de acesso:

https://www.googleapis.com/auth/sqlservice.admin
https://www.googleapis.com/auth/cloud-platform

Acesse a página Contas de serviço no Console do Google Cloud.
Acessar 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.
Na caixa de diálogo Criar conta de serviço, forneça um nome descritivo para a conta.
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
Altere o ID da conta de serviço para um valor exclusivo e facilmente reconhecível.
Clique em Fornecer uma nova chave privada e confirme se o tipo de chave é JSON.
Clique em Criar
O arquivo da chave privada é transferido para sua máquina. Você pode movê-lo para outro local. Mantenha-o seguro.

Instalar o Cloud SQL Proxy

Linux de 64 bits

Faça o download do proxy:

wget https://dl.google.com/cloudsql/cloud_sql_proxy.linux.amd64 -O cloud_sql_proxy

Torne o proxy executável:
```
chmod +x cloud_sql_proxy
```

Linux de 32 bits

Faça o download do proxy:

wget https://dl.google.com/cloudsql/cloud_sql_proxy.linux.386 -O cloud_sql_proxy

Torne o proxy executável:
```
chmod +x cloud_sql_proxy
```

macOS de 64 bits

Faça o download do proxy:

curl -o cloud_sql_proxy https://dl.google.com/cloudsql/cloud_sql_proxy.darwin.amd64

Torne o proxy executável:
```
chmod +x cloud_sql_proxy
```

macOS de 32 bits

Faça o download do proxy:

curl -o cloud_sql_proxy https://dl.google.com/cloudsql/cloud_sql_proxy.darwin.386

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.

Imagem de proxy do Docker

Por conveniência, a equipe do Cloud SQL mantém várias imagens de contêiner que contêm o Cloud SQL Proxy para uso pelos nossos clientes. Para mais informações sobre essas imagens, consulte o repositório do Cloud SQL Proxy no GitHub. É possível extrair a imagem mais recente na sua máquina local usando o Docker com o seguinte comando:

docker pull gcr.io/cloudsql-docker/gce-proxy:1.19.1

Outros SOs

Para outros sistemas operacionais não incluídos aqui, compile o proxy a partir da fonte.

Inicie o Cloud SQL Proxy

Dependendo da linguagem e do ambiente, é possível iniciar o proxy usando soquetes TCP, soquetes Unix ou a imagem do proxy do Docker. O binário de proxy se conecta a uma ou mais instâncias do Cloud SQL especificadas na linha de comando e abre uma conexão local como TCP ou 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.

Sockets TCP

Para conexões TCP, o proxy detecta em localhost (127.0.0.1) por padrão. Portanto, quando você especifica tcp: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, veja como fazer o proxy detectar a conexão local em 0.0.0.0:1234:

  ./cloud_sql_proxy -instances=INSTANCE_CONNECTION_NAME=tcp:0.0.0.0:1234

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
```
.
Por exemplo, myproject:myregion:myinstance.
Se a instância tiver IP público e particular configurados e você quiser que o proxy use o endereço IP particular, forneça a seguinte opção ao iniciar o proxy:
```
-ip_address_types=PRIVATE
```
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.
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.
- 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_NAM=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.

Sockets Unix

O Cloud SQL Proxy também pode detectar em um soquete Unix, que é um mecanismo padrão do Posix para usar uma pasta para 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.

O padrão PostgreSQL requer um sufixo `.s.PGSQL.5432` no caminho do soquete. Algumas bibliotecas aplicam esse sufixo automaticamente, mas outras exigem que você especifique o caminho do soquete da seguinte forma:

/cloudsql/INSTANCE_CONNECTION_NAME/.s.PGSQL.5432

Para criar e usar um soquete Unix, o diretório de destino precisa existir e o proxy 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 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
```
.
Por exemplo, myproject:myregion:myinstance.
Crie o diretório em que os soquetes do proxy ficarão:
```
sudo mkdir /cloudsql; sudo chmod 777 /cloudsql
```
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.
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 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 para autenticar o proxy e Opções para especificar instâncias.

Observação: ao usar um soquete Unix para se conectar ao Cloud SQL usando o Cloud SQL Proxy, verifique se o comprimento do nome de arquivo do soquete não ultrapassa o limite do sistema. Depende do sistema, mas geralmente é entre 91 e 108 caracteres. No Linux, o tamanho geralmente é definido como 108. Use o seguinte comando para verificar:

cat /usr/include/linux/un.h | grep "define UNIX_PATH_MAX"

Imagem do proxy Docker

Para executar o Cloud SQL Proxy em um contêiner do Docker, use a imagem do Proxy Docker disponível no Google Container Registry.

Você pode iniciar o proxy usando soquetes TCP ou soquetes 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 Visão geral da sua instância no Google Cloud Console ou executando o comando a seguir:

gcloud sql instances describe INSTANCE_NAME

Por exemplo, myproject:myregion:myinstance.

Dependendo da linguagem e do ambiente, inicie o proxy 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:/config \\
  -p 127.0.0.1:5432:5432 \\
  gcr.io/cloudsql-docker/gce-proxy:1.19.1 /cloud_sql_proxy \\
  -instances=INSTANCE_CONNECTION_NAME=tcp:0.0.0.0:5432 -credential_file=/config

Se você usa as credenciais fornecidas pela instância do Compute Engine, não inclua o parâmetro credential_file e a linha -v PATH_TO_KEY_FILE:/config.

Sempre especifique o prefixo 127.0.0.1 em "-p" para que o proxy 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:/config \\
  gcr.io/cloudsql-docker/gce-proxy:1.19.1 /cloud_sql_proxy -dir=/cloudsql \\
  -instances=INSTANCE_CONNECTION_NAME -credential_file=/config

Se você usa as credenciais fornecidas pela instância do Compute Engine, não inclua o parâmetro credential_file e a linha -v PATH_TO_KEY_FILE:/config.

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

Outros argumentos de linha de comando

Os exemplos acima abrangem os casos de uso mais comuns, mas o Cloud SQL Proxy também tem outras opções de configuração que podem ser definidas com argumentos de linha de comando. Para receber ajuda sobre argumentos de linha de comando, use a sinalização -help para ver a documentação mais recente:

./cloud_sql_proxy -help

Consulte o README no repositório do Cloud SQL Proxy no GitHub (em inglês) para ver outros exemplos de como usar as opções de linha de comando do Cloud SQL Proxy.

Conecte-se ao Cloud SQL Proxy

A string da conexão usada depende de como você iniciou o proxy: usando um soquete TCP, um soquete Unix ou o docker.

Sockets TCP

Inicie o cliente psql:
```
psql "host=127.0.0.1 sslmode=disable dbname=DB_NAME user=USERNAME"
```
O proxy fornece uma conexão criptografada mesmo que o parâmetro sslmode esteja definido como disable.

Quando você estabelece conexão usando soquetes TCP, o endereço de acesso do proxy é 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 user=USERNAME"
```
O proxy fornece uma conexão criptografada mesmo que o parâmetro sslmode esteja definido como disable.
Digite a senha.
O prompt do psql é exibido.

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.

Amostras de código específicas da linguagem

Você pode se conectar ao proxy por qualquer linguagem que permita se conectar a um soquete Unix ou TCP. Veja abaixo alguns snippets de código de exemplos completos no GitHub para ajudar você a entender como eles funcionam em conjunto no aplicativo.

Como se conectar com soquetes Unix

Instrução de chamada de proxy:

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

Python

Para ver esse snippet no contexto de um aplicativo da Web, consulte o README no GitHub (em inglês).

cloud-sql/postgres/sqlalchemy/main.py

Ver no GitHub

# Remember - storing secrets in plaintext is potentially unsafe. Consider using
# something like https://cloud.google.com/secret-manager/docs/overview to help keep
# secrets secret.
db_user = os.environ["DB_USER"]
db_pass = os.environ["DB_PASS"]
db_name = os.environ["DB_NAME"]
db_socket_dir = os.environ.get("DB_SOCKET_DIR", "/cloudsql")
cloud_sql_connection_name = os.environ["CLOUD_SQL_CONNECTION_NAME"]

pool = sqlalchemy.create_engine(

    # Equivalent URL:
    # postgres+pg8000://<db_user>:<db_pass>@/<db_name>
    #                         ?unix_sock=<socket_path>/<cloud_sql_instance_name>/.s.PGSQL.5432
    sqlalchemy.engine.url.URL(
        drivername="postgresql+pg8000",
        username=db_user,  # e.g. "my-database-user"
        password=db_pass,  # e.g. "my-database-password"
        database=db_name,  # e.g. "my-database-name"
        query={
            "unix_sock": "{}/{}/.s.PGSQL.5432".format(
                db_socket_dir,  # e.g. "/cloudsql"
                cloud_sql_connection_name)  # i.e "<PROJECT-NAME>:<INSTANCE-REGION>:<INSTANCE-NAME>"
        }
    ),
    **db_config
)

Java

Para ver esse snippet no contexto de um aplicativo da Web, consulte o README no GitHub (em inglês).

cloud-sql/postgres/servlet/src/main/java/com/example/cloudsql/ConnectionPoolContextListener.java

Ver no GitHub

// Note: For Java users, the Cloud SQL JDBC Socket Factory can provide authenticated connections
// which is preferred to using the Cloud SQL Proxy with Unix sockets.
// See https://github.com/GoogleCloudPlatform/cloud-sql-jdbc-socket-factory for details.

// The configuration object specifies behaviors for the connection pool.
HikariConfig config = new HikariConfig();

// The following URL is equivalent to setting the config options below:
// jdbc:postgresql:///<DB_NAME>?cloudSqlInstance=<CLOUD_SQL_CONNECTION_NAME>&
// socketFactory=com.google.cloud.sql.postgres.SocketFactory&user=<DB_USER>&password=<DB_PASS>
// See the link below for more info on building a JDBC URL for the Cloud SQL JDBC Socket Factory
// https://github.com/GoogleCloudPlatform/cloud-sql-jdbc-socket-factory#creating-the-jdbc-url

// Configure which instance and what database user to connect with.
config.setJdbcUrl(String.format("jdbc:postgresql:///%s", DB_NAME));
config.setUsername(DB_USER); // e.g. "root", "postgres"
config.setPassword(DB_PASS); // e.g. "my-password"

config.addDataSourceProperty("socketFactory", "com.google.cloud.sql.postgres.SocketFactory");
config.addDataSourceProperty("cloudSqlInstance", CLOUD_SQL_CONNECTION_NAME);

// The ipTypes argument can be used to specify a comma delimited list of preferred IP types
// for connecting to a Cloud SQL instance. The argument ipTypes=PRIVATE will force the
// SocketFactory to connect with an instance's associated private IP.
config.addDataSourceProperty("ipTypes", "PUBLIC,PRIVATE");

// ... Specify additional connection properties here.
// ...

// Initialize the connection pool using the configuration object.
DataSource pool = new HikariDataSource(config);

Node.js

Para ver esse snippet no contexto de um aplicativo da Web, consulte o README no GitHub (em inglês).

cloud-sql/postgres/knex/server.js

Ver no GitHub

const createUnixSocketPool = config => {
  const dbSocketPath = process.env.DB_SOCKET_PATH || '/cloudsql';

  // Establish a connection to the database
  return Knex({
    client: 'pg',
    connection: {
      user: process.env.DB_USER, // e.g. 'my-user'
      password: process.env.DB_PASS, // e.g. 'my-user-password'
      database: process.env.DB_NAME, // e.g. 'my-database'
      host: `${dbSocketPath}/${process.env.CLOUD_SQL_CONNECTION_NAME}`,
    },
    // ... Specify additional properties here.
    ...config,
  });
};

C#

Para ver esse snippet no contexto de um aplicativo da Web, consulte o README no GitHub (em inglês).

cloud-sql/postgres/Startup.cs

Ver no GitHub

// Equivalent connection string:
// "Server=<dbSocketDir>/<INSTANCE_CONNECTION_NAME>;Uid=<DB_USER>;Pwd=<DB_PASS>;Database=<DB_NAME>"
String dbSocketDir = Environment.GetEnvironmentVariable("DB_SOCKET_PATH") ?? "/cloudsql";
String instanceConnectionName = Environment.GetEnvironmentVariable("INSTANCE_CONNECTION_NAME");
var connectionString = new NpgsqlConnectionStringBuilder()
{
    // The Cloud SQL proxy provides encryption between the proxy and instance.
    SslMode = SslMode.Disable,
    // Remember - storing secrets in plain text is potentially unsafe. Consider using
    // something like https://cloud.google.com/secret-manager/docs/overview to help keep
    // secrets secret.
    Host = String.Format("{0}/{1}", dbSocketDir, instanceConnectionName),
    Username = Environment.GetEnvironmentVariable("DB_USER"), // e.g. 'my-db-user
    Password = Environment.GetEnvironmentVariable("DB_PASS"), // e.g. 'my-db-password'
    Database = Environment.GetEnvironmentVariable("DB_NAME"), // e.g. 'my-database'
};
connectionString.Pooling = true;
// Specify additional properties here.
return connectionString;

Go

Para ver esse snippet no contexto de um aplicativo da Web, consulte o README no GitHub (em inglês).

cloudsql/postgres/database-sql/cloudsql.go

Ver no GitHub

var (
	dbUser                 = mustGetenv("DB_USER")                  // e.g. 'my-db-user'
	dbPwd                  = mustGetenv("DB_PASS")                  // e.g. 'my-db-password'
	instanceConnectionName = mustGetenv("INSTANCE_CONNECTION_NAME") // e.g. 'project:region:instance'
	dbName                 = mustGetenv("DB_NAME")                  // e.g. 'my-database'
)

socketDir, isSet := os.LookupEnv("DB_SOCKET_DIR")
if !isSet {
	socketDir = "/cloudsql"
}

var dbURI string
dbURI = fmt.Sprintf("user=%s password=%s database=%s host=%s/%s", dbUser, dbPwd, dbName, socketDir, instanceConnectionName)

// dbPool is the pool of database connections.
dbPool, err := sql.Open("pgx", dbURI)
if err != nil {
	return nil, fmt.Errorf("sql.Open: %v", err)
}

// ...

return dbPool, nil

Ruby

Para ver esse snippet no contexto de um aplicativo da Web, consulte o README no GitHub (em inglês).

cloud-sql/postgres/activerecord/config/database.yml

Ver no GitHub

production:
  adapter: postgresql
  # Configure additional properties here.
  username: <%= ENV["DB_USER"] %>  # e.g. "my-database-user"
  password: <%= ENV["DB_PASS"] %> # e.g. "my-database-password"
  database: <%= ENV.fetch("DB_NAME") { "vote_production" } %>
  # If connecting via unix domain socket, specify the socket path as host
  host:  "<%= ENV.fetch("DB_SOCKET_DIR") { '/cloudsql' } %>/<%= ENV["INSTANCE_CONNECTION_NAME"] %>"

PHP

Para ver esse snippet no contexto de um aplicativo da Web, consulte o README no GitHub (em inglês).

cloud_sql/postgres/pdo/src/DBInitializer.php

Ver no GitHub

// $username = 'your_db_user';
// $password = 'yoursupersecretpassword';
// $dbName = 'your_db_name';
// $connectionName = getenv("CLOUD_SQL_CONNECTION_NAME");
// $socketDir = getenv('DB_SOCKET_DIR') ?: '/cloudsql';

// Connect using UNIX sockets
$dsn = sprintf(
    'pgsql:dbname=%s;host=%s/%s',
    $dbName,
    $socketDir,
    $connectionName
);

// Connect to the database.
$conn = new PDO($dsn, $username, $password, $connConfig);

Como se conectar com TCP

Instrução de chamada de proxy:

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

Python

Para ver esse snippet no contexto de um aplicativo da Web, consulte o README no GitHub.

cloud-sql/postgres/sqlalchemy/main.py

Ver no GitHub

# Remember - storing secrets in plaintext is potentially unsafe. Consider using
# something like https://cloud.google.com/secret-manager/docs/overview to help keep
# secrets secret.
db_user = os.environ["DB_USER"]
db_pass = os.environ["DB_PASS"]
db_name = os.environ["DB_NAME"]
db_host = os.environ["DB_HOST"]

# Extract host and port from db_host
host_args = db_host.split(":")
db_hostname, db_port = host_args[0], int(host_args[1])

pool = sqlalchemy.create_engine(
    # Equivalent URL:
    # postgres+pg8000://<db_user>:<db_pass>@<db_host>:<db_port>/<db_name>
    sqlalchemy.engine.url.URL(
        drivername="postgresql+pg8000",
        username=db_user,  # e.g. "my-database-user"
        password=db_pass,  # e.g. "my-database-password"
        host=db_hostname,  # e.g. "127.0.0.1"
        port=db_port,  # e.g. 5432
        database=db_name  # e.g. "my-database-name"
    ),
    **db_config
)

Java

Para ver esse snippet no contexto de um aplicativo da Web, consulte o README no GitHub (em inglês).

cloud-sql/postgres/servlet/src/main/java/com/example/cloudsql/ConnectionPoolContextListener.java

Ver no GitHub

// Note: For Java users, the Cloud SQL JDBC Socket Factory can provide authenticated connections
// which is preferred to using the Cloud SQL Proxy with Unix sockets.
// See https://github.com/GoogleCloudPlatform/cloud-sql-jdbc-socket-factory for details.

// The configuration object specifies behaviors for the connection pool.
HikariConfig config = new HikariConfig();

// The following URL is equivalent to setting the config options below:
// jdbc:postgresql:///<DB_NAME>?cloudSqlInstance=<CLOUD_SQL_CONNECTION_NAME>&
// socketFactory=com.google.cloud.sql.postgres.SocketFactory&user=<DB_USER>&password=<DB_PASS>
// See the link below for more info on building a JDBC URL for the Cloud SQL JDBC Socket Factory
// https://github.com/GoogleCloudPlatform/cloud-sql-jdbc-socket-factory#creating-the-jdbc-url

// Configure which instance and what database user to connect with.
config.setJdbcUrl(String.format("jdbc:postgresql:///%s", DB_NAME));
config.setUsername(DB_USER); // e.g. "root", "postgres"
config.setPassword(DB_PASS); // e.g. "my-password"

config.addDataSourceProperty("socketFactory", "com.google.cloud.sql.postgres.SocketFactory");
config.addDataSourceProperty("cloudSqlInstance", CLOUD_SQL_CONNECTION_NAME);

// The ipTypes argument can be used to specify a comma delimited list of preferred IP types
// for connecting to a Cloud SQL instance. The argument ipTypes=PRIVATE will force the
// SocketFactory to connect with an instance's associated private IP.
config.addDataSourceProperty("ipTypes", "PUBLIC,PRIVATE");

// ... Specify additional connection properties here.
// ...

// Initialize the connection pool using the configuration object.
DataSource pool = new HikariDataSource(config);

Node.js

Para ver esse snippet no contexto de um aplicativo da Web, consulte o README no GitHub.

cloud-sql/postgres/knex/server.js

Ver no GitHub

const createTcpPool = config => {
  // Extract host and port from socket address
  const dbSocketAddr = process.env.DB_HOST.split(':'); // e.g. '127.0.0.1:5432'

  // Establish a connection to the database
  return Knex({
    client: 'pg',
    connection: {
      user: process.env.DB_USER, // e.g. 'my-user'
      password: process.env.DB_PASS, // e.g. 'my-user-password'
      database: process.env.DB_NAME, // e.g. 'my-database'
      host: dbSocketAddr[0], // e.g. '127.0.0.1'
      port: dbSocketAddr[1], // e.g. '5432'
    },
    // ... Specify additional properties here.
    ...config,
  });
};

Go

Para ver esse snippet no contexto de um aplicativo da Web, consulte o README no GitHub.

cloudsql/postgres/database-sql/cloudsql.go

Ver no GitHub

var (
	dbUser    = mustGetenv("DB_USER")     // e.g. 'my-db-user'
	dbPwd     = mustGetenv("DB_PASS")     // e.g. 'my-db-password'
	dbTcpHost = mustGetenv("DB_TCP_HOST") // e.g. '127.0.0.1' ('172.17.0.1' if deployed to GAE Flex)
	dbPort    = mustGetenv("DB_PORT")     // e.g. '5432'
	dbName    = mustGetenv("DB_NAME")     // e.g. 'my-database'
)

var dbURI string
dbURI = fmt.Sprintf("host=%s user=%s password=%s port=%s database=%s", dbTcpHost, dbUser, dbPwd, dbPort, dbName)

// dbPool is the pool of database connections.
dbPool, err := sql.Open("pgx", dbURI)
if err != nil {
	return nil, fmt.Errorf("sql.Open: %v", err)
}

// ...

return dbPool, nil

C#

Para ver esse snippet no contexto de um aplicativo da Web, consulte o README no GitHub (em inglês).

cloud-sql/postgres/Startup.cs

Ver no GitHub

            // Equivalent connection string:
            // "Uid=<DB_USER>;Pwd=<DB_PASS>;Host=<DB_HOST>;Database=<DB_NAME>;"
            var connectionString = new NpgsqlConnectionStringBuilder()
            {
                // The Cloud SQL proxy provides encryption between the proxy and instance.
                SslMode = SslMode.Disable,

                // Remember - storing secrets in plain text is potentially unsafe. Consider using
                // something like https://cloud.google.com/secret-manager/docs/overview to help keep
                // secrets secret.
                Host = Environment.GetEnvironmentVariable("DB_HOST"),     // e.g. '127.0.0.1'
                // Set Host to 'cloudsql' when deploying to App Engine Flexible environment
                Username = Environment.GetEnvironmentVariable("DB_USER"), // e.g. 'my-db-user'
                Password = Environment.GetEnvironmentVariable("DB_PASS"), // e.g. 'my-db-password'
                Database = Environment.GetEnvironmentVariable("DB_NAME"), // e.g. 'my-database'
            };
            connectionString.Pooling = true;
            // Specify additional properties here.
            return connectionString;

Ruby

Para ver esse snippet no contexto de um aplicativo da Web, consulte o README no GitHub.

cloud-sql/postgres/activerecord/config/database.yml

Ver no GitHub

development:
  adapter: postgresql
  # Configure additional properties here.
  username: <%= ENV["DB_USER"] %>  # e.g. "my-database-user"
  password: <%= ENV["DB_PASS"] %> # e.g. "my-database-password"
  database: <%= ENV.fetch("DB_NAME") { "vote_development" } %>
  host: <%= ENV.fetch("DB_HOST") { "127.0.0.1" }%> # '172.17.0.1' if deployed to GAE Flex
  port: <%= ENV.fetch("DB_PORT")  { 5432 }%>

PHP

Para ver esse snippet no contexto de um aplicativo da Web, consulte o README no GitHub.

cloud_sql/postgres/pdo/src/DBInitializer.php

Ver no GitHub

// $username = 'your_db_user';
// $password = 'yoursupersecretpassword';
// $dbName = 'your_db_name';
// $dbHost = "127.0.0.1";

// Connect using TCP
$dsn = sprintf('pgsql:dbname=%s;host=%s', $dbName, $dbHost);

// Connect to the database
$conn = new PDO($dsn, $username, $password, $connConfig);

Tópicos adicionais:

Como usar o proxy com IP particular

Para se conectar a uma instância do Cloud SQL usando o IP particular, o proxy precisa estar em um recurso com acesso à mesma rede VPC que a instância.

O proxy usa o IP para estabelecer uma conexão com a instância do Cloud SQL. Por padrão, o proxy tenta se conectar usando um endereço IPv4 público. Se sua instância do Cloud SQL tiver apenas IP particular, o proxy usará o endereço IP privado para se conectar.

Se a instância tiver IP público e particular configurados e você quiser que o proxy use o endereço IP particular, forneça a seguinte opção ao iniciar o proxy:

-ip_address_types=PRIVATE

Como executar o proxy em um processo separado

Executar o Cloud SQL Proxy em um processo de terminal separado pode ser útil para evitar misturar a saída do console com a saída de outros programas. Use a sintaxe mostrada abaixo para invocar o proxy em um processo separado.

Linux

No Linux ou no macOS, use um & à direita na linha de comando para iniciar o proxy em um processo separado:

./cloud_sql_proxy -instances=INSTANCE_CONNECTION_NAME=tcp:PORT_NUMBER
  -credential_file=PATH_TO_KEY_FILE &

Windows

No Windows PowerShell, use o comando Start-Process para iniciar o proxy em um processo separado:

Start-Process -filepath "cloud_sql_proxy.exe"
  -ArgumentList "-instances=INSTANCE_CONNECTION_NAME=tcp:PORT_NUMBER
  -credential_file=PATH_TO_KEY_FILE"

Como executar o Cloud SQL Proxy em um contêiner do Docker

Para executar o Cloud SQL Proxy em um contêiner do Docker, use a imagem do Proxy Docker disponível no Google Container Registry. Você pode instalar a imagem do Proxy Docker com este comando gcloud:

docker pull gcr.io/cloudsql-docker/gce-proxy:1.19.1

Você pode iniciar o proxy usando soquetes TCP ou soquetes Unix, com os comandos mostrados abaixo.

Soquetes TCP

    docker run -d \
      -v PATH_TO_KEY_FILE:/config \
      -p 127.0.0.1:5432:5432 \
      gcr.io/cloudsql-docker/gce-proxy:1.19.1 /cloud_sql_proxy \
      -instances=INSTANCE_CONNECTION_NAME=tcp:0.0.0.0:5432 \
      -credential_file=/config

Soquetes Unix

    docker run -d \
      -v /PATH_TO_HOST_TARGET:/PATH_TO_GUEST_TARGET \
      -v PATH_TO_KEY_FILE:/config \
      gcr.io/cloudsql-docker/gce-proxy:1.19.1 /cloud_sql_proxy -dir=/cloudsql \
      -instances=INSTANCE_CONNECTION_NAME
      -credential_file=/config/PATH_TO_KEY_FILE

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

Se você usa as credenciais fornecidas pela instância do Compute Engine, não inclua o parâmetro credential_file e a linha -v PATH_TO_KEY_FILE:/config.

Como executar o Cloud SQL Proxy como um serviço

Executar o proxy como um serviço em segundo plano pode ser conveniente para desenvolvimento e teste locais. Quando você precisar acessar sua instância do Cloud SQL, poderá iniciar o serviço em segundo plano e interrompê-lo quando terminar.

No momento, o Cloud SQL Proxy não é compatível com a execução como um serviço do Windows, mas os gerenciadores de serviço de terceiros podem ser usados para executá-lo como um serviço. Por exemplo, você pode usar o NSSM para configurar o proxy como um serviço do Windows. O NSSM monitora o proxy e o reinicia automaticamente se ele parar de responder. Consulte a documentação do NSSM para mais informações.

Dicas para trabalhar com o Cloud SQL Proxy

Invocação do Cloud SQL Proxy

Todas as invocações de proxy de exemplo iniciam o proxy em segundo plano. Assim, um prompt é retornado. É preferível reservar esse terminal para o proxy, a fim de evitar que a saída seja confundida com a saída de outros programas. Além disso, a saída do proxy pode ajudá-lo a diagnosticar problemas de conexão, portanto, pode ser útil capturá-la em um arquivo de registros. Se você não iniciar o proxy em segundo plano, a saída será stdout, a menos que seja redirecionada.

Não é necessário usar /cloudsql como o diretório dos soquetes do proxy. Esse nome de diretório foi escolhido para minimizar as diferenças com as strings de conexão do App Engine. Porém, se você alterar o nome do diretório, mantenha um tamanho total mínimo, visto que é incorporado a uma string mais longa com limite de tamanho imposto pelo sistema operacional. Depende do sistema, mas geralmente é entre 91 e 108 caracteres. No Linux, o tamanho geralmente é definido como 108. Use o seguinte comando para verificar:

cat /usr/include/linux/un.h | grep "define UNIX_PATH_MAX"

Como usar o proxy para se conectar a várias instâncias

Você pode usar um cliente de proxy local para se conectar a várias instâncias do Cloud SQL. A maneira de fazer isso dependerá do uso de soquetes Unix ou TCP.

Sockets Unix

Para conectar o proxy a várias instâncias, forneça os nomes de conexão da instância com o parâmetro -instances, em uma lista separada por vírgulas e sem espaços. O proxy se conecta a cada instância quando é iniciado.

Conecte-se a cada instância usando o soquete correspondente no diretório especificado.

Exemplo:

      ./cloud_sql_proxy -dir=/cloudsql -instances=myProject:us-central1:myInstance,myProject:us-central1:myInstance2 &
      psql -U myUser -h /cloudsql/myProject:us-central1:myInstance2

Sockets TCP

Ao se conectar usando TCP, você especifica a porta na máquina que será usada para se conectar à instância. É necessário que cada instância tenha a própria porta. Por padrão, a ferramenta psql usa 5432, mas é possível especificar outra porta para ela.

Exemplo:

    # Start the proxy for two instances, each with its own port:

    ./cloud_sql_proxy -instances=myProject:us-central1:myInstance=tcp:5432,myProject:us-central1:myInstance2=tcp:1234

    # Connect to "myInstance" on port 5432, and "myInstance2" on port 1234

    psql -U myUser -h 127.0.0.1  --port 5432
    psql -U myUser -h 127.0.0.1  --port 1234

Invocações de proxy e strings de conexão do cliente psql

É possível usar invocações de proxy e strings de conexão, por exemplo, em comandos para um usuário do PostgreSQL myUser, para a instância myInstance, localizada em us-central1, no projeto myProject.

Uso de descoberta automática da instância com credenciais gcloud:

    ./cloud_sql_proxy -dir=/cloudsql &
    psql -U myUser -h /cloudsql/myProject:us-central1:myInstance

Como usar a descoberta do projeto com credenciais gcloud:

    ./cloud_sql_proxy -dir=/cloudsql -projects=myProject &
    psql -U myUser -h /cloudsql/myProject:us-central1:myInstance

Para uma instância do Compute Engine, com especificação explícita da instância:

    ./cloud_sql_proxy -dir=/cloudsql -instances=myProject:us-central1:myInstance &
    psql -U myUser -h /cloudsql/myProject:us-central1:myInstance

Para Unix, uso de TCP:

    ./cloud_sql_proxy -instances=myProject:us-central1:myInstance=tcp:5432 &
    psql -U myUser -h 127.0.0.1

Para Windows (no prompt da linha de comando):

    cloud_sql_proxy.exe -instances=myProject:us-central1:myInstance=tcp:5432
    psql -U myUser -h 127.0.0.1

Para mais informações sobre opções e strings de conexão do Cloud SQL Proxy, consulte Página do Cloud SQL Proxy no GitHub.

Solução de problemas de conexões do Cloud SQL Proxy

A imagem do Proxy Docker é baseada em uma versão específica do Cloud SQL Proxy. Quando uma nova versão do Cloud SQL Proxy estiver disponível, extraia a nova versão da imagem do Proxy Docker para manter seu ambiente atualizado. Você pode ver qual é a versão atual na página de versões do Cloud SQL Proxy no GitHub.

Se você tiver problemas para se conectar à instância do Cloud SQL usando o Cloud SQL Proxy, tente estas opções para encontrar o motivo.

Verifique a saída do proxy.

Muitas vezes, a saída do proxy pode ajudá-lo a determinar a origem do problema e como solucioná-lo. Redirecione a saída para um arquivo ou observe o terminal onde você iniciou o proxy.
Se você estiver recebendo um erro 403 notAuthorized e estiver usando uma conta de serviço para autenticar o proxy, verifique se a conta de serviço tem as permissões corretas.

Você pode verificar a conta de serviço pesquisando pelo ID dela na página "IAM". A conta precisa ter a permissão cloudsql.instances.connect. Todos os papéis predefinidos do Cloud SQL têm essa permissão, exceto Cloud SQL Viewer. Além disso, os papéis de projeto legados de Editor e Owner têm a permissão necessária.
Certifique-se de ativar a API Cloud SQL Admin.

Se não estiver, você verá uma saída como Error 403: Access Not Configured nos registros de proxy.
Se você estiver incluindo várias instâncias na lista de instâncias, use a vírgula como delimitador, sem espaços. Se você estiver usando o TCP, especifique portas diferentes para cada instância.
Se você estiver se conectando usando soquetes UNIX, liste o diretório fornecido quando iniciou o proxy para confirmar se os soquetes foram criados.
Se você tiver uma política de firewall para o tráfego de saída, verifique se ela permite conexões com a porta 3307 na instância do Cloud SQL de destino.

Observação: a porta 3307 é usada pelo Cloud SQL Proxy para se conectar ao servidor proxy. A porta 5432 é a porta padrão para o protocolo MySQL em uma conexão TCP direta (sem usar o Cloud SQL Proxy).

A seguir

Saiba mais sobre o proxy.
Saiba mais sobre o Gerenciamento de identidade e acesso.
Saiba mais sobre Contas de serviço.
Saiba mais sobre os dois níveis de controle de acesso para instâncias do Cloud SQL.
Crie usuários e bancos de dados.
Saiba mais sobre como se conectar à instância pelo aplicativo.
Saiba mais sobre o cliente psql (em inglês).
Conheça as opções de suporte.

Conexão pelo Cloud SQL Proxy

Antes de começar

Ativar a API Cloud SQL Admin

Opções para autenticar o Cloud SQL Proxy

Credenciais fornecidas pela sinalização credential_file.

Credenciais fornecidas por um token de acesso.

Credenciais fornecidas por uma variável de ambiente.

Credenciais de um cliente autenticado do Cloud SDK.

Credenciais associadas à instância do Compute Engine

Conta de serviço padrão do ambiente

Crie uma conta de serviço

Instalar o Cloud SQL Proxy

Linux de 64 bits

Linux de 32 bits

macOS de 64 bits

macOS de 32 bits

Windows de 64 bits

Windows de 32 bits

Imagem de proxy do Docker

Outros SOs

Inicie o Cloud SQL Proxy

Sockets TCP

Sockets Unix

Imagem do proxy Docker

Como usar soquetes TCP

Como usar soquetes Unix

Outros argumentos de linha de comando

Conecte-se ao Cloud SQL Proxy

Sockets TCP

Como usar soquetes Unix

Amostras de código específicas da linguagem

Como se conectar com soquetes Unix

Python

Java

Node.js

C#

Go

Ruby

PHP

Como se conectar com TCP

Python

Java

Node.js

Go

C#

Ruby

PHP

Tópicos adicionais:

Como usar o proxy com IP particular

Como executar o proxy em um processo separado

Linux

Windows

Como executar o Cloud SQL Proxy em um contêiner do Docker

Soquetes TCP

Soquetes Unix

Como executar o Cloud SQL Proxy como um serviço

Dicas para trabalhar com o Cloud SQL Proxy

Invocação do Cloud SQL Proxy

Como usar o proxy para se conectar a várias instâncias

Sockets Unix

Sockets TCP

Invocações de proxy e strings de conexão do cliente psql

Solução de problemas de conexões do Cloud SQL Proxy

A seguir