Como se conectar pelo proxy do Cloud SQL Auth

Nesta página, você verá como estabelecer uma conexão com a instância do Cloud SQL usando o proxy do Cloud SQL Auth.

Para informações sobre como conectar um cliente sqlcmd a uma instância do Cloud SQL usando um IP público, consulte Como se conectar usando um cliente de banco de dados.

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

Antes de começar

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

  1. Verifique se você tem o papel "Cliente do Cloud SQL" na conta de usuário.

    Acessar a página IAM

  2. Ative a API Cloud SQL Admin.

    Ative a API

  3. Instale e inicialize o Cloud SDK.
  4. Opcional. Instale o cliente Docker do proxy do Cloud SQL Auth.

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

Linux de 64 bits

  1. Faça o download do proxy do Cloud SQL Auth:
    wget https://dl.google.com/cloudsql/cloud_sql_proxy.linux.amd64 -O cloud_sql_proxy
    
  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 do Cloud SQL Auth:
    wget https://dl.google.com/cloudsql/cloud_sql_proxy.linux.386 -O cloud_sql_proxy
    
  2. Se o comando wget não for encontrado, execute sudo apt-get install wget abd 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 do Cloud SQL Auth:
    curl -o cloud_sql_proxy https://dl.google.com/cloudsql/cloud_sql_proxy.darwin.amd64
    
  2. Torne o proxy do Cloud SQL Auth executável:
    chmod +x cloud_sql_proxy
    

macOS de 32 bits

  1. Faça o download do proxy do Cloud SQL Auth:
    curl -o cloud_sql_proxy https://dl.google.com/cloudsql/cloud_sql_proxy.darwin.386
    
  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://dl.google.com/cloudsql/cloud_sql_proxy_x64.exe e selecione Salvar link como para fazer o download do proxy do Cloud SQL Auth. Renomeie o arquivo para cloud_sql_proxy.exe.

Windows de 32 bits

Clique com o botão direito do mouse em https://dl.google.com/cloudsql/cloud_sql_proxy_x86.exe e selecione Salvar link como para fazer o download do proxy do Cloud SQL Auth. Renomeie o arquivo para cloud_sql_proxy.exe.

Imagem do Docker do proxy do Cloud SQL Auth

Por conveniência, várias imagens de contêiner que contêm o proxy do Cloud SQL Auth estão disponíveis no GitHub no repositório do proxy do Cloud SQL Auth. É 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 do Cloud SQL Auth na origem.

Iniciar o proxy do Cloud SQL Auth

Inicie o proxy do Cloud SQL Auth usando soquetes TCP ou a imagem do Docker desse serviço. O binário do proxy do Cloud SQL Auth se conecta a uma ou mais instâncias do Cloud SQL especificadas na linha de comando e abre uma conexão local como um soquete TCP. Outros aplicativos e serviços, como o código do aplicativo ou as ferramentas de cliente do gerenciamento de banco de dados, podem se conectar a instâncias do Cloud SQL usando a conexão de soquete TCP.

Sockets TCP

Para conexões TCP, o proxy do Cloud SQL Auth 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 do Cloud SQL Auth detectar em 0.0.0.0:1234 para a conexão local:

  ./cloud_sql_proxy -instances=INSTANCE_CONNECTION_NAME=tcp:0.0.0.0:1234
  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
    .

    Por exemplo, myproject:myregion:myinstance.

  2. Se a instância tiver IP público e particular configurados e você quiser que o proxy do Cloud SQL Auth use o endereço IP particular, forneça a opção a seguir ao iniciar o proxy do Cloud SQL Auth:
    -ip_address_types=PRIVATE
  3. Se você estiver usando uma conta de serviço para autenticar o proxy do Cloud SQL Auth, 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. Iniciar o proxy do Cloud SQL Auth.

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

    • Usando autenticação do SDK do Cloud:
      ./cloud_sql_proxy -instances=INSTANCE_CONNECTION_NAME=tcp:1433
      
      A porta especificada não pode estar em uso, por exemplo, por um servidor de banco de dados local.
    • Usar uma conta de serviço e incluir explicitamente o nome da conexão da instância (recomendado para ambientes de produção):
      ./cloud_sql_proxy -instances=INSTANCE_CONNECTION_NAM=tcp:1433 \
                        -credential_file=PATH_TO_KEY_FILE &
      

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

Imagem do Docker do proxy do Cloud SQL Auth

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

Inicie o proxy do Cloud SQL Auth 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 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 do Cloud SQL Auth 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:1433:1433 \\
  gcr.io/cloudsql-docker/gce-proxy:1.19.1 /cloud_sql_proxy \\
  -instances=INSTANCE_CONNECTION_NAME=tcp:0.0.0.0:1433 -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 do Cloud SQL Auth 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 o parâmetro do proxy do Cloud SQL Auth..

Conectar-se com o cliente sqlcmd

Debian/Ubuntu

Para Debian/Ubuntu, instale as ferramentas de linha de comando aplicáveis do SQL Server seguindo estas instruções.

CentOS/RHEL

Para o CentOS/RHEL, instale as ferramentas de linha de comando aplicáveis do SQL Server seguindo estas instruções.

openSUSE

Para o openSUSE, instale as ferramentas de linha de comando aplicáveis do SQL Server seguindo estas instruções.

Outras plataformas

Consulte a página de destino e a página de downloads do SQL Server para instalar o SQL Server.

A string de conexão que você usa depende se a inicialização do proxy do Cloud SQL Auth foi feita usando um soquete TCP ou o Docker.

Sockets TCP

  1. Inicie o cliente sqlcmd:
    sqlcmd -S tcp:127.0.0.1,1433 -U USERNAME -P PASSWORD
    

    Quando você se conecta usando soquetes TCP, o proxy do Cloud SQL Auth é acessado por 127.0.0.1.

  2. Se solicitado, digite a senha.
  3. Será exibido o prompt sqlcmd.

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

Conectar-se com um aplicativo

É possível se conectar ao proxy do Cloud SQL Auth por qualquer linguagem que permita se conectar a um soquete 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 do Cloud SQL Auth:

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

Python

Para ver esse snippet no contexto de um aplicativo da Web, consulte o README 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 environment variable DB_HOST
host_args = db_host.split(":")
db_hostname, db_port = host_args[0], int(host_args[1])

# SQL Server drivers don't account for this
if db_hostname == "localhost":
    db_hostname = "127.0.0.1"

# The SQLAlchemy engine will help manage interactions, including automatically
# managing a pool of connections to your database
pool = sqlalchemy.create_engine(
    # Equivalent URL:
    # mssql+pytds://<db_user>:<db_pass>@/<host>:<port>/<db_name>?driver=ODBC+Driver+17+for+SQL+Server
    sqlalchemy.engine.url.URL.create(
        "mssql+pytds",
        username=db_user,
        password=db_pass,
        database=db_name,
        host=db_hostname,
        port=db_port,
    ),
    **db_config
)

Java

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

Observação:

  • CLOUD_SQL_CONNECTION_NAME precisa ser representado como <MY-PROJECT>:<INSTANCE-REGION>:<INSTANCE-NAME>
  • 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.

// 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 is equivalent to setting the config options below:
// jdbc:sqlserver://;user=<DB_USER>;password=<DB_PASS>;databaseName=<DB_NAME>;
// socketFactoryClass=com.google.cloud.sql.sqlserver.SocketFactory;
// socketFactoryConstructorArg=<CLOUD_SQL_CONNECTION_NAME>

// 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
    .setDataSourceClassName("com.microsoft.sqlserver.jdbc.SQLServerDataSource");
config.setUsername(DB_USER); // e.g. "root", "sqlserver"
config.setPassword(DB_PASS); // e.g. "my-password"
config.addDataSourceProperty("databaseName", DB_NAME);

config.addDataSourceProperty("socketFactoryClass",
    "com.google.cloud.sql.sqlserver.SocketFactory");
config.addDataSourceProperty("socketFactoryConstructorArg", CLOUD_SQL_CONNECTION_NAME);

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

const createPool = async () => {
  const config = {pool: {}, options: {}};
  config.user = process.env.DB_USER; // e.g. 'my-db-user'
  config.password = process.env.DB_PASS; // e.g. 'my-db-password'
  config.database = process.env.DB_NAME; // e.g. 'my-database'
  // set the server to '172.17.0.1' when connecting from App Engine Flex
  config.server = process.env.DEPLOYED ? '172.17.0.1' : '127.0.0.1';
  config.port = 1433;

  // ...
  config.options.trustServerCertificate = true;
  return await mssql.connect(config);
};

Go

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

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

var dbURI string
dbURI = fmt.Sprintf("server=%s;user id=%s;password=%s;port=%s;database=%s;", dbTCPHost, dbUser, dbPwd, dbPort, dbName)

// dbPool is the pool of database connections.
dbPool, err := sql.Open("mssql", 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).

            // Equivalent connection string:
            // "User Id=<DB_USER>;Password=<DB_PASS>;Server=<DB_HOST>;Database=<DB_NAME>;"
            var connectionString = new SqlConnectionStringBuilder()
            {
                // 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.
                DataSource = Environment.GetEnvironmentVariable("DB_HOST"),     // e.g. '127.0.0.1'
                // Set Host to 'cloudsql' when deploying to App Engine Flexible environment
                UserID = Environment.GetEnvironmentVariable("DB_USER"),         // e.g. 'my-db-user'
                Password = Environment.GetEnvironmentVariable("DB_PASS"),       // e.g. 'my-db-password'
                InitialCatalog = Environment.GetEnvironmentVariable("DB_NAME"), // e.g. 'my-database'

                // The Cloud SQL proxy provides encryption between the proxy and instance
                Encrypt = false,
            };
            connectionString.Pooling = true;
            // ...
            return connectionString;

Ruby

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

development:
  adapter: sqlserver
  # 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") { 1433 }%> 

PHP

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

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

// Connect using TCP
$dsn = sprintf('sqlsrv:server=%s;Database=%s', $dbHost, $dbName);

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

Temas adicionais

Argumentos da linha de comando do proxy do Cloud SQL Auth

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

Opções para autenticar o proxy do Cloud SQL Auth

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 --project PROJECT_ID

Por exemplo, gcloud sql instances describe myinstance --project myproject.

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 do Cloud SQL Auth fornece várias alternativas para autenticação, dependendo do seu ambiente. O proxy do Cloud SQL Auth verifica cada um dos itens a seguir, na ordem a seguir, usando o primeiro item encontrado para tentar autenticar:

  1. 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 proxy do Cloud SQL Auth. 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.

  2. 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
      
  3. 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_file.
  4. 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 proxy do Cloud SQL Auth poderá usar as mesmas credenciais da conta. Esse método é especialmente útil para colocar um ambiente para desenvolvedores em funcionamento.

    Se nenhuma conta foi selecionada para gcloud auth login, o proxy do Cloud SQL Auth verificará se há uma conta selecionada para 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 do Cloud SQL Auth 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 do Cloud SQL Auth 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 do Cloud SQL Auth. 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 do Cloud SQL Auth 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.

Como criar uma conta de serviço

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

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

  2. Selecione o projeto que contém a instância do Cloud SQL.
  3. Clique em Criar conta de serviço.
  4. Na caixa de diálogo Criar conta de serviço, forneça um nome descritivo para a conta.
  5. Altere o ID da conta de serviço para um valor exclusivo e reconhecível e, em seguida, clique em Criar.
  6. Em Papel, selecione um dos seguintes papéis, clique em Continuar e em Concluído:
    • Cloud SQL > Cliente do Cloud SQL
    • Cloud SQL > Editor do Cloud SQL
    • Cloud SQL > Administrador do Cloud SQL
  7. Clique no menu de ações da sua nova conta de serviço e selecione Gerenciar chaves.
  8. Clique no menu suspenso Adicionar chave e clique em Criar nova chave.
  9. 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.

Como usar o proxy do Cloud SQL Auth com 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 do Cloud SQL Auth usa um IP para estabelecer uma conexão com sua instância do Cloud SQL. Por padrão, o proxy do Cloud SQL Auth tenta se conectar usando um endereço IPv4 público. Caso sua instância do Cloud SQL tiver apenas um IP particular, o proxy do Cloud SQL Auth usará o endereço IP particular para se conectar.

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

-ip_address_types=PRIVATE

Como executar o proxy do Cloud SQL Auth em um processo separado

Executar o proxy do Cloud SQL Auth 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 do Cloud SQL Auth em um processo separado.

Linux

No Linux ou no macOS, use um & à direita na linha de comando para iniciar o proxy do Cloud SQL Auth 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 do Cloud SQL Auth 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 proxy do Cloud SQL Auth em um contêiner do Docker

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

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

Inicie o proxy do Cloud SQL Auth usando soquetes TCP ou Unix, com os comandos mostrados abaixo.

Soquetes TCP

    docker run -d \
      -v PATH_TO_KEY_FILE:/config \
      -p 127.0.0.1:1433:1433 \
      gcr.io/cloudsql-docker/gce-proxy:1.19.1 /cloud_sql_proxy \
      -instances=INSTANCE_CONNECTION_NAME=tcp:0.0.0.0:1433 \
      -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 proxy do Cloud SQL Auth como um serviço

A execução do proxy do Cloud SQL Auth como um serviço em segundo plano pode ser conveniente para o desenvolvimento e os testes 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 proxy do Cloud SQL Auth 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, use o NSSM para configurar o proxy do Cloud SQL Auth como um serviço do Windows. O NSSM monitora o proxy do Cloud SQL Auth e o reinicia automaticamente se ele parar de responder. Consulte a documentação do NSSM para mais informações.

Como se conectar quando o SSL for necessário

Dicas para trabalhar com o proxy do Cloud SQL Auth

Como usar o proxy do Cloud SQL Auth para se conectar a várias instâncias

Use um cliente proxy local do Cloud SQL Auth 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 TCP

Ao se conectar usando TCP, você especificará uma porta na sua máquina para que o proxy do Cloud SQL Auth detecte 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 -instances=myProject:us-central1:myInstance=tcp:1433,myProject:us-central1:myInstance2=tcp:1234

    # Connect to "myInstance" using port 1433 on your machine:
    sqlcmd -U myUser -S "127.0.0.1,1433"

    # Connect to "myInstance2" using port 1234 on your machine:
    sqlcmd -U myUser -S "127.0.0.1,1234"
  

Como solucionar problemas de conexões de proxy do Cloud SQL Auth

A imagem do Docker do proxy do Cloud SQL Auth é baseada em uma versão específica do proxy. Quando uma nova versão do proxy do Cloud SQL Auth estiver disponível, extraia a nova versão da imagem do Docker do proxy do Cloud SQL Auth para manter seu 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 do Cloud SQL Auth, tente estas opções para encontrar o motivo.

  • Verifique a saída do proxy do Cloud SQL Auth.

    Muitas vezes, a saída do proxy do Cloud SQL Auth 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 em que você iniciou o proxy do Cloud SQL Auth.

  • Se você estiver recebendo um erro 403 notAuthorized e estiver usando uma conta de serviço para autenticar o proxy de Cloud SQL Auth, 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, $PROJECT_ID@appspot.gserviceaccount.com) 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 do Cloud SQL Auth.

  • 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 do Cloud SQL Auth.

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

  • É possível confirmar se o proxy de autenticação do Cloud SQL foi iniciado corretamente procurando nos registros na seção Operações > Logging > Explorador 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/1433 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 do Cloud SQL Auth é 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