Ligue através do proxy Auth do Cloud SQL

MySQL   |  PostgreSQL   |  SQL Server

Esta página descreve como estabelecer ligação à sua instância do Cloud SQL através do proxy Auth do Cloud SQL.

Para mais informações sobre o funcionamento do proxy Auth do Cloud SQL, consulte o artigo Acerca do proxy Auth do Cloud SQL.

Vista geral

A utilização do proxy Auth do Cloud SQL é o método recomendado para estabelecer ligação a uma instância do Cloud SQL. O proxy Auth do Cloud SQL:

• Funciona com pontos finais de IP públicos e privados
• Valida as ligações através de credenciais de um utilizador ou de uma conta de serviço
• Encapsula a ligação numa camada SSL/TLS autorizada para uma instância do Cloud SQL

Alguns Google Cloud serviços e aplicações usam o proxy Auth do Cloud SQL para fornecer ligações para caminhos de IP públicos com encriptação e autorização, incluindo:

• Ambiente padrão do App Engine
• Ambiente flexível do App Engine
• Cloud Run

As aplicações em execução no Google Kubernetes Engine podem estabelecer ligação através do proxy Auth do Cloud SQL.

Nota: para estabelecer ligação a partir do Google Kubernetes Engine, recomendamos que execute o proxy Auth do Cloud SQL num padrão sidecar, como um contentor adicional que partilha um pod com a sua aplicação. Consulte também o início rápido relacionado.

Consulte o guia de início rápido para usar o proxy Auth do Cloud SQL para uma introdução básica à sua utilização.

Também pode estabelecer ligação, com ou sem o proxy Auth do Cloud SQL, através de um cliente psql a partir de uma máquina local ou do Compute Engine.

Antes de começar

Antes de poder estabelecer ligação a uma instância do Cloud SQL, faça o seguinte:

1. • Para um utilizador ou uma conta de serviço, certifique-se de que a conta tem a função de cliente do Cloud SQL. Esta função contém a autorização cloudsql.instances.connect, que autoriza um principal a ligar-se a todas as instâncias do Cloud SQL num projeto.

     Aceda à página IAM

   • Opcionalmente, pode incluir uma condição da IAM na associação da política da IAM que concede autorização à conta para estabelecer ligação apenas a uma instância específica do Cloud SQL.

2. Enable the Cloud SQL Admin API.

   Roles required to enable APIs

   To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

   Enable the API

3. Instale e inicialize a CLI gcloud.
4. Opcional. Instale o cliente Docker do proxy Auth do Cloud SQL.

Transfira o proxy Auth do Cloud SQL

Linux (64 bits)

1. Transfira o proxy Auth do Cloud SQL:

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

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

   chmod +x cloud-sql-proxy

Linux (32 bits)

1. Transfira o proxy Auth do Cloud SQL:

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

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

   chmod +x cloud-sql-proxy

macOS de 64 bits

1. Transfira o proxy Auth do Cloud SQL:

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

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

   chmod +x cloud-sql-proxy

Mac M1

1. Transfira o proxy Auth do Cloud SQL:

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

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

     chmod +x cloud-sql-proxy
     

Windows (64 bits)

Clique com o botão direito do rato em https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.18.2/cloud-sql-proxy.x64.exe e selecione Guardar link como para transferir o proxy Auth do Cloud SQL. Mude o nome do ficheiro para cloud-sql-proxy.exe.

Windows (32 bits)

Clique com o botão direito do rato em https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.18.2/cloud-sql-proxy.x86.exe e selecione Guardar link como para transferir o proxy Auth do Cloud SQL. Mude o nome do ficheiro para cloud-sql-proxy.exe.

Imagem do Docker do proxy Auth do Cloud SQL

O proxy Auth do Cloud SQL tem diferentes imagens de contentores, como distroless, alpine e buster. A imagem do contentor do proxy Auth do Cloud SQL predefinida usa o distroless, que não contém nenhuma shell. Se precisar de um shell ou de ferramentas relacionadas, transfira uma imagem com base no alpine ou no buster. Para mais informações, consulte o artigo Imagens de contentores do proxy Auth do Cloud SQL.

Pode transferir a imagem mais recente para a sua máquina local através do Docker com o seguinte comando:

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

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

Outro SO

Para outros sistemas operativos não incluídos aqui, pode compilar o proxy Auth do Cloud SQL a partir da origem.

Inicie o proxy Auth do Cloud SQL

Consoante o seu idioma e ambiente, pode iniciar o proxy Auth do Cloud SQL através de sockets TCP, sockets Unix ou da imagem Docker do proxy Auth do Cloud SQL. O binário do proxy Auth do Cloud SQL liga-se a uma ou mais instâncias do Cloud SQL especificadas na linha de comandos e abre uma ligação local como TCP ou um soquete Unix. Outras aplicações e serviços, como o código da sua aplicação ou as ferramentas de cliente de gestão de bases de dados, podem ligar-se a instâncias do Cloud SQL através dessas ligações TCP ou de soquetes Unix.

Aviso: tenha cuidado ao associar o proxy Auth do Cloud SQL a uma interface externa. Qualquer pessoa com acesso a essa interface/porta está autorizada a estabelecer ligação à sua instância.

Entradas TCP

Para ligações TCP, o proxy Auth do Cloud SQL escuta em localhost(127.0.0.1) por predefinição. Assim, quando especifica --port PORT_NUMBER para uma instância, a ligação local está em 127.0.0.1:PORT_NUMBER.

Em alternativa, pode especificar um endereço diferente para a ligação local. Por exemplo, veja como fazer com que o proxy Auth do Cloud SQL ouça em 0.0.0.0:1234 para a ligação local:

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

1. Copie o INSTANCE_CONNECTION_NAME. Pode encontrá-lo na página Vista geral da sua instância na consola 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 um IP público e privado configurados e quiser que o proxy Auth do Cloud SQL use o endereço IP privado, tem de fornecer a seguinte opção quando iniciar o proxy Auth do Cloud SQL:

   --private-ip

3. Se estiver a usar uma conta de serviço para autenticar o proxy Auth do Cloud SQL, tenha em atenção a localização no seu computador cliente do ficheiro de chave privada que foi criado quando criou a conta de serviço.
4. Inicie o proxy Auth do Cloud SQL.

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

   • Usando a autenticação do SDK Cloud:

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

     A porta especificada não pode estar já a ser usada, por exemplo, por um servidor de base de dados local.
   • Usar uma conta de serviço e incluir explicitamente o nome da ligaçã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 Auth do Cloud SQL, consulte o artigo Opções para autenticar o proxy Auth do Cloud SQL.

Sockets Unix

Nota: Atualmente, o proxy Auth do Cloud SQL não suporta sockets Unix no Windows, pelo que esta opção só está disponível para plataformas Linux e macOS.

O proxy Auth do Cloud SQL pode ouvir num soquete Unix, que é um mecanismo padrão Posix para usar uma pasta para gerir a comunicação entre dois processos em execução no mesmo anfitrião. As vantagens da utilização de sockets Unix são a melhoria da segurança e a redução da latência. No entanto, não pode aceder a um socket Unix a partir de uma máquina externa.

Nota: a norma PostgreSQL requer um sufixo `.s.PGSQL.5432` no caminho do socket. Algumas bibliotecas aplicam este sufixo automaticamente, mas outras requerem que especifique o caminho do soquete da seguinte forma:

  /cloudsql/INSTANCE_CONNECTION_NAME/.s.PGSQL.5432
  

Para criar e usar um socket Unix, o diretório de destino tem de existir e o proxy Auth do Cloud SQL e a aplicação têm de ter acesso de leitura e escrita ao mesmo.

1. Copie o INSTANCE_CONNECTION_NAME. Pode encontrá-lo na página Vista geral da sua instância na consola 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 os soquetes do proxy Auth do Cloud SQL vão residir:

   sudo mkdir /cloudsql; sudo chmod 777 /cloudsql

3. Se estiver a usar uma conta de serviço para autenticar o proxy Auth do Cloud SQL, tenha em atenção a localização no seu computador cliente do ficheiro de chave privada que foi criado quando criou a conta de serviço.
4. Abra uma nova janela de terminal do Cloud Shell e inicie o Proxy Auth do Cloud SQL.

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

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

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

   • Usar uma conta de serviço:

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

   Inicie o proxy Auth do Cloud SQL no respetivo terminal do Cloud Shell para poder monitorizar o respetivo resultado sem que se misture com o resultado de outros programas.

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

   NOTA: Quando usar um socket Unix para ligar ao Cloud SQL através do proxy Auth do Cloud SQL, certifique-se de que o comprimento do nome do ficheiro do socket não excede o limite do sistema. Depende do sistema, mas, normalmente, tem entre 91 e 108 carateres. No Linux, o comprimento é normalmente definido como 108 e pode usar o seguinte comando para verificar:

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

Docker

Para executar o proxy Auth do Cloud SQL num contentor Docker, use a imagem Docker do proxy Auth do Cloud SQL disponível no Google Container Registry.

Pode iniciar o proxy Auth do Cloud SQL através de sockets TCP ou sockets Unix, com os comandos apresentados abaixo. As opções usam um INSTANCE_CONNECTION_NAME como a string de ligação para identificar uma instância do Cloud SQL. Pode encontrar o INSTANCE_CONNECTION_NAME na página Vista geral da sua instância na Google Cloud consola. Em alternativa, pode executar o seguinte comando:

gcloud sql instances describe INSTANCE_NAME

.

Por exemplo: myproject:myregion:myinstance.

Nota: o proxy Auth do Cloud SQL não suporta a escuta em tomadas de domínio Unix no Windows.

Consoante o seu idioma e ambiente, pode iniciar o proxy Auth do Cloud SQL através de sockets TCP ou sockets Unix. Os sockets Unix não são suportados para aplicações escritas na linguagem de programação Java nem para o ambiente Windows.

Usar entradas 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.18.2 \\
  --address 0.0.0.0 --port 5432 \\
  --credentials-file /path/to/service-account-key.json INSTANCE_CONNECTION_NAME

Se estiver a usar as credenciais fornecidas pela sua 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.

Especifique sempre o prefixo 127.0.0.1 em -p para que o proxy Auth do Cloud SQL não seja exposto fora do anfitrião local. O "0.0.0.0" no parâmetro instances é necessário para tornar a porta acessível a partir do exterior do contentor do Docker.

Usar sockets 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.18.2 --unix-socket=/cloudsql \\
  --credentials-file /path/to/service-account-key.json INSTANCE_CONNECTION_NAME

Se estiver a usar as credenciais fornecidas pela sua 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 estiver a usar uma imagem otimizada para contentores, use um diretório gravável em vez de /cloudsql, por exemplo:

-v /mnt/stateful_partition/cloudsql:/cloudsql

Pode especificar mais do que uma instância, separadas por vírgulas. Também pode usar os metadados do Compute Engine para determinar dinamicamente as instâncias às quais estabelecer ligação. Saiba mais acerca dos parâmetros do proxy Auth do Cloud SQL.

Ligue-se ao cliente psql

Debian/Ubuntu

Instale o cliente psql a partir do gestor de pacotes:

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

CentOS/RHEL

Instale o cliente psql a partir do gestor de pacotes:

sudo yum install postgresql

openSUSE

Instale o cliente psql a partir do gestor de pacotes:

sudo zypper install postgresql

Outras plataformas

1. Transfira a distribuição principal do PostgreSQL para a sua plataforma na página de transferências do PostgreSQL.
   A distribuição principal inclui o cliente psql.
2. Instale a base de dados PostgreSQL seguindo as instruções na página de transferência.

A string de ligação que usa depende de ter iniciado o proxy Auth do Cloud SQL com um socket TCP, um socket UNIX ou o Docker.

Entradas TCP

1. Inicie o cliente psql:

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

   Embora o parâmetro sslmode esteja definido como disable, o proxy Auth do Cloud SQL fornece uma ligação encriptada.

   Quando se liga através de sockets TCP, acede-se ao proxy Auth do Cloud SQL através de 127.0.0.1.

2. Se lhe for pedido, introduza a palavra-passe.
3. É apresentada a linha de comandos psql.

Usar sockets Unix

1. Inicie o cliente psql:

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

   Embora o parâmetro sslmode esteja definido como disable, o proxy Auth do Cloud SQL fornece uma ligação encriptada.

2. Introduza a palavra-passe.
3. É apresentada a linha de comandos psql.

Precisa de ajuda? Para obter ajuda na resolução de problemas do proxy, consulte o artigo Resolução de problemas de ligações do proxy Auth do Cloud SQL ou consulte a nossa página de apoio técnico do Cloud SQL.

Estabeleça ligação com uma aplicação

Pode estabelecer ligação ao proxy Auth do Cloud SQL a partir de qualquer linguagem que lhe permita estabelecer ligação a um soquete Unix ou TCP. Seguem-se alguns fragmentos de código de exemplos completos no GitHub para ajudar a compreender como funcionam em conjunto na sua aplicação.

A estabelecer ligação com TCP

Declaração de invocação do proxy Auth do Cloud SQL:

./cloud-sql-proxy INSTANCE_CONNECTION_NAME &

Python

Para ver este fragmento no contexto de uma app Web, consulte o ficheiro 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 ver este fragmento no contexto de uma app Web, consulte o ficheiro README no GitHub.

Nota:

• CLOUD_SQL_CONNECTION_NAME deve ser representado como <MY-PROJECT>:<INSTANCE-REGION>:<INSTANCE-NAME>
• A utilização do argumento ipTypes=PRIVATE força o SocketFactory a estabelecer ligação com o IP privado associado de uma instância
• Consulte os requisitos da versão da fábrica de sockets JDBC para o ficheiro pom.xml.

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 ver este fragmento no contexto de uma app Web, consulte o ficheiro 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);
};

Ir

Para ver este fragmento no contexto de uma app Web, consulte o ficheiro 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 ver este fragmento no contexto de uma app Web, consulte o ficheiro 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 ver este fragmento no contexto de uma app Web, consulte o ficheiro 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 ver este fragmento no contexto de uma app Web, consulte o ficheiro 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;
    }
}

Estabelecer ligação com sockets Unix

Declaração de invocação do proxy Auth do Cloud SQL:

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

Python

Para ver este fragmento no contexto de uma app Web, consulte o ficheiro 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 ver este fragmento no contexto de uma app Web, consulte o ficheiro 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);
    }


    // cloudSqlRefreshStrategy set to "lazy" is used to perform a
    // refresh when needed, rather than on a scheduled interval.
    // This is recommended for serverless environments to
    // avoid background refreshes from throttling CPU.
    config.addDataSourceProperty("cloudSqlRefreshStrategy", "lazy");

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

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

Node.js

Para ver este fragmento no contexto de uma app Web, consulte o ficheiro 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 ver este fragmento no contexto de uma app Web, consulte o ficheiro 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;
        }
    }
}

Ir

Para ver este fragmento no contexto de uma app Web, consulte o ficheiro 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 ver este fragmento no contexto de uma app Web, consulte o ficheiro 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 ver este fragmento no contexto de uma app Web, consulte o ficheiro 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;
    }
}

Tópicos adicionais

Argumentos da linha de comandos do proxy Auth do Cloud SQL

Os exemplos acima abrangem os exemplos de utilização mais comuns, mas o proxy Auth do Cloud SQL também tem outras opções de configuração que podem ser definidas com argumentos da linha de comandos. Para obter ajuda sobre argumentos de linha de comandos, use a flag --help para ver a documentação mais recente:

./cloud-sql-proxy --help

Consulte o README no repositório do GitHub do proxy Auth do Cloud SQL para ver exemplos adicionais de como usar as opções de linha de comandos do proxy Auth do Cloud SQL.

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

Quando autentica o proxy Auth do Cloud SQL, permite-lhe aceder a Google Cloud em nome da sua aplicação, através de um conjunto de credenciais da Google. Isto é independente da autenticação de utilizadores da base de dados. A autenticação de base de dados de utilizadores do IAM está integrada com o proxy Auth do Cloud SQL.

Todas estas opções usam um INSTANCE_CONNECTION_NAME como a string de ligação para identificar uma instância do Cloud SQL. Pode encontrar o INSTANCE_CONNECTION_NAME na página Vista geral da sua instância na Google Cloud consola. Em alternativa, pode executar o seguinte comando:

gcloud sql instances describe --project PROJECT_ID INSTANCE_CONNECTION_NAME.

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

Algumas destas opções usam um ficheiro de credenciais JSON que inclui a chave privada RSA para a conta. Para instruções sobre como criar um ficheiro de credenciais JSON para uma conta de serviço, consulte o artigo Criar uma conta de serviço.

O Proxy Auth do Cloud SQL oferece várias alternativas para a autenticação, consoante o seu ambiente. O proxy Auth do Cloud SQL verifica cada um dos seguintes itens, pela ordem indicada, usando o primeiro que encontrar para tentar a autenticação:

1. Credenciais fornecidas pela flag credentials-file.

   Use uma conta de serviço para criar e transferir o ficheiro JSON associado e defina a flag --credentials-file para o caminho do ficheiro quando iniciar o proxy Auth do Cloud SQL. A conta de serviço tem de ter as autorizações necessárias para a instância do Cloud SQL.

   Para usar esta opção na linha de comandos, invoque o comando cloud-sql-proxy com o sinalizador --credentials-file definido para o caminho e o nome do ficheiro de credenciais JSON. O caminho pode ser absoluto ou relativo ao diretório de trabalho atual. Por exemplo:

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

   Para obter instruções detalhadas sobre como adicionar funções de IAM a uma conta de serviço, consulte o artigo Conceder funções a contas de serviço.

   Para mais informações sobre as funções suportadas pelo Cloud SQL, consulte o artigo Funções de IAM para o Cloud SQL.

2. Credenciais fornecidas por um token de acesso.

   Crie uma chave de acesso e invoque o comando cloud-sql-proxy com a flag --token definida como uma chave de acesso OAuth 2.0. Por exemplo:

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

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

   Esta opção é semelhante à utilização da flag --credentials-file, exceto que especifica o ficheiro de credenciais JSON que definiu na variável de ambiente GOOGLE_APPLICATION_CREDENTIALS, em vez de usar o argumento da linha de comandos --credentials-file.

4. Credenciais de um cliente da CLI gcloud autenticado.

   Se tiver instalado a CLI gcloud e tiver feito a autenticação com a sua conta pessoal, o proxy Auth do Cloud SQL pode usar as mesmas credenciais da conta. Este método é especialmente útil para ter um ambiente de desenvolvimento a funcionar.

   Para permitir que o proxy Auth do Cloud SQL use as suas credenciais da CLI gcloud, use o seguinte comando para autenticar a CLI gcloud:

   gcloud auth application-default login

5. Credenciais associadas à instância do Compute Engine.

   Se estiver a estabelecer ligação ao Cloud SQL a partir de uma instância do Compute Engine, o proxy Auth do Cloud SQL pode usar a conta de serviço associada à instância do Compute Engine. Se a conta de serviço tiver as autorizações necessárias para a instância do Cloud SQL, o proxy Auth do Cloud SQL é 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 predefinida da instância do Compute Engine tem as autorizações necessárias para autenticar o proxy de autorização do Cloud SQL. Se as duas instâncias estiverem em projetos diferentes, tem de adicionar 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 predefinida do ambiente

   Se o Cloud SQL Auth Proxy não conseguir encontrar credenciais em nenhum dos locais abordados anteriormente, segue a lógica documentada em Configurar a autenticação para aplicações de produção de servidor para servidor. Alguns ambientes (como o Compute Engine, o App Engine e outros) fornecem uma conta de serviço predefinida que a sua aplicação pode usar para fazer a autenticação por predefinição. Se usar uma conta de serviço predefinida, esta tem de ter as autorizações descritas em funções e autorizações. Para mais informações sobre a abordagem da Google Cloud à autenticação, consulte a vista geral da autenticação.

Criar uma conta de serviço

Se estiver a estabelecer ligação a partir do Compute Engine, certifique-se de que a sua VM tem as autorizações adequadas scope para estabelecer ligação através da API Admin do Cloud SQL.

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

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

1. Na Google Cloud consola, aceda à página Contas de serviço.

   Aceda a Contas de serviço

2. Selecione o projeto que contém a sua instância do Cloud SQL.
3. Clique em Criar conta de serviço.
4. No campo Nome da conta de serviço, introduza um nome descritivo para a conta de serviço.
5. Altere o ID da conta de serviço para um valor único e reconhecível e, de seguida, clique em Criar e continuar.
6. Clique no campo Selecionar uma função e selecione uma das seguintes funções:
   • Cloud SQL > Cliente do Cloud SQL
   • Cloud SQL > Editor do Cloud SQL
   • Cloud SQL > Administração do Cloud SQL
   Nota: para criar uma conta de serviço com as autorizações necessárias, tem de ter a autorização resourcemanager.projects.setIamPolicy. Esta autorização está incluída nas funções de proprietário do projeto, administrador de IAM do projeto e administrador da organização.
   Também tem de ter ativado a API Admin do Cloud SQL. Se estiver a usar as funções do projeto antigas (Leitor, Editor, Proprietário), a conta de serviço tem de ter, pelo menos, a função Editor.
7. Clique em Concluído para terminar de criar a conta de serviço.
8. Clique no menu de ações da nova conta de serviço e, de seguida, selecione Gerir chaves.
9. Clique no menu pendente Adicionar chave e, de seguida, em Criar nova chave.
10. Confirme que o tipo de chave é JSON e, de seguida, clique em Criar.

    O ficheiro de chave privada é transferido para o seu computador. Pode movê-lo para outra localização. Mantenha o ficheiro de chave seguro.

Use o proxy Auth do Cloud SQL com IP privado

Para ligar a uma instância do Cloud SQL através de um IP privado, o proxy Auth do Cloud SQL tem de estar num recurso com acesso à mesma rede de VPC que a instância.

O proxy Auth do Cloud SQL usa o IP para estabelecer uma ligação com a sua instância do Cloud SQL. Por predefinição, o proxy Auth do Cloud SQL tenta estabelecer ligação através de um endereço IPv4 público.

Se a sua instância do Cloud SQL tiver apenas IP privado ou tiver o IP público e privado configurados, e quiser que o proxy Auth do Cloud SQL use o endereço IP privado, tem de fornecer a seguinte opção quando iniciar o proxy Auth do Cloud SQL:

--private-ip

Use o proxy Auth do Cloud SQL com instâncias que tenham o Private Service Connect ativado

Pode usar o proxy Auth do Cloud SQL para se ligar a uma instância do Cloud SQL com o Private Service Connect ativado.

O proxy Auth do Cloud SQL é um conetor que fornece acesso seguro a esta instância sem necessidade de redes autorizadas nem de configurar o SSL.

Para permitir ligações de clientes do proxy Auth do Cloud SQL, tem de configurar um registo de DNS que corresponda ao nome de DNS recomendado fornecido para a instância. O registo de DNS é um mapeamento entre um recurso de DNS e um nome de domínio.

Para mais informações sobre a utilização do proxy Auth do Cloud SQL para estabelecer ligação a instâncias com o Private Service Connect ativado, consulte o artigo Estabeleça ligação através do proxy Auth do Cloud SQL.

Execute o proxy Auth do Cloud SQL num processo separado

A execução do proxy Auth do Cloud SQL num processo de terminal do Cloud Shell separado pode ser útil para evitar a mistura da respetiva saída da consola com a saída de outros programas. Use a sintaxe apresentada abaixo para invocar o proxy Auth do Cloud SQL num processo separado.

Linux

No Linux ou macOS, use um & no final da linha de comandos para iniciar o proxy Auth do Cloud SQL num 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 Auth do Cloud SQL num processo separado:

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

Execute o proxy Auth do Cloud SQL num contentor do Docker

Para executar o proxy Auth do Cloud SQL num contentor Docker, use a imagem Docker do proxy Auth do Cloud SQL disponível no Google Container Registry. Pode instalar a imagem do Docker do proxy Auth do Cloud SQL através do seguinte comando:

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

Pode iniciar o proxy Auth do Cloud SQL através de sockets TCP ou sockets Unix, com os comandos apresentados abaixo.

Nota: os sockets Unix não são suportados para aplicações escritas na linguagem de programação Java nem para o ambiente Windows.

Entradas 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.18.2 \
      --address 0.0.0.0 \
      --credentials-file /path/to/service-account-key.json \
      INSTANCE_CONNECTION_NAME

Sockets 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.18.2 --unix-socket /cloudsql \
      --credentials-file /path/to/service-account-key.json/PATH_TO_KEY_FILE \
      INSTANCE_CONNECTION_NAME

Se estiver a usar uma imagem otimizada para contentores, use um diretório gravável em vez de /cloudsql, por exemplo:

v /mnt/stateful_partition/cloudsql:/cloudsql

Se estiver a usar as credenciais fornecidas pela sua 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.

Executar o proxy Auth do Cloud SQL como um serviço

A execução do proxy Auth do Cloud SQL como um serviço em segundo plano é uma opção para o desenvolvimento local e as cargas de trabalho de produção. Durante o desenvolvimento, quando precisar de aceder à sua instância do Cloud SQL, pode iniciar o serviço em segundo plano e pará-lo quando terminar.

Para cargas de trabalho de produção, o proxy Auth do Cloud SQL não oferece atualmente suporte incorporado para execução como um serviço Windows, mas podem ser usados gestores de serviços de terceiros para o executar como um serviço. Por exemplo, pode usar o NSSM para configurar o proxy Auth do Cloud SQL como um serviço do Windows. O NSSM monitoriza o proxy Auth do Cloud SQL e reinicia-o automaticamente se deixar de responder. Consulte a documentação do NSSM para mais informações.

Nota: se executar o proxy Auth do Cloud SQL como um serviço, tenha em atenção que este usa uma ligação segura para comunicar com as instâncias do Cloud SQL, mas as ligações da sua aplicação ao proxy Auth do Cloud SQL não são encriptadas. Por este motivo, certifique-se de que apenas os utilizadores fidedignos conseguem aceder ao endereço e à porta em que o proxy Auth do Cloud SQL está a escutar.

Aplique a utilização do proxy Auth do Cloud SQL

Ative a utilização do proxy Auth do Cloud SQL no Cloud SQL através de ConnectorEnforcement.

Se estiver a usar uma instância ativada com o Private Service Connect, existe uma limitação. Se a instância tiver a aplicação de conetores ativada, não pode criar réplicas de leitura para a instância. Da mesma forma, se a instância tiver réplicas de leitura, não pode ativar a aplicação do conector para a instância.

gcloud

O seguinte comando aplica a utilização de 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 um reinício.

REST v1

O seguinte comando aplica a utilização de conectores do Cloud SQL

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

• 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 do pedido:

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

Para enviar o seu pedido, expanda uma destas opções:

curl (Linux, macOS ou Cloud Shell)

Nota: O comando seguinte pressupõe que tem sessão iniciada na CLI gcloud com a sua conta de utilizador executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que inicia automaticamente sessão na CLI gcloud. Pode verificar a conta atualmente ativa executando o comando gcloud auth list.

Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte comando:

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)

Nota: O comando seguinte pressupõe que iniciou sessão na CLI do Google Cloud com a sua conta de utilizador executando gcloud init ou gcloud auth login .gcloud Pode verificar a conta atualmente ativa executando o comando gcloud auth list.

Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte comando:

$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

Deve receber uma resposta JSON semelhante à seguinte:

{
  "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 a política "connectorEnforcement": "NOT_REQUIRED" em alternativa. A atualização não aciona um reinício.

REST v1beta4

O seguinte comando aplica a utilização de conectores do Cloud SQL.

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

• 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 do pedido:

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

Para enviar o seu pedido, expanda uma destas opções:

curl (Linux, macOS ou Cloud Shell)

Nota: O comando seguinte pressupõe que tem sessão iniciada na CLI gcloud com a sua conta de utilizador executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que inicia automaticamente sessão na CLI gcloud. Pode verificar a conta atualmente ativa executando o comando gcloud auth list.

Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte comando:

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)

Nota: O comando seguinte pressupõe que iniciou sessão na CLI do Google Cloud com a sua conta de utilizador executando gcloud init ou gcloud auth login .gcloud Pode verificar a conta atualmente ativa executando o comando gcloud auth list.

Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte comando:

$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

Deve receber uma resposta JSON semelhante à seguinte:

{
  "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 a política "connectorEnforcement": "NOT_REQUIRED" em alternativa. A atualização não aciona um reinício.

Sugestões para trabalhar com o proxy Auth do Cloud SQL

Invocar o proxy Auth do Cloud SQL

Todas as invocações de proxy de exemplo iniciam o proxy Auth do Cloud SQL em segundo plano, pelo que é devolvida uma mensagem. Reserve esse terminal do Cloud Shell para o proxy Auth do Cloud SQL, para evitar que o respetivo resultado seja misturado com o resultado de outros programas. Além disso, o resultado do proxy Auth do Cloud SQL pode ajudar a diagnosticar problemas de ligação, pelo que pode ser útil capturá-lo num ficheiro de registo. Se não iniciar o proxy Auth do Cloud SQL em segundo plano, o resultado é enviado para stdout, a menos que seja redirecionado.

Não tem de usar /cloudsql como o diretório para os soquetes do proxy Auth do Cloud SQL. (Esse nome de diretório foi escolhido para minimizar as diferenças com as strings de ligação do App Engine.) No entanto, se alterar o nome do diretório, mantenha o comprimento geral ao mínimo. Este é incorporado numa string mais longa que tem um limite de comprimento imposto pelo sistema operativo. Depende do sistema, mas geralmente tem entre 91 e 108 carateres. No Linux, o comprimento é normalmente definido como 108 e pode usar o seguinte comando para verificar:

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

Use o proxy Auth do Cloud SQL para ligar a várias instâncias

Pode usar um cliente do proxy Auth do Cloud SQL local para estabelecer ligação a várias instâncias do Cloud SQL. A forma como o faz depende de estar a usar sockets Unix ou TCP.

Sockets Unix

Para ligar o proxy Auth do Cloud SQL a várias instâncias, fornece o nome de ligação de cada instância como um argumento ao proxy Auth do Cloud SQL, numa lista separada por espaços. O proxy Auth do Cloud SQL liga-se a cada instância quando é iniciado.

Estabelece ligação a cada instância através do respetivo socket no diretório especificado.

Por exemplo:

      ./cloud-sql-proxy --unix-socket /cloudsql \
      myProject:us-central1:myInstance myProject:us-central1:myInstance2 &
      psql -U myUser -h /cloudsql/myProject:us-central1:myInstance2
  

Entradas TCP

Quando se liga através de TCP, especifica uma porta na sua máquina para o proxy Auth do Cloud SQL ouvir em cada instância do Cloud SQL. Quando se liga a várias instâncias do Cloud SQL, cada porta especificada tem de ser única e estar disponível para utilização no seu computador.

Por 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
  

Resolva problemas de ligações do proxy Auth do Cloud SQL

A imagem Docker do proxy Auth do Cloud SQL baseia-se numa versão específica do proxy Auth do Cloud SQL. Quando estiver disponível uma nova versão do proxy Auth do Cloud SQL, transfira a nova versão da imagem do Docker do proxy Auth do Cloud SQL para manter o seu ambiente atualizado. Pode ver a versão atual do proxy Auth do Cloud SQL consultando a página de lançamentos do proxy Auth do Cloud SQL no GitHub.

Se tiver problemas ao ligar-se à sua instância do Cloud SQL através do proxy Auth do Cloud SQL, seguem-se algumas sugestões que pode experimentar para descobrir a causa do problema.

• Confirme que está a usar o endereço IP para estabelecer ligação à instância e não o ponto final de gravação.

• Verifique o resultado do proxy Auth do Cloud SQL.

  Muitas vezes, o resultado do proxy Auth do Cloud SQL pode ajudar a determinar a origem do problema e como o resolver. Encaminhe a saída para um ficheiro ou observe o terminal do Cloud Shell onde iniciou o Proxy Auth do Cloud SQL.

• Se estiver a receber um erro 403 notAuthorized e estiver a usar uma conta de serviço para autenticar o proxy Auth do Cloud SQL, certifique-se de que a conta de serviço tem as autorizações corretas.

  Pode verificar a conta de serviço pesquisando o respetivo ID na página IAM. Tem de ter a autorização cloudsql.instances.connect. As funções predefinidas Cloud SQL Admin, Client e Editor têm esta autorização.

• Se estiver a estabelecer ligação a partir do App Engine e receber um erro 403 notAuthorized, verifique o valor app.yaml cloud_sql_instances para ver se o nome da ligação de instância tem erros ortográficos ou está incorreto. Os nomes das ligaçõ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 a função de IAM de cliente do Cloud SQL.

  Se o serviço do App Engine estiver num projeto (projeto A) e a base de dados estiver noutro (projeto B), este erro significa que a conta de serviço do App Engine não recebeu a função de IAM de cliente do Cloud SQL no projeto com a base de dados (projeto B).

• Certifique-se de que ativa a API Admin do Cloud SQL.

  Se não for o caso, vê uma saída como Error 403: Access Not Configured nos registos do proxy Auth do Cloud SQL.

• Se estiver a incluir várias instâncias na lista de instâncias, certifique-se de que está a usar uma vírgula como delimitador, sem espaços. Se estiver a usar TCP, certifique-se de que especifica portas diferentes para cada instância.

• Se estiver a estabelecer ligação através de sockets UNIX, confirme que os sockets foram criados listando o diretório que indicou quando iniciou o proxy Auth do Cloud SQL.

• Se tiver uma política de firewall de saída, certifique-se de que permite ligações à porta 3307 na instância do Cloud SQL de destino.

  Nota: o proxy Auth do Cloud SQL usa a porta 3307 para se ligar ao servidor do proxy Auth do Cloud SQL. A porta 5432 é a porta predefinida para o protocolo PostgreSQL através de uma ligação TCP direta (não usa o proxy Auth do Cloud SQL).

• Pode confirmar que o proxy de autorização do Cloud SQL foi iniciado corretamente consultando os registos na secção Operações > Registo > Explorador de registos da consolaGoogle Cloud . Uma operação bem-sucedida tem o seguinte aspeto:

  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 quota: quando a quota da API Admin do Cloud SQL é violada, o proxy Auth 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
  

  Assim que uma aplicação se liga ao proxy, o proxy comunica 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 quota. Por exemplo, uma aplicação está a usar incorretamente o conetor e a criar novas ligações desnecessariamente. Em alternativa, contacte o apoio técnico para pedir um aumento da quota da API Admin do Cloud SQL. Se o erro de quota aparecer no arranque, tem de voltar a implementar a aplicação para reiniciar o proxy. Se o erro de quota for apresentado após o arranque, não é necessário voltar a implementar.

O que se segue?

• Saiba mais sobre o proxy Auth do Cloud SQL.
• Saiba mais acerca da gestão de identidade e acesso (IAM).
• Saiba mais sobre as contas de serviço.
• Saiba mais sobre os dois níveis de controlo de acesso para instâncias do Cloud SQL.
• Criar utilizadores e bases de dados.
• Saiba como estabelecer ligação à sua instância a partir da sua aplicação.
• Saiba mais sobre o cliente psql.
• Saiba mais acerca das opções de apoio técnico.