Conectar usando o proxy do Cloud SQL Auth

MySQL   |  PostgreSQL   |  SQL Server

Nesta página, confira como estabelecer uma conexão com a instância do Cloud SQL usando o proxy de autenticação do Cloud SQL.

Para mais informações sobre como o proxy de autenticação do Cloud SQL funciona, consulte Sobre o proxy de autenticação do Cloud SQL.

Visão geral

Usar o proxy de autenticação do Cloud SQL é o método recomendado para se conectar a uma instância do Cloud SQL. O proxy de autenticação do Cloud SQL:

• Funciona com endpoints de IP público e particular
• Valida conexões usando credenciais de um usuário ou conta de serviço
• Encapsula a conexão em uma camada SSL/TLS autorizada para uma instância do Cloud SQL

Alguns serviços e aplicativos do Google Cloud usam o proxy de autenticação do Cloud SQL para fornecer conexões a caminhos de IP públicos com criptografia e autorização, incluindo o seguinte:

• Ambiente padrão do App Engine
• Ambiente flexível do App Engine
• Funções do Cloud Run
• Cloud Run

Os aplicativos em execução no Google Kubernetes Engine podem se conectar usando o proxy de autenticação do Cloud SQL.

Observação: para se conectar pelo Google Kubernetes Engine, recomendamos executar o proxy de autenticação do Cloud SQL em um padrão sidecar como um contêiner adicional que compartilha um pod com o aplicativo. Consulte também o guia de início rápido relacionado.

Confira uma introdução básica ao uso do proxy de autenticação no guia de início rápido para uso do proxy de autenticação do Cloud SQL.

Também é possível se conectar, com ou sem o proxy de autenticação do Cloud SQL, usando um cliente psql de uma máquina local ou do Compute Engine.

Antes de começar

Antes de se conectar a uma instância do Cloud SQL, faça o seguinte:

1. • Para um usuário ou conta de serviço, verifique se a conta tem o papel de cliente do Cloud SQL. Esse papel contém a permissão cloudsql.instances.connect, que autoriza um principal a se conectar a todas as instâncias do Cloud SQL em um projeto.

     Acessar a página IAM

   • Se quiser, é possível incluir uma condição do IAM na vinculação de política do IAM que conceda à conta permissão para se conectar apenas a uma instância específica do Cloud SQL.

2. Enable the Cloud SQL Admin API.

   Enable the API

3. Instale e inicialize a gcloud CLI.
4. Opcional. Instale o cliente Docker do proxy de autenticação do Cloud SQL.

Fazer o download do proxy de autenticação do Cloud SQL

Linux de 64 bits

1. Faça o download do proxy de autenticação do Cloud SQL:

   curl -o cloud-sql-proxy https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.13.0/cloud-sql-proxy.linux.amd64

2. Torne o proxy do Cloud SQL Auth executável:

   chmod +x cloud-sql-proxy

Linux de 32 bits

1. Faça o download do proxy de autenticação do Cloud SQL:

   curl -o cloud-sql-proxy https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.13.0/cloud-sql-proxy.linux.386

2. Se o comando curl não for encontrado, execute sudo apt install curl e repita o comando de download.
3. Torne o proxy do Cloud SQL Auth executável:

   chmod +x cloud-sql-proxy

macOS de 64 bits

1. Faça o download do proxy de autenticação do Cloud SQL:

   curl -o cloud-sql-proxy https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.13.0/cloud-sql-proxy.darwin.amd64

2. Torne o proxy do Cloud SQL Auth executável:

   chmod +x cloud-sql-proxy

Mac M1

1. Faça o download do proxy do Cloud SQL Auth:

     curl -o cloud-sql-proxy https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.13.0/cloud-sql-proxy.darwin.arm64
     

2. Torne o proxy do Cloud SQL Auth executável:

     chmod +x cloud-sql-proxy
     

Windows de 64 bits

Clique com o botão direito do mouse em https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.13.0/cloud-sql-proxy.x64.exe e selecione Salvar link como para fazer o download do proxy de autenticação do Cloud SQL. Renomeie o arquivo para cloud-sql-proxy.exe.

Windows de 32 bits

Clique com o botão direito do mouse em https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.13.0/cloud-sql-proxy.x86.exe e selecione Salvar link como para fazer o download do proxy de autenticação do Cloud SQL. Renomeie o arquivo para cloud-sql-proxy.exe.

Imagem Docker do proxy do Cloud SQL Auth

O proxy do Cloud SQL Auth tem imagens de contêiner diferentes, como distroless, alpine e buster. A imagem de contêiner padrão do proxy do Cloud SQL Auth usa distroless, que não contém shell. Se você precisar de um shell ou de ferramentas relacionadas, faça o download de uma imagem baseada em alpine ou buster. Para mais informações, consulte Imagens de contêiner do proxy do Cloud SQL Auth.

Você pode extrair a imagem mais recente para sua máquina local usando o Docker usando o seguinte comando:

docker pull gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.13.0

Observação: o proxy do Cloud SQL Auth usa um repositório que oferece suporte ao domínio gcr.io, mas disponibiliza imagens do Artifact Registry. Para mais informações, consulte Transição do Container Registry.

Outros SOs

Para outros sistemas operacionais não incluídos aqui, compile o proxy do Cloud SQL Auth a partir do código-fonte.

Iniciar o proxy do Cloud SQL Auth.

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

Aviso: tenha cuidado ao vincular o proxy de autenticação do Cloud SQL a uma interface externa. Qualquer um com acesso a essa interface/porta será autorizado a se conectar à instância.

Soquetes TCP

Para conexões TCP, o proxy de autenticação do Cloud SQL faz a detecção em localhost(127.0.0.1) por padrão. Portanto, quando você especifica --port 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, confira como fazer o proxy de autenticação do Cloud SQL realizar as detecções em 0.0.0.0:1234 para a conexão local:

./cloud-sql-proxy --address 0.0.0.0 --port 1234 INSTANCE_CONNECTION_NAME

1. 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 --format='value(connectionName)'

   Por exemplo, myproject:myregion:myinstance.

2. Se a instância tiver IP público e privado configurados e você quiser que o proxy de autenticação do Cloud SQL use o endereço IP privado, forneça a seguinte opção ao iniciar o proxy de autenticação do Cloud SQL:

   --private-ip

3. Se você estiver usando uma conta de serviço para autenticar o proxy de autenticação do Cloud SQL, anote o local em que o arquivo da chave privada foi criado na máquina do cliente durante a criação da conta de serviço.
4. Inicie o proxy de autenticação do Cloud SQL.

   Algumas strings de invocação possíveis do proxy de autenticação do Cloud SQL:

   • Usando autenticação do SDK do Cloud:

     ./cloud-sql-proxy --port 5432 INSTANCE_CONNECTION_NAME

     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 \
     --credentials-file PATH_TO_KEY_FILE INSTANCE_CONNECTION_NAME &

   Para mais informações sobre as opções do proxy de autenticação do Cloud SQL, consulte Opções para autenticar o proxy de autenticação do Cloud SQL.

Soquetes Unix

Observação: no momento, o proxy de autenticação do Cloud SQL não é compatível com soquetes Unix no Windows. Portanto, essa opção só está disponível para plataformas Linux e macOS.

O proxy de autenticação do Cloud SQL também pode fazer detecções em um soquete Unix, um mecanismo padrão do Posix para usar uma pasta a fim de 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.

Observação: o padrão do 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 de autenticação do Cloud SQL e o aplicativo precisam ter acesso de leitura e gravação a ele.

1. 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 --format='value(connectionName)'

   Por exemplo, myproject:myregion:myinstance.

2. Crie o diretório onde ficarão os soquetes do proxy de autenticação do Cloud SQL:

   sudo mkdir /cloudsql; sudo chmod 777 /cloudsql

3. Se você estiver usando uma conta de serviço para autenticar o proxy de autenticação do Cloud SQL, anote o local em que o arquivo da chave privada foi criado na máquina do cliente durante a criação da conta de serviço.
4. Abra uma nova janela de terminal do Cloud Shell e inicie o proxy de autenticação do Cloud SQL.

   Algumas strings de invocação possíveis do proxy de autenticação do Cloud SQL:

   • Usando a autenticação do SDK Google Cloud:

     ./cloud-sql-proxy --unix-socket /cloudsql INSTANCE_CONNECTION_NAME &

   • Usando uma conta de serviço:

       ./cloud-sql-proxy --unix-socket /cloudsql
       --credentials-file PATH_TO_KEY_FILE INSTANCE_CONNECTION_NAME &

   Inicie o proxy de autenticação do Cloud SQL no próprio terminal do Cloud Shell para monitorar a saída dele sem misturá-la com a saída de outros programas.

   Para mais informações sobre as opções do proxy de autenticação do Cloud SQL, consulte Opções para autenticar o proxy de autenticação do Cloud SQL.

   OBSERVAÇÃO: ao usar um soquete Unix para se conectar ao Cloud SQL por meio do proxy de autenticação do Cloud SQL, verifique se o comprimento do nome de arquivo do soquete não ultrapassa o limite do sistema. Isso será de acordo com o sistema, mas o valor geralmente fica entre 91 e 108 caracteres. No Linux, o tamanho geralmente é definido como 108 e é possível usar o seguinte comando para verificar:

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

Docker

Para executar o proxy de autenticação do Cloud SQL em um contêiner do Docker, use a respectiva imagem Docker disponível no Google Container Registry.

Inicie o proxy de autenticação do Cloud SQL usando soquetes TCP ou 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 página Visão geral da instância no console do Google Cloud ou executando este comando:

gcloud sql instances describe INSTANCE_NAME

.

Por exemplo, myproject:myregion:myinstance.

Observação: o proxy de autenticação do Cloud SQL não oferece suporte à detecção em soquetes de domínio Unix no Windows.

Dependendo da linguagem e do ambiente, inicie o proxy de autenticação do Cloud SQL 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:/path/to/service-account-key.json \\
  -p 127.0.0.1:5432:5432 \\
  gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.13.0 \\
  --address 0.0.0.0 --port 5432 \\
  --credentials-file /path/to/service-account-key.json INSTANCE_CONNECTION_NAME

Se você usa as credenciais fornecidas pela instância do Compute Engine, não inclua o parâmetro --credentials-file e a linha -v PATH_TO_KEY_FILE:/path/to/service-account-key.json.

Sempre especifique o prefixo 127.0.0.1 em -p para que o proxy de autenticação do Cloud SQL 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:/path/to/service-account-key.json \\
  gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.13.0 --unix-socket=/cloudsql \\
  --credentials-file /path/to/service-account-key.json INSTANCE_CONNECTION_NAME

Se você usa as credenciais fornecidas pela instância do Compute Engine, não inclua o parâmetro --credentials-file e a linha -v PATH_TO_KEY_FILE:/path/to/service-account-key.json.

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 do proxy de autenticação do Cloud SQL..

Estabeleça conexão com o cliente psql

Debian/Ubuntu

Instale o cliente psql do gerenciador de pacotes:

sudo apt-get update
sudo apt-get install postgresql-client

CentOS/RHEL

Instale o cliente psql do gerenciador de pacotes:

sudo yum install postgresql

openSUSE

Instale o cliente psql do gerenciador de pacotes:

sudo zypper install postgresql

Outras plataformas

1. Faça o download da PostgreSQL Core Distribution referente à sua plataforma na página de downloads do PostgreSQL (em inglês).
   A Core Distribution inclui o cliente psql.
2. Instale o banco de dados PostgreSQL de acordo com as orientações contidas na página de download.

A string de conexão usada depende de como você iniciou o proxy de autenticação do Cloud SQL, ou seja, usando um soquete TCP, um soquete Unix ou o Docker.

Soquetes TCP

1. Inicie o cliente psql:

   psql "host=127.0.0.1 sslmode=disable dbname=DB_NAME user=USERNAME"

   Mesmo que o parâmetro sslmode esteja definido como disable, o proxy de autenticação do Cloud SQL fornece uma conexão criptografada.

   Quando você se conecta usando soquetes TCP, o proxy de autenticação do Cloud SQL é acessado por meio de 127.0.0.1.

2. Se solicitado, digite a senha.
3. O prompt do psql é exibido.

Como usar soquetes Unix

1. Inicie o cliente psql:

   psql "sslmode=disable host=/cloudsql/INSTANCE_CONNECTION_NAME dbname=DB_NAME user=USERNAME"

   Mesmo que o parâmetro sslmode esteja definido como disable, o proxy de autenticação do Cloud SQL fornece uma conexão criptografada.

2. Digite a senha.
3. O prompt do psql é exibido.

Precisa de ajuda? Para receber ajuda na solução de problemas do proxy, consulte Solução de problemas de conexões do proxy de autenticação do Cloud SQL ou a página Suporte do Cloud SQL.

Conectar-se com um aplicativo

É possível se conectar ao proxy de autenticação do Cloud SQL por meio de qualquer linguagem que permita a conexão com 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 TCP

Instrução de invocação do proxy de autenticação do Cloud SQL:

./cloud-sql-proxy INSTANCE_CONNECTION_NAME &

Python

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

import os
import ssl

import sqlalchemy


def connect_tcp_socket() -> sqlalchemy.engine.base.Engine:
    """Initializes a TCP connection pool for a Cloud SQL instance of Postgres."""
    # Note: Saving credentials in environment variables is convenient, but not
    # secure - consider a more secure solution such as
    # Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
    # keep secrets safe.
    db_host = os.environ[
        "INSTANCE_HOST"
    ]  # e.g. '127.0.0.1' ('172.17.0.1' if deployed to GAE Flex)
    db_user = os.environ["DB_USER"]  # e.g. 'my-db-user'
    db_pass = os.environ["DB_PASS"]  # e.g. 'my-db-password'
    db_name = os.environ["DB_NAME"]  # e.g. 'my-database'
    db_port = os.environ["DB_PORT"]  # e.g. 5432

    pool = sqlalchemy.create_engine(
        # Equivalent URL:
        # postgresql+pg8000://<db_user>:<db_pass>@<db_host>:<db_port>/<db_name>
        sqlalchemy.engine.url.URL.create(
            drivername="postgresql+pg8000",
            username=db_user,
            password=db_pass,
            host=db_host,
            port=db_port,
            database=db_name,
        ),
        # ...
    )
    return pool

Java

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

Observação:

• CLOUD_SQL_CONNECTION_NAME precisa ser representado como <MEU-PROJETO>:<REGIÃO-DA-INSTÂNCIA>:<NOME-DA-INSTÂNCIA>
• O uso do argumento ipTypes=PRIVATE forçará o SocketFactory a se conectar ao IP privado associado de uma instância
• Consulte os requisitos de versão de fábrica do soquete JDBC para o arquivo pom.xml aqui.

import com.zaxxer.hikari.HikariConfig;
import com.zaxxer.hikari.HikariDataSource;
import javax.sql.DataSource;

public class TcpConnectionPoolFactory extends ConnectionPoolFactory {

  // Note: Saving credentials in environment variables is convenient, but not
  // secure - consider a more secure solution such as
  // Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
  // keep secrets safe.
  private static final String DB_USER = System.getenv("DB_USER");
  private static final String DB_PASS = System.getenv("DB_PASS");
  private static final String DB_NAME = System.getenv("DB_NAME");

  private static final String INSTANCE_HOST = System.getenv("INSTANCE_HOST");
  private static final String DB_PORT = System.getenv("DB_PORT");


  public static DataSource createConnectionPool() {
    // 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://<INSTANCE_HOST>:<DB_PORT>/<DB_NAME>?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:%s/%s", INSTANCE_HOST, DB_PORT, DB_NAME));
    config.setUsername(DB_USER); // e.g. "root", "postgres"
    config.setPassword(DB_PASS); // e.g. "my-password"


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

    // Initialize the connection pool using the configuration object.
    return new HikariDataSource(config);
  }
}

Node.js

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

const Knex = require('knex');
const fs = require('fs');

// createTcpPool initializes a TCP connection pool for a Cloud SQL
// instance of Postgres.
const createTcpPool = async config => {
  // Note: Saving credentials in environment variables is convenient, but not
  // secure - consider a more secure solution such as
  // Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
  // keep secrets safe.
  const dbConfig = {
    client: 'pg',
    connection: {
      host: process.env.INSTANCE_HOST, // e.g. '127.0.0.1'
      port: process.env.DB_PORT, // e.g. '5432'
      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'
    },
    // ... Specify additional properties here.
    ...config,
  };
  // Establish a connection to the database.
  return Knex(dbConfig);
};

Go

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

package cloudsql

import (
	"database/sql"
	"fmt"
	"log"
	"os"

	// Note: If connecting using the App Engine Flex Go runtime, use
	// "github.com/jackc/pgx/stdlib" instead, since v5 requires
	// Go modules which are not supported by App Engine Flex.
	_ "github.com/jackc/pgx/v5/stdlib"
)

// connectTCPSocket initializes a TCP connection pool for a Cloud SQL
// instance of Postgres.
func connectTCPSocket() (*sql.DB, error) {
	mustGetenv := func(k string) string {
		v := os.Getenv(k)
		if v == "" {
			log.Fatalf("Fatal Error in connect_tcp.go: %s environment variable not set.", k)
		}
		return v
	}
	// Note: Saving credentials in environment variables is convenient, but not
	// secure - consider a more secure solution such as
	// Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
	// keep secrets safe.
	var (
		dbUser    = mustGetenv("DB_USER")       // e.g. 'my-db-user'
		dbPwd     = mustGetenv("DB_PASS")       // e.g. 'my-db-password'
		dbTCPHost = mustGetenv("INSTANCE_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'
	)

	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: %w", err)
	}

	// ...

	return dbPool, nil
}

C#

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

using Npgsql;
using System;

namespace CloudSql
{
    public class PostgreSqlTcp
    {
        public static NpgsqlConnectionStringBuilder NewPostgreSqlTCPConnectionString()
        {
            // Equivalent connection string:
            // "Uid=<DB_USER>;Pwd=<DB_PASS>;Host=<INSTANCE_HOST>;Database=<DB_NAME>;"
            var connectionString = new NpgsqlConnectionStringBuilder()
            {
                // Note: Saving credentials in environment variables is convenient, but not
                // secure - consider a more secure solution such as
                // Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
                // keep secrets safe.
                Host = Environment.GetEnvironmentVariable("INSTANCE_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'

                // The Cloud SQL proxy provides encryption between the proxy and instance.
                SslMode = SslMode.Disable,
            };
            connectionString.Pooling = true;
            // Specify additional properties here.
            return connectionString;
        }
    }
}

Ruby

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

tcp: &tcp
  adapter: postgresql
  # Configure additional properties here.
  # Note: Saving credentials in environment variables is convenient, but not
  # secure - consider a more secure solution such as
  # Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
  # keep secrets safe.
  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("INSTANCE_HOST") { "127.0.0.1" }%> # '172.17.0.1' if deployed to GAE Flex
  port: <%= ENV.fetch("DB_PORT") { 5432 }%>

PHP

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

namespace Google\Cloud\Samples\CloudSQL\Postgres;

use PDO;
use PDOException;
use RuntimeException;
use TypeError;

class DatabaseTcp
{
    public static function initTcpDatabaseConnection(): PDO
    {
        try {
            // Note: Saving credentials in environment variables is convenient, but not
            // secure - consider a more secure solution such as
            // Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
            // keep secrets safe.
            $username = getenv('DB_USER'); // e.g. 'your_db_user'
            $password = getenv('DB_PASS'); // e.g. 'your_db_password'
            $dbName = getenv('DB_NAME'); // e.g. 'your_db_name'
            $instanceHost = getenv('INSTANCE_HOST'); // e.g. '127.0.0.1' ('172.17.0.1' for GAE Flex)

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

            // Connect to the database
            $conn = new PDO(
                $dsn,
                $username,
                $password,
                # ...
            );
        } catch (TypeError $e) {
            throw new RuntimeException(
                sprintf(
                    'Invalid or missing configuration! Make sure you have set ' .
                        '$username, $password, $dbName, and $instanceHost (for TCP mode). ' .
                        'The PHP error was %s',
                    $e->getMessage()
                ),
                $e->getCode(),
                $e
            );
        } catch (PDOException $e) {
            throw new RuntimeException(
                sprintf(
                    'Could not connect to the Cloud SQL Database. Check that ' .
                        'your username and password are correct, that the Cloud SQL ' .
                        'proxy is running, and that the database exists and is ready ' .
                        'for use. For more assistance, refer to %s. The PDO error was %s',
                    'https://cloud.google.com/sql/docs/postgres/connect-external-app',
                    $e->getMessage()
                ),
                $e->getCode(),
                $e
            );
        }

        return $conn;
    }
}

Como se conectar com soquetes Unix

Instrução de invocação do proxy de autenticação do Cloud SQL:

./cloud-sql-proxy --unix-socket /cloudsql INSTANCE_CONNECTION_NAME &

Python

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

import os

import sqlalchemy


def connect_unix_socket() -> sqlalchemy.engine.base.Engine:
    """Initializes a Unix socket connection pool for a Cloud SQL instance of Postgres."""
    # Note: Saving credentials in environment variables is convenient, but not
    # secure - consider a more secure solution such as
    # Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
    # keep secrets safe.
    db_user = os.environ["DB_USER"]  # e.g. 'my-database-user'
    db_pass = os.environ["DB_PASS"]  # e.g. 'my-database-password'
    db_name = os.environ["DB_NAME"]  # e.g. 'my-database'
    unix_socket_path = os.environ[
        "INSTANCE_UNIX_SOCKET"
    ]  # e.g. '/cloudsql/project:region:instance'

    pool = sqlalchemy.create_engine(
        # Equivalent URL:
        # postgresql+pg8000://<db_user>:<db_pass>@/<db_name>
        #                         ?unix_sock=<INSTANCE_UNIX_SOCKET>/.s.PGSQL.5432
        # Note: Some drivers require the `unix_sock` query parameter to use a different key.
        # For example, 'psycopg2' uses the path set to `host` in order to connect successfully.
        sqlalchemy.engine.url.URL.create(
            drivername="postgresql+pg8000",
            username=db_user,
            password=db_pass,
            database=db_name,
            query={"unix_sock": f"{unix_socket_path}/.s.PGSQL.5432"},
        ),
        # ...
    )
    return pool

Java

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

import com.zaxxer.hikari.HikariConfig;
import com.zaxxer.hikari.HikariDataSource;
import javax.sql.DataSource;

public class ConnectorConnectionPoolFactory extends ConnectionPoolFactory {

  // Note: Saving credentials in environment variables is convenient, but not
  // secure - consider a more secure solution such as
  // Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
  // keep secrets safe.
  private static final String INSTANCE_CONNECTION_NAME =
      System.getenv("INSTANCE_CONNECTION_NAME");
  private static final String INSTANCE_UNIX_SOCKET = System.getenv("INSTANCE_UNIX_SOCKET");
  private static final String DB_USER = System.getenv("DB_USER");
  private static final String DB_PASS = System.getenv("DB_PASS");
  private static final String DB_NAME = System.getenv("DB_NAME");

  public static DataSource createConnectionPool() {
    // 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=<INSTANCE_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", INSTANCE_CONNECTION_NAME);

    // Unix sockets are not natively supported in Java, so it is necessary to use the Cloud SQL
    // Java Connector to connect. When setting INSTANCE_UNIX_SOCKET, the connector will 
    // call an external package that will enable Unix socket connections.
    // Note: For Java users, the Cloud SQL Java Connector can provide authenticated connections
    // which is usually preferable to using the Cloud SQL Proxy with Unix sockets.
    // See https://github.com/GoogleCloudPlatform/cloud-sql-jdbc-socket-factory for details.
    if (INSTANCE_UNIX_SOCKET != null) {
      config.addDataSourceProperty("unixSocketPath", INSTANCE_UNIX_SOCKET);
    }



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

    // Initialize the connection pool using the configuration object.
    return new HikariDataSource(config);
  }
}

Node.js

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

const Knex = require('knex');

// createUnixSocketPool initializes a Unix socket connection pool for
// a Cloud SQL instance of Postgres.
const createUnixSocketPool = async config => {
  // Note: Saving credentials in environment variables is convenient, but not
  // secure - consider a more secure solution such as
  // Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
  // keep secrets safe.
  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: process.env.INSTANCE_UNIX_SOCKET, // e.g. '/cloudsql/project:region:instance'
    },
    // ... Specify additional properties here.
    ...config,
  });
};

C#

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

using Npgsql;
using System;

namespace CloudSql
{
    public class PostgreSqlUnix
    {
        public static NpgsqlConnectionStringBuilder NewPostgreSqlUnixSocketConnectionString()
        {
            // Equivalent connection string:
            // "Server=<INSTANCE_UNIX_SOCKET>;Uid=<DB_USER>;Pwd=<DB_PASS>;Database=<DB_NAME>"
            var connectionString = new NpgsqlConnectionStringBuilder()
            {
                // The Cloud SQL proxy provides encryption between the proxy and instance.
                SslMode = SslMode.Disable,

                // Note: Saving credentials in environment variables is convenient, but not
                // secure - consider a more secure solution such as
                // Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
                // keep secrets safe.
                Host = Environment.GetEnvironmentVariable("INSTANCE_UNIX_SOCKET"), // e.g. '/cloudsql/project:region:instance'
                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 conferir esse snippet no contexto de um aplicativo da Web, consulte o README no GitHub.

package cloudsql

import (
	"database/sql"
	"fmt"
	"log"
	"os"

	// Note: If connecting using the App Engine Flex Go runtime, use
	// "github.com/jackc/pgx/stdlib" instead, since v5 requires
	// Go modules which are not supported by App Engine Flex.
	_ "github.com/jackc/pgx/v5/stdlib"
)

// connectUnixSocket initializes a Unix socket connection pool for
// a Cloud SQL instance of Postgres.
func connectUnixSocket() (*sql.DB, error) {
	mustGetenv := func(k string) string {
		v := os.Getenv(k)
		if v == "" {
			log.Fatalf("Fatal Error in connect_unix.go: %s environment variable not set.\n", k)
		}
		return v
	}
	// Note: Saving credentials in environment variables is convenient, but not
	// secure - consider a more secure solution such as
	// Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
	// keep secrets safe.
	var (
		dbUser         = mustGetenv("DB_USER")              // e.g. 'my-db-user'
		dbPwd          = mustGetenv("DB_PASS")              // e.g. 'my-db-password'
		unixSocketPath = mustGetenv("INSTANCE_UNIX_SOCKET") // e.g. '/cloudsql/project:region:instance'
		dbName         = mustGetenv("DB_NAME")              // e.g. 'my-database'
	)

	dbURI := fmt.Sprintf("user=%s password=%s database=%s host=%s",
		dbUser, dbPwd, dbName, unixSocketPath)

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

	// ...

	return dbPool, nil
}

Ruby

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

unix: &unix
  adapter: postgresql
  # Configure additional properties here.
  # Note: Saving credentials in environment variables is convenient, but not
  # secure - consider a more secure solution such as
  # Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
  # keep secrets safe.
  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" } %>
  # Specify the Unix socket path as host
  host: "<%= ENV["INSTANCE_UNIX_SOCKET"] %>"

PHP

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

namespace Google\Cloud\Samples\CloudSQL\Postgres;

use PDO;
use PDOException;
use RuntimeException;
use TypeError;

class DatabaseUnix
{
    public static function initUnixDatabaseConnection(): PDO
    {
        try {
            // Note: Saving credentials in environment variables is convenient, but not
            // secure - consider a more secure solution such as
            // Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
            // keep secrets safe.
            $username = getenv('DB_USER'); // e.g. 'your_db_user'
            $password = getenv('DB_PASS'); // e.g. 'your_db_password'
            $dbName = getenv('DB_NAME'); // e.g. 'your_db_name'
            $instanceUnixSocket = getenv('INSTANCE_UNIX_SOCKET'); // e.g. '/cloudsql/project:region:instance'

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

            // Connect to the database.
            $conn = new PDO(
                $dsn,
                $username,
                $password,
                # ...
            );
        } catch (TypeError $e) {
            throw new RuntimeException(
                sprintf(
                    'Invalid or missing configuration! Make sure you have set ' .
                        '$username, $password, $dbName, ' .
                        'and $instanceUnixSocket (for UNIX socket mode). ' .
                        'The PHP error was %s',
                    $e->getMessage()
                ),
                (int) $e->getCode(),
                $e
            );
        } catch (PDOException $e) {
            throw new RuntimeException(
                sprintf(
                    'Could not connect to the Cloud SQL Database. Check that ' .
                        'your username and password are correct, that the Cloud SQL ' .
                        'proxy is running, and that the database exists and is ready ' .
                        'for use. For more assistance, refer to %s. The PDO error was %s',
                    'https://cloud.google.com/sql/docs/postgres/connect-external-app',
                    $e->getMessage()
                ),
                (int) $e->getCode(),
                $e
            );
        }

        return $conn;
    }
}

Temas adicionais

Argumentos da linha de comando do proxy de autenticação do Cloud SQL

Os exemplos acima abrangem os casos de uso mais comuns, mas o proxy de autenticação do Cloud SQL 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 proxy de autenticação do Cloud SQL no GitHub para conferir outros exemplos de como usar as opções de linha de comando desse proxy.

Opções de autenticação do proxy de autenticação do Cloud SQL

Quando você autentica o proxy de autenticação do Cloud SQL, você permite que ele acesse o Google Cloud em nome do aplicativo usando um conjunto de credenciais do Google. Isso é diferente da autenticação do usuário do banco de dados. A autenticação do banco de dados do usuário do IAM é integrada ao proxy de autenticação do Cloud SQL.

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 página Visão geral da instância no console do Google Cloud ou executando este comando:

gcloud sql instances describe --project PROJECT_ID INSTANCE_CONNECTION_NAME.

Por exemplo: gcloud sql instances describe --project myproject 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 proxy de autenticação do Cloud SQL fornece várias alternativas para autenticação, de acordo com o ambiente. O proxy de autenticação do Cloud SQL verifica cada um dos itens a seguir, na seguinte ordem, usando o primeiro item encontrado para tentar realizar a autenticação:

1. Credenciais fornecidas pela flag credentials-file.

   Use uma conta de serviço para criar e fazer o download do arquivo JSON associado e defina a flag --credentials-file para o caminho do arquivo ao iniciar o proxy de autenticação do Cloud SQL. 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 flag --credentials-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 --credentials-file PATH_TO_KEY_FILE \
   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.

   Saiba mais sobre os papéis compatíveis com o Cloud SQL em Papéis do IAM para o Cloud SQL.

2. Credenciais fornecidas por um token de acesso.

   Crie um token de acesso e invoque o comentário cloud-sql-proxy com a flag --token definida como um token de acesso do OAuth 2.0. Exemplo:

   ./cloud-sql-proxy --token ACCESS_TOKEN \
   INSTANCE_CONNECTION_NAME
     

3. Credenciais fornecidas por uma variável de ambiente.

   Essa opção é semelhante a usar a flag --credentials-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 --credentials-file.

4. Credenciais de um cliente CLI gcloud autenticado.

   Se você tiver instalado a CLI gcloud e realizado a autenticação com sua conta pessoal, o proxy de autenticação do Cloud SQL poderá usar as mesmas credenciais de conta. Esse método é especialmente útil para colocar um ambiente para desenvolvedores em funcionamento.

   Para permitir que o proxy de autenticação do Cloud SQL use as credenciais da CLI gcloud, use o comando a seguir para autenticá-la:

   gcloud auth application-default login

5. 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 de autenticação do Cloud SQL 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 de autenticação do Cloud SQL 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 instância do Compute Engine terá as permissões necessárias para autenticar o proxy de autenticação do Cloud SQL. 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.

6. Conta de serviço padrão do ambiente

   Se o proxy de autenticação do Cloud SQL 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

1. No Console do Google Cloud, acesse a página Contas de serviço.

   Acessar 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. Preencha o campo Nome da conta de serviço.
5. Altere o ID da conta de serviço para um valor exclusivo e facilmente reconhecível, depois clique em Criar e continuar.
6. Clique no campo Selecionar papel e escolha um dos seguintes papéis:
   • Cloud SQL > Cliente do Cloud SQL
   • Cloud SQL > Editor do Cloud SQL
   • Cloud SQL > Administrador do Cloud SQL
   Observação: para criar uma conta de serviço com as permissões necessárias, você precisa ter a permissão resourcemanager.projects.setIamPolicy. Essa permissão está incluída nos papéis de proprietário do projeto, administrador do IAM do projeto e administrador da organização.
   Você também precisa ativar a API Cloud SQL Admin. 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.
7. Clique em Concluído para terminar a criação da conta de serviço.
8. Clique no menu de ações da sua nova conta de serviço e selecione Gerenciar chaves.
9. Clique no menu suspenso Adicionar chave e clique em Criar nova chave.
10. Confirme se o tipo de chave é JSON e clique em Criar.

    O arquivo da chave privada é transferido para sua máquina. Você pode movê-lo para outro local. Mantenha-o seguro.

Usar o proxy de autenticação do Cloud SQL com um IP privado

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

O proxy de autenticação do Cloud SQL usa um IP para estabelecer uma conexão com a instância do Cloud SQL. Por padrão, ele tenta se conectar usando um endereço IPv4 público.

Se a instância do Cloud SQL tiver apenas um IP privado ou tiver um IP público e um privado configurados e você quiser que o proxy do Cloud SQL Auth usar o endereço IP privado, forneça a seguinte opção ao iniciar o proxy do Cloud SQL Auth:

--private-ip

Usar o proxy de autenticação do Cloud SQL com instâncias que tenham o Private Service Connect ativado

Use o proxy do Cloud SQL Auth para se conectar a uma instância do Cloud SQL com o Private Service Connect ativado.

O proxy de autenticação do Cloud SQL é um conector que fornece acesso seguro a essa instância sem a necessidade de redes autorizadas ou configuração de SSL.

Para permitir conexões de cliente do proxy de autenticação do Cloud SQL, você precisa configurar um registro DNS que corresponda ao nome DNS recomendado que foi fornecido para a instância. O registro DNS é um mapeamento entre um recurso de DNS e um nome de domínio.

Para mais informações sobre como usar o proxy do Cloud SQL Auth para se conectar a instâncias com o Private Service Connect ativado, consulte Conectar usando o proxy de autenticação do Cloud SQL.

Executar o proxy de autenticação do Cloud SQL em um processo separado

Executar o proxy de autenticação do Cloud SQL em um processo de terminal separado do Cloud Shell 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 de autenticação do Cloud SQL em um processo separado.

Linux

No Linux ou no macOS, use um & à direita na linha de comando para iniciar o proxy de autenticação do Cloud SQL em um processo separado:

./cloud-sql-proxy INSTANCE_CONNECTION_NAME
  --credentials-file PATH_TO_KEY_FILE &

Windows

No Windows PowerShell, use o comando Start-Process para iniciar o proxy de autenticação do Cloud SQL em um processo separado:

Start-Process --filepath "cloud-sql-proxy.exe"
  --ArgumentList "
  --credentials-file PATH_TO_KEY_FILEINSTANCE_CONNECTION_NAME"

Executar o proxy de autenticação do Cloud SQL em um contêiner do Docker

Para executar o proxy de autenticação do Cloud SQL em um contêiner do Docker, use a respectiva imagem Docker disponível no Google Container Registry. É possível instalar a imagem Docker do proxy de autenticação do Cloud SQL com este comando gcloud:

docker pull gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.13.0

Inicie o proxy de autenticação do Cloud SQL usando soquetes TCP ou Unix, com os comandos mostrados abaixo.

Observação: os soquetes Unix não são compatíveis com aplicativos desenvolvidos na linguagem de programação Java ou com o ambiente Windows.

Soquetes TCP

    docker run -d \
      -v PATH_TO_KEY_FILE:/path/to/service-account-key.json \
      -p 127.0.0.1:5432:5432 \
      gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.13.0 \
      --address 0.0.0.0 \
      --credentials-file /path/to/service-account-key.json \
      INSTANCE_CONNECTION_NAME

Soquetes Unix

    docker run -d \
      -v /PATH_TO_HOST_TARGET:/PATH_TO_GUEST_TARGET \
      -v PATH_TO_KEY_FILE:/path/to/service-account-key.json \
      gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.13.0 --unix-socket /cloudsql \
      --credentials-file /path/to/service-account-key.json/PATH_TO_KEY_FILE \
      INSTANCE_CONNECTION_NAME

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:/path/to/service-account-key.json.

Como executar o proxy de autenticação do Cloud SQL como um serviço

Executar o proxy de autenticação do Cloud SQL como um serviço em segundo plano é uma opção para cargas de trabalho de desenvolvimento e produção locais. Em desenvolvimento, quando você precisar acessar sua instância do Cloud SQL, inicie o serviço em segundo plano e interrompa-o quando terminar.

No momento, no caso das cargas de trabalho de produção, o proxy de autenticação do Cloud SQL não é compatível com a execução como um serviço do Windows, mas gerenciadores de serviço de terceiros podem ser usados para executá-lo como um serviço. Por exemplo, use o NSSM para configurar o proxy de autenticação do Cloud SQL como um serviço do Windows. O NSSM monitora o proxy de autenticação do Cloud SQL e o reinicia automaticamente quando ele deixa de responder. Consulte a documentação do NSSM para mais informações.

Observação: se você executar o proxy de autenticação do Cloud SQL como um serviço, lembre-se de que ele usa uma conexão segura para se comunicar com as instâncias do Cloud SQL. No entanto, as conexões do aplicativo com o proxy de autenticação do Cloud SQL não são criptografadas. Por esse motivo, garanta que apenas usuários confiáveis possam acessar o endereço e a porta por onde o proxy de autenticação do Cloud SQL faz as detecções.

Exigir o uso do proxy de autenticação do Cloud SQL

Ative o uso do proxy de autenticação do Cloud SQL no Cloud SQL usando ConnectorEnforcement.

gcloud

O comando a seguir impõe o uso dos conectores do Cloud SQL.

    gcloud sql instances patch INSTANCE_NAME \
    --connector-enforcement REQUIRED
  

Para desativar a aplicação, use a seguinte linha de código: --connector-enforcement NOT_REQUIRED A atualização não aciona uma reinicialização.

REST v1

O comando a seguir aplica o uso dos conectores do Cloud SQL

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

• project-id: o ID do projeto.
• instance-id: o ID da instância

Método HTTP e URL:

PATCH https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id

Corpo JSON da solicitação:

{
  "settings": {                     
    "connectorEnforcement": "REQUIRED"    
  }                                             
}   

Para enviar a solicitação, expanda uma destas opções:

curl (Linux, macOS ou Cloud Shell)

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud. . É possível verificar a conta ativa atual executando gcloud auth list.

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id"

PowerShell (Windows)

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login . É possível verificar a conta ativa atual executando gcloud auth list.

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id" | Select-Object -Expand Content

Você receberá uma resposta JSON semelhante a esta:

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id",
  "status": "PENDING",
  "user": "[e-mail]",
  "insertTime": "2020-01-16T02:32:12.281Z",
  "operationType": "UPDATE",
  "name": "operation-id",
  "targetId": "instance-id",
  "selfLink": "https://sqladmin.googleapis.com/v1/projects/project-id/operations/operation-id",
  "targetProject": "project-id"
}

Para desativar a aplicação, use "connectorEnforcement": "NOT_REQUIRED". A atualização não aciona uma reinicialização.

REST v1beta4

O comando a seguir impõe o uso dos conectores do Cloud SQL.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

• project-id: o ID do projeto.
• instance-id: o ID da instância

Método HTTP e URL:

PATCH https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id

Corpo JSON da solicitação:

{
  "settings": {
    "connectorEnforcement": "REQUIRED"
  }
}

Para enviar a solicitação, expanda uma destas opções:

curl (Linux, macOS ou Cloud Shell)

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud. . É possível verificar a conta ativa atual executando gcloud auth list.

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id"

PowerShell (Windows)

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login . É possível verificar a conta ativa atual executando gcloud auth list.

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id" | Select-Object -Expand Content

Você receberá uma resposta JSON semelhante a esta:

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id",
  "status": "PENDING",
  "user": "[e-mail]",
  "insertTime": "2020-01-16T02:32:12.281Z",
  "operationType": "UPDATE",
  "name": "operation-id",
  "targetId": "instance-id",
  "selfLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/operations/operation-id",
  "targetProject": "project-id"
}

Para desativar a aplicação, use "connectorEnforcement": "NOT_REQUIRED". A atualização não aciona uma reinicialização.

Dicas para trabalhar com o proxy de autenticação do Cloud SQL

Invocar o proxy de autenticação do Cloud SQL

Todas as invocações de proxy de exemplo iniciam o proxy de autenticação do Cloud SQL em segundo plano. Devido a isso, um prompt é retornado. Reserve o terminal do Cloud Shell para o proxy de autenticação do Cloud SQL a fim de evitar que a saída seja confundida com a de outros programas. Além disso, a saída do proxy de autenticação do Cloud SQL pode ajudar você a diagnosticar problemas de conexão. Portanto, pode ser útil capturá-la em um arquivo de registro. Se você não iniciar o proxy de autenticação do Cloud SQL em segundo plano, a saída irá para stdout, a menos que seja redirecionada.

Não é necessário usar /cloudsql como o diretório dos soquetes do proxy de autenticação do Cloud SQL. 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"

Usar o proxy de autenticação do Cloud SQL para a conexão com várias instâncias

Use um cliente local do proxy de autenticação do Cloud SQL para se conectar a várias instâncias do Cloud SQL. A maneira de fazer isso dependerá do uso de soquetes Unix ou TCP.

Soquetes Unix

Para conectar o proxy do Cloud SQL Auth a várias instâncias, informe a ele o nome de conexão de cada instância como um argumento, em uma lista separada por vírgulas. O proxy de autenticação do Cloud SQL 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 --unix-socket /cloudsql \
      myProject:us-central1:myInstance myProject:us-central1:myInstance2 &
      psql -U myUser -h /cloudsql/myProject:us-central1:myInstance2
  

Soquetes TCP

Ao se conectar usando TCP, você especificará uma porta na máquina para que o proxy de autenticação do Cloud SQL faça a detecção para cada instância do Cloud SQL. Ao se conectar a várias instâncias do Cloud SQL, cada porta especificada precisa ser exclusiva e estar disponível para uso em sua máquina.

Exemplo:

    # Start the Cloud SQL Auth Proxy to connect to two different Cloud SQL instances
    # Give the Cloud SQL Auth Proxy a unique port on your machine to use for each Cloud SQL instance.

    ./cloud-sql-proxy "myProject:us-central1:myInstance?port=5432" \
    "myProject:us-central1:myInstance2?port=1234"

    # Connect to "myInstance" using port 5432 on your machine:
    psql -U myUser -h 127.0.0.1  --port 5432

    # Connect to "myInstance2" using port 1234 on your machine:
    psql -U myUser -h 127.0.0.1  --port 1234
  

Resolver problemas de conexões do proxy de autenticação do Cloud SQL

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

Se você tiver problemas para se conectar à instância do Cloud SQL usando o proxy de autenticação do Cloud SQL, tente aplicar as opções a seguir para encontrar o motivo.

• Verifique a saída do proxy de autenticação do Cloud SQL.

  Muitas vezes, a saída do proxy pode ajudar você a determinar a origem do problema e saber como resolvê-lo. Redirecione a saída para um arquivo ou observe o terminal do Cloud Shell em que você iniciou o proxy de autenticação do Cloud SQL.

• Se você estiver recebendo um erro 403 notAuthorized e estiver usando uma conta de serviço para autenticar o proxy de autenticação de Cloud SQL, 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. Os papéis predefinidos Cloud SQL Admin, Client e Editor têm essa permissão.

• Se você estiver se conectando a partir do App Engine e estiver recebendo um erro 403 notAuthorized, verifique a cloud_sql_instances valor app.yaml quanto a um nome de conexão de instância incorreto ou incorreto. Os nomes das conexões de instâncias estão sempre no formato PROJECT:REGION:INSTANCE.

  Além disso, verifique se a conta de serviço do App Engine (por exemplo, $[e-mail]) tem o papel de Cliente do Cloud SQL do IAM.

  Se o serviço do App Engine residir em um projeto (projeto A) e o banco de dados em outro (projeto B), esse erro significa que a conta de serviço do App Engine não recebeu o papel de Cliente do Cloud SQL do IAM no projeto com o banco de dados (projeto B).

• Certifique-se de ativar a API Cloud SQL Admin.

  Caso contrário, você verá uma saída como Error 403: Access Not Configured nos registros do proxy de autenticação do Cloud SQL.

• 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 com soquetes UNIX, confirme se eles foram criados listando o diretório fornecido quando você iniciou o proxy de autenticação do Cloud SQL.

• 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: o proxy de autenticação do Cloud SQL usa a porta 3307 para se conectar ao servidor do proxy de autenticação do Cloud SQL. A porta 5432 é a porta padrão do protocolo PostgreSQL em uma conexão TCP direta (que não usa o proxy de autenticação do Cloud SQL).

• É possível confirmar se o proxy de autenticação do Cloud SQL foi iniciado corretamente procurando nos registros na seção Operações > Logging > Análise de registros do console do Google Cloud. Uma operação bem-sucedida é semelhante a esta:

  2021/06/14 15:47:56 Listening on /cloudsql/$PROJECT_ID:$REGION:$INSTANCE_NAME/5432 for $PROJECT_ID:$REGION:$INSTANCE_NAME
  2021/06/14 15:47:56 Ready for new connections
  

• Problemas de cota: quando a cota da API Cloud SQL Admin é violada, o proxy de autenticação do Cloud SQL é iniciado com a seguinte mensagem de erro:

  There was a problem when parsing a instance configuration but ignoring due
  to the configuration. Error: googleapi: Error 429: Quota exceeded for quota
  metric 'Queries' and limit 'Queries per minute per user' of service
  'sqladmin.googleapis.com' for consumer 'project_number:$PROJECT_ID.,
  rateLimitExceeded
  

  Depois que um aplicativo se conecta ao proxy, o proxy informa o seguinte erro:

  failed to refresh the ephemeral certificate for $INSTANCE_CONNECTION_NAME:
  googleapi: Error 429: Quota exceeded for quota metric 'Queries' and limit
  'Queries per minute per user' of service 'sqladmin.googleapis.com' for
  consumer 'project_number:$PROJECT_ID., rateLimitExceeded
  

  Solução: identifique a origem do problema de cota, por exemplo, um aplicativo está usando o conector de maneira incorreta e criando novas conexões desnecessariamente, ou entre em contato com o suporte para solicitar um aumento na cota da API Cloud SQL Admin. Se o erro de cota aparecer na inicialização, você precisará reimplantar o aplicativo para reiniciar o proxy. Se o erro de cota aparecer após a inicialização, a reimplantação será desnecessária.

A seguir

• Saiba mais sobre o proxy de autenticação do Cloud SQL.
• 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.