Esta página foi traduzida pela API Cloud Translation.

Sobre as opções de conexão

MySQL | PostgreSQL | SQL Server

Nesta página, você encontra uma visão geral das maneiras de se conectar à instância do Cloud SQL e a descrição das opções de autenticação e autorização disponíveis.

Visão geral

Ao se conectar à instância do Cloud SQL, há muitas escolhas a serem consideradas, incluindo:

Você quer que sua instância do Cloud SQL seja acessível pela Internet, mantida em uma rede de nuvem privada virtual (VPC) ou que seja acessível como pública e privada?
Você planeja escrever seu próprio código de conexão ou se conectar usando ferramentas disponíveis publicamente, como o proxy do Cloud SQL Auth ou um cliente psql?
Você quer exigir criptografia usando SSL/TLS ou permitir tráfego não criptografado?

Nas seções a seguir, discutiremos as opções que o Cloud SQL oferece para conectar, autorizar e autenticar no banco de dados.

Como se conectar: qual caminho de rede você usa para acessar a instância:
- Um endereço IP interno somente VPC (Privado).
- Um endereço IP externo acessível pela Internet (Público).
Como autorizar: quais conexões são autorizadas e têm permissão para se conectar à instância do Cloud SQL:
- As bibliotecas de proxy de autenticação do Cloud SQL e de conectores do Cloud SQL para Java e Python fornecem acesso com base no IAM.
- Certificados SSL/TLS autogerenciados: permitem apenas conexões com base em chaves públicas específicas.
- Redes autorizadas: uma lista de endereços IP com permissão para se conectar.
Como autenticar: o método para fazer login no seu banco de dados.
- Autenticação de banco de dados integrada: faça login com um nome de usuário/senha definido no mecanismo de banco de dados.
- Autenticação do banco de dados do IAM - login com um e-mail ou um token OAuth como senha.

Use as informações a seguir para decidir quais opções de conexão, autorização e autenticação funcionam melhor para você.

Antes de começar

A concessão de acesso a um aplicativo não permite automaticamente que uma conta de usuário do banco de dados se conecte à instância. Para se conectar a uma instância, é necessário ter uma conta de usuário do banco de dados com que possa se conectar. Para novas instâncias, isso significa que é preciso configurar a conta de usuário padrão. Para mais informações, consulte Gerenciar usuários com a autenticação integrada.

Como se conectar ao Cloud SQL

As conexões do banco de dados consomem recursos no servidor e no aplicativo conectado. Sempre use boas práticas de gerenciamento de conexões para minimizar o espaço ocupado pelo seu aplicativo e reduzir a probabilidade de exceder os limites de conexão do Cloud SQL. Para mais informações, consulte Como gerenciar conexões de banco de dados.

IP público e privado

No Cloud SQL, IP público significa que a instância é acessível pela Internet pública. Por outro lado, as instâncias que usam apenas IP privado não são acessíveis pela Internet pública, mas podem ser acessadas por uma nuvem privada virtual (VPC, na sigla em inglês). As instâncias do Cloud SQL podem ter um endereço IP público e um privado.

IP privado

O IP privado é um endereço IPv4 acessível em uma nuvem privada virtual (VPC).

É possível usar esse endereço para se conectar a partir de outros recursos com acesso à VPC. As conexões por IP privado geralmente fornecem menor latência e vetores de ataque limitados porque não exigem a passagem da Internet. Outra opção é exigir que todas as conexões usem o proxy do Cloud SQL ou os certificados de SSL autogerenciados.

É preferível configurar sua instância com um IP privado ao se conectar a partir de um cliente em um recurso com acesso a uma VPC. Para mais informações sobre quais recursos podem usar IP privado, consulte Requisitos para IP privado.

Para caminhos de IP privado, os seguintes serviços e aplicativos se conectam diretamente à instância pelo acesso VPC sem servidor:

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

Saiba mais sobre como usar IP privado com o Cloud SQL

Para instruções sobre como adicionar um IP privado à instância, consulte uma das seguintes opções:

IP público

Um IP público é um endereço IPv4 disponível externamente na Internet pública. Esse endereço pode receber conexões de dispositivos dentro e fora da rede do Google, inclusive de locais como sua casa ou seu escritório.

Para ajudar a manter as instâncias seguras, todas as conexões com uma instância do Cloud SQL que usam um IP público precisam ser autorizadas com o proxy de autenticação do Cloud SQL ou redes autorizadas.

A configuração da instância com um IP público é melhor quando você se conecta a partir de um cliente que não atende aos requisitos de uma VPC.

Para instruções sobre como adicionar um IP público à instância, consulte Como configurar a conectividade de IP público.

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

Endereços IP atribuídos dinamicamente

Alguns aplicativos precisam se conectar à instância do Cloud SQL usando um endereço IP atribuído dinamicamente (temporário). Esse é o caso dos aplicativos Platform as a Service (PaaS), entre outros.

Nesses casos, é necessário usar o proxy do Cloud SQL Auth.

Opções de conexão para instâncias

Esta seção contém recursos compatíveis com o Cloud SQL para conexão a instâncias. A seção também contém opções de conexão com suporte para criar, desativar e ativar instâncias.

Recursos compatíveis

A tabela a seguir lista os recursos compatíveis com o Cloud SQL para conexões privadas.

Recurso	Instância com acesso apenas a serviços particulares	Instância com o Private Service Connect	Instância com acesso a serviços particulares e o Private Service Connect
Conectar-se de várias VPCs	Incompatível.	Compatível.	Suporte ao uso do endpoint do Private Service Connect.
Extensões `pglogical`, `PL/Proxy`, `dblink` e `postgres_fdw`	Compatível.	Incompatível.	Suporte ao uso da conectividade de saída para acesso a serviços particulares.
Réplicas externas	Compatível.	Incompatível.	Suporte ao uso da conectividade de saída para acesso a serviços particulares.
Endpoint de gravação	Compatível.	Incompatível.	Suporte para acesso a serviços particulares.
Mude a rede VPC associada para o acesso a serviços particulares	Compatível.	Não relevante.	Não é compatível com o acesso a serviços particulares porque a instância tem o Private Service Connect ativado. Não se aplica ao Private Service Connect.
Visibilidade do endereço IP do cliente para o Cloud SQL	Compatível.	Incompatível.	Suporte ao uso do endereço IP de acesso a serviços privados. Não é compatível com o uso do endpoint do Private Service Connect.

Opções de conexão para criar instâncias

O Cloud SQL oferece suporte a configurações de IP particular e público. Você pode escolher as opções de conexão com base nos requisitos do aplicativo.

É possível configurar o IP particular para manter as instâncias do Cloud SQL particulares em uma rede VPC. Os seguintes tipos de conexões privadas são aceitos:

Acesso a serviços particulares: conecte-se a instâncias do Cloud SQL em uma única rede VPC.
Private Service Connect: conecte-se a instâncias do Cloud SQL de várias redes VPC que pertencem a diferentes grupos, equipes, projetos ou organizações.

Se você quiser que a instância acesse conexões de clientes dentro e fora da rede do Google Cloud pela Internet pública, configure o IP público para a instância.

O Cloud SQL oferece suporte às seguintes opções de conexão para criar instâncias:

Somente acesso a serviços particulares
Somente Private Service Connect
Somente IP público
Acesso a serviços particulares e o Private Service Connect
Acesso a IPs públicos e serviços particulares
IP público, acesso a serviços particulares e Private Service Connect

Desativar as opções de conexão

O Cloud SQL oferece suporte para desativar as seguintes opções de conexão para instâncias:

IP público em uma instância com acesso a serviços privados e IP público
IP público em uma instância com IP público, acesso a serviços particulares e Private Service Connect
Private Service Connect em uma instância com o Private Service Connect e o acesso a serviços particulares
Private Service Connect em uma instância com o Private Service Connect, o acesso a serviços particulares e o IP público

Ativar as opções de conexão

O Cloud SQL oferece suporte para ativar as seguintes opções de conexão para instâncias:

Acesso a serviços privados em uma instância com apenas IP público
Private Service Connect em uma instância com acesso apenas a serviços particulares
Private Service Connect em uma instância com acesso a serviços particulares e IP público
IP público em uma instância com acesso apenas a serviços privados

Limitações

Não é possível criar uma instância com IP público e o Private Service Connect.
Não é possível desativar o acesso a serviços particulares em uma instância com o acesso a serviços particulares e o Private Service Connect.
Não é possível desativar o acesso a serviços particulares em uma instância com acesso a serviços particulares e IP público.
Se você tiver uma instância que usa apenas IP público, não será possível ativar o Acesso a serviços particulares e o Private Service Connect juntos. Primeiro, ative o acesso a serviços particulares e, em seguida, o Private Service Connect.
Não há suporte para a lista de permissões baseada em IP usando redes autorizadas em instâncias com o Private Service Connect ativado.

Como autorizar o Cloud SQL

Conectores de linguagem do Cloud SQL

Os conectores de linguagem do Cloud SQL são bibliotecas de cliente que fornecem criptografia e autorização do IAM ao se conectar com uma instância do Cloud SQL. O Cloud SQL recomenda o uso dos conectores de linguagem do Cloud SQL para a conexão com a instância do Cloud SQL, em vez de outras opções de conexão.

Essas bibliotecas podem ser usadas diretamente na linguagem de programação compatível. Elas fornecem a mesma autenticação que o proxy de autenticação do Cloud SQL, sem exigir um processo externo. Isso proporciona maior segurança e requisitos de configuração reduzidos para a conexão com o Cloud SQL. Os conectores do Cloud SQL também usam o mesmo código ao se conectar por meio de um endereço IP público ou privado.

Para começar, consulte Sobre os conectores de linguagem do Cloud SQL.

Proxy do Cloud SQL Auth

O proxy de autenticação do Cloud SQL permite autorizar e proteger conexões usando as permissões do Identity and Access Management (IAM). Ele valida as conexões usando as credenciais de um usuário ou conta de serviço e unindo a conexão em uma camada SSL/TLS autorizada para uma instância do Cloud SQL. Para mais detalhes sobre como o proxy de autenticação do Cloud SQL funciona, consulte Sobre o proxy de autenticação do Cloud SQL.

Por ser o método mais seguro, é recomendável usar o proxy de autenticação do Cloud SQL para autenticar conexões com uma instância do Cloud SQL.

O proxy de autenticação do Cloud SQL é uma biblioteca de código aberto distribuída como um binário executável. O proxy de autenticação do Cloud SQL funciona como um servidor intermediário que detecta conexões de entrada, une essas conexões em SSL/TLS e as transmite para uma instância do Cloud SQL.

Alguns ambientes fornecem um mecanismo que se conecta usando o proxy de autenticação do Cloud SQL. Para instruções sobre como se conectar usando esses ambientes, consulte uma das seguintes opções:

Certificados SSL/TLS autogerenciados

Em vez de usar o proxy de autenticação do Cloud SQL para criptografar as conexões, é possível configurar certificados SSL/TLS de cliente/servidor específicos para uma instância do Cloud SQL. Esses certificados são usados para validar o cliente/servidor e criptografar conexões entre eles.

É altamente recomendável usar certificados SSL/TLS autogerenciados para fornecer criptografia quando o proxy de autenticação do Cloud SQL não estiver sendo usado. Deixar de fazer isso significa que seus dados estão sendo transmitidos sem segurança e podem ser interceptados ou inspecionados por terceiros.

Para começar a usar certificados SSL/TLS autogerenciados, consulte Como autorizar com certificados SSL/TLS.

Redes autorizadas

A menos que o proxy de autenticação do Cloud SQL seja usado, as conexões com o endereço IP público de uma instância só serão permitidas se forem provenientes de uma rede autorizada. As redes autorizadas são endereços IP ou intervalos que o usuário especificou como tendo permissão para se conectar.

Para começar a usar as redes autorizadas, consulte Como autorizar com redes autorizadas.

Como autenticar no Cloud SQL

A autenticação fornece controle de acesso verificando a identidade de um usuário. Para usuários finais, a autenticação é realizada quando o usuário insere credenciais (um nome de usuário e uma senha). Para aplicativos, a autenticação é realizada quando as credenciais de um usuário são atribuídas a uma conta de serviço.

O Cloud SQL usa a autenticação integrada do banco de dados que autentica usando um nome de usuário e uma senha. Para mais informações, consulte Como criar e gerenciar usuários do PostgreSQL.

O Cloud SQL também está integrado ao IAM para ajudar você a monitorar e gerenciar melhor o acesso do banco de dados de usuários e contas de serviço. Esse recurso é chamado de autenticação de banco de dados do IAM.

Saiba mais sobre a autenticação do banco de dados do IAM.

Saiba mais sobre como criar e gerenciar usuários que usam a autenticação do banco de dados do IAM.

Ferramentas para se conectar ao Cloud SQL

A tabela a seguir contém algumas opções para se conectar ao Cloud SQL:

Opção de conexão	Mais informações
Proxy do Cloud SQL Auth	Sobre o proxy de autenticação do Cloud SQL Como se conectar por meio do proxy de autenticação do Cloud SQL Como se conectar por meio da imagem Docker do proxy de autenticação do Cloud SQL
CLI gcloud	`gcloud sql connect`
Conectores de linguagem do Cloud SQL	Como se conectar por meio de conectores do Cloud SQL para Java, Python e Go.
Cloud Shell	Como se conectar usando o Cloud Shell
Cloud Code	Como se conectar usando o Cloud Code no ambiente de desenvolvimento integrado do JetBrains

Conecte-se usando ferramentas de administração de banco de dados de terceiros
pgAdmin	pgAdmin.org para PostgreSQL
Toad Edge	Toad Edge para PostgreSQL
Blendo	Como conectar o Google Cloud SQL PostgreSQL ao Blendo

Amostras de código

É possível se conectar ao proxy de autenticação do Cloud SQL por meio de qualquer linguagem que permita a conexão com um soquete Unix ou TCP. Veja abaixo alguns snippets de código de exemplos completos no GitHub para ajudar você a entender como eles funcionam em conjunto no aplicativo.

Como se conectar com TCP

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

./cloud-sql-proxy INSTANCE_CONNECTION_NAME &

Python

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

import os
import ssl

import sqlalchemy


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

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

Java

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

Observação:

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


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

public class TcpConnectionPoolFactory extends ConnectionPoolFactory {

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

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


  public static DataSource createConnectionPool() {
    // The configuration object specifies behaviors for the connection pool.
    HikariConfig config = new HikariConfig();

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

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


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

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

Node.js

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

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

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

Go

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

package cloudsql

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

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

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

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


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

	// ...

	return dbPool, nil
}

C#

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

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 esse snippet no contexto de um aplicativo da Web, consulte o README no GitHub.

tcp: &tcp
  adapter: postgresql
  # Configure additional properties here.
  # Note: Saving credentials in environment variables is convenient, but not
  # secure - consider a more secure solution such as
  # Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
  # keep secrets safe.
  username: <%= ENV["DB_USER"] %>  # e.g. "my-database-user"
  password: <%= ENV["DB_PASS"] %> # e.g. "my-database-password"
  database: <%= ENV.fetch("DB_NAME") { "vote_development" } %>
  host: <%= ENV.fetch("INSTANCE_HOST") { "127.0.0.1" }%> # '172.17.0.1' if deployed to GAE Flex
  port: <%= ENV.fetch("DB_PORT") { 5432 }%>

PHP

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

namespace Google\Cloud\Samples\CloudSQL\Postgres;

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

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

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

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

        return $conn;
    }
}

Como se conectar com soquetes Unix

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

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

Python

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

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 esse snippet no contexto de um aplicativo da Web, consulte o README no GitHub (em inglês).

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

public class ConnectorConnectionPoolFactory extends ConnectionPoolFactory {

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

  public static DataSource createConnectionPool() {
    // The configuration object specifies behaviors for the connection pool.
    HikariConfig config = new HikariConfig();

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

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

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

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



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

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

Node.js

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

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 esse snippet no contexto de um aplicativo da Web, consulte o README no GitHub (em inglês).

using Npgsql;
using System;

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

                // Note: Saving credentials in environment variables is convenient, but not
                // secure - consider a more secure solution such as
                // Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
                // keep secrets safe.
                Host = Environment.GetEnvironmentVariable("INSTANCE_UNIX_SOCKET"), // e.g. '/cloudsql/project:region:instance'
                Username = Environment.GetEnvironmentVariable("DB_USER"), // e.g. 'my-db-user
                Password = Environment.GetEnvironmentVariable("DB_PASS"), // e.g. 'my-db-password'
                Database = Environment.GetEnvironmentVariable("DB_NAME"), // e.g. 'my-database'
            };
            connectionString.Pooling = true;
            // Specify additional properties here.
            return connectionString;
        }
    }
}

Go

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

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 esse snippet no contexto de um aplicativo da Web, consulte o README no GitHub (em inglês).

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 esse snippet no contexto de um aplicativo da Web, consulte o README no GitHub (em inglês).

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;
    }
}

Resolver problemas

Se você tiver problemas de conexão, consulte as páginas a seguir para receber ajuda na depuração ou localização de soluções para problemas conhecidos:

A seguir

Aprenda a se conectar com o Guia de início rápido do Cloud SQL para Postgres.
Conheça as práticas recomendadas para gerenciar conexões de banco de dados.
Saiba mais sobre a autenticação do banco de dados do IAM.
Saiba mais sobre como se conectar usando um cliente psql em uma máquina local ou no Compute Engine.
Saiba mais sobre configurar a conectividade IP.
Saiba mais sobre o proxy de autenticação do Cloud SQL.
Conheça as opções de suporte.