Informazioni sulle opzioni di connessione

MySQL   |  PostgreSQL   |  SQL Server

Questa pagina fornisce una panoramica dei modi in cui puoi connetterti all'istanza Cloud SQL e descrive le opzioni di autenticazione e autorizzazione disponibili.

Panoramica

Quando decidi come connetterti all'istanza Cloud SQL, tieni presente che hai a disposizione molte opzioni, tra cui:

• Vuoi che l'istanza Cloud SQL sia accessibile da internet, che sia privata all'interno di una rete Virtual Private Cloud (VPC) o che sia accessibile sia pubblicamente che privatamente?
• Prevedi di scrivere il tuo codice di connessione o di connetterti utilizzando strumenti disponibili pubblicamente come Cloud SQL Auth Proxy o un client psql?
• Vuoi richiedere la crittografia tramite SSL/TLS o consentire il traffico non criptato?

Nelle sezioni seguenti vengono descritte le opzioni offerte da Cloud SQL per connettersi, autorizzare e autenticarsi al database.

• Come connettersi: il percorso di rete utilizzato per raggiungere l'istanza:
  • Un indirizzo IP interno solo VPC (privato).
  • Un indirizzo IP esterno accessibile da internet (pubblico).
• Come autorizzare: le connessioni autorizzate e consentite per collegarsi all'istanza Cloud SQL:
  • Proxy di autenticazione Cloud SQL e librerie del connettore Cloud SQL per Java e Python: forniscono l'accesso in base a IAM.
  • Certificati SSL/TLS con gestione indipendente: consentono solo connessioni basate su chiavi pubbliche specifiche.
  • Reti autorizzate: un elenco di indirizzi IP autorizzati a connettersi.
• Come eseguire l'autenticazione: il metodo per accedere al database.
  • Autenticazione del database integrata: accedi con un nome utente/una password impostati nel motore del database.
  • Autenticazione IAM dei database: accedi con un'email o con un token OAuth 2.0 come password.

Utilizza le informazioni riportate di seguito per decidere quali opzioni di connessione, autorizzazione e autenticazione sono più adatte alle tue esigenze.

Puoi creare un account per valutare le prestazioni di Cloud SQL in scenari reali. I nuovi clienti ricevono anche 300 $di crediti gratuiti da spendere su Cloud SQL per eseguire, testare e implementare i carichi di lavoro. Non ti verrà addebitato alcun importo fino a quando non eseguirai l'upgrade.

Registrati per provare Cloud SQL gratuitamente.

Prima di iniziare

La concessione dell'accesso a un'applicazione non consente automaticamente a un account utente del database di connettersi all'istanza. Prima di poterti connettere a un'istanza, devi disporre di un account utente del database con cui effettuare la connessione. Per le nuove istanze, devi aver configurato l'account utente predefinito. Per ulteriori informazioni, consulta Gestire gli utenti con l'autenticazione integrata.

Come connettersi a Cloud SQL

Le connessioni al database consumano risorse sul server e sull'applicazione di connessione. Utilizza sempre buone pratiche di gestione delle connessioni per ridurre al minimo l'impronta della tua applicazione e ridurre la probabilità di superare i limiti di connessione di Cloud SQL. Per saperne di più, consulta Gestire le connessioni al database.

IP pubblico e privato

In Cloud SQL, l'IP pubblico indica che l'istanza è accessibile tramite la rete internet pubblica. Al contrario, le istanze che utilizzano solo IP privati non sono accessibili tramite internet pubblico, ma sono accessibili tramite un Virtual Private Cloud (VPC). Le istanze Cloud SQL possono avere un indirizzo IP pubblico e uno privato.

IP privato

Un IP privato è un indirizzo IPv4 accessibile su un Virtual Private Cloud (VPC).

Puoi utilizzare questo indirizzo per connetterti da altre risorse con accesso al VPC. Le connessioni tramite IP privato in genere forniscono una latenza inferiore e vettori di attacco limitati perché non richiedono il passaggio attraverso internet. Se vuoi, puoi richiedere che tutte le connessioni utilizzino il proxy Cloud SQL o i certificati SSL con gestione indipendente.

È preferibile configurare l'istanza con un indirizzo IP privato quando ti connetti da un client su una risorsa con accesso a un VPC. Per saperne di più sulle risorse che possono utilizzare l'IP privato, consulta Requisiti per l'IP privato.

Per i percorsi IP privati, i seguenti servizi e applicazioni si connettono direttamente all'istanza tramite accesso VPC serverless:

• Ambiente standard di App Engine
• Ambiente flessibile di App Engine
• Funzioni Cloud Run
• Cloud Run

Scopri di più sull'utilizzo dell'IP privato con Cloud SQL

Per istruzioni su come aggiungere un indirizzo IP privato all'istanza, consulta una delle seguenti risorse:

• Configurare la connettività IP privato.
• Connettersi a un'istanza utilizzando Private Service Connect

IP pubblico

Un IP pubblico è un indirizzo IPv4 disponibile esternamente sulla rete internet pubblica. Questo indirizzo può ricevere connessioni da dispositivi sia all'interno che al di fuori della rete di Google, ad esempio da luoghi come casa o ufficio.

Per contribuire a mantenere la tua istanza al sicuro, tutte le connessioni a un'istanza Cloud SQL che utilizzano un IP pubblico devono essere autorizzate utilizzando il proxy di autenticazione Cloud SQL o le reti autorizzate.

La configurazione dell'istanza con un indirizzo IP pubblico è consigliata quando ti connetti da un client che non soddisfa i requisiti per un VPC.

Per istruzioni su come aggiungere un IP pubblico all'istanza, consulta Configurare la connettività IP pubblica.

Per informazioni su come connettere un client psql a un'istanza Cloud SQL tramite IP pubblico, consulta Connessione tramite un client di database.

Indirizzi IP assegnati dinamicamente

Alcune applicazioni devono connettersi all'istanza Cloud SQL utilizzando un indirizzo IP assegnato dinamicamente o temporaneo. È il caso, ad esempio, delle applicazioni PaaS (Platform as a Service).

In questi casi, devi utilizzare il proxy di autenticazione Cloud SQL.

Opzioni di connessione per le istanze

Questa sezione contiene le funzionalità supportate da Cloud SQL per la connessione alle istanze. La sezione contiene anche le opzioni di connessione supportate per la creazione, la disattivazione e l'attivazione delle istanze.

Funzionalità supportate

La tabella seguente elenca le funzionalità supportate da Cloud SQL per collegarsi alle istanze utilizzando connessioni private.

Funzionalità	Istanze con solo accesso ai servizi privati	Istanza solo con Private Service Connect	Istanze con accesso ai servizi privati e Private Service Connect
Connettiti da più VPC	Non supportati.	Supportato.	Supportato tramite l'endpoint Private Service Connect.
Estensioni pglogical, PL/Proxy, dblink e postgres_fdw	Supportato.	Non supportati.	Supportato dall'utilizzo della connettività in uscita per l'accesso ai servizi privati.
Repliche esterne	Supportato.	Non supportati.	Supportato dall'utilizzo della connettività in uscita per l'accesso ai servizi privati.
Endpoint di scrittura	Supportato.	Non supportati.	Supportato per l'accesso privato ai servizi.
Modificare la rete VPC associata per l'accesso privato ai servizi	Supportato.	Non applicabile.	Non supportato per l'accesso ai servizi privati perché per l'istanza è abilitato Private Service Connect. Non applicabile a Private Service Connect.
Visibilità dell'indirizzo IP del client per Cloud SQL	Supportato.	Non supportati.	Supportato tramite l'utilizzo dell'indirizzo IP di accesso ai servizi privati. Non supportato dall'utilizzo dell'endpoint Private Service Connect.

Opzioni di connessione per la creazione di istanze

Cloud SQL supporta le configurazioni con IP privato e IP pubblico. Puoi scegliere le opzioni di connessione in base ai requisiti dell'applicazione.

Puoi configurare l'IP privato per mantenere private le istanze Cloud SQL all'interno di una rete VPC. Sono supportati i seguenti tipi di connessioni private:

• Accesso privato ai servizi: connettiti alle istanze Cloud SQL da una singola rete VPC
• Private Service Connect: connettiti alle istanze Cloud SQL da più reti VPC appartenenti a gruppi, team, progetti o organizzazioni diversi

Se vuoi che l'istanza acceda alle connessioni da client sia all'interno sia all'esterno della rete di Google Cloud tramite la rete internet pubblica, configura l'IP pubblico per l'istanza.

Cloud SQL supporta le seguenti opzioni di connessione per la creazione di istanze:

• Solo accesso ai servizi privati
• Solo Private Service Connect
• Solo IP pubblico
• Accesso ai servizi privati e Private Service Connect
• Accesso sia all'IP pubblico sia ai servizi privati
• IP pubblico, accesso ai servizi privati e Private Service Connect

Disattivare le opzioni di connessione

Cloud SQL supporta la disattivazione delle seguenti opzioni di connessione per le istanze:

• IP pubblico su un'istanza con accesso ai servizi privati e IP pubblico
• IP pubblico su un'istanza con IP pubblico, accesso ai servizi privati e Private Service Connect
• Private Service Connect in un'istanza con accesso sia a Private Service Connect sia ai servizi privati
• Private Service Connect in un'istanza con Private Service Connect, accesso ai servizi privati e IP pubblico

Attivare le opzioni di connessione

Cloud SQL supporta l'attivazione delle seguenti opzioni di connessione per le istanze:

• Accesso ai servizi privati su un'istanza con solo IP pubblico
• Private Service Connect in un'istanza con accesso solo ai servizi privati
• Private Service Connect in un'istanza con accesso ai servizi privati e IP pubblico
• IP pubblico su un'istanza con accesso solo ai servizi privati

Limitazioni

• La creazione di un'istanza con IP pubblico e Private Service Connect non è supportata.
• La disattivazione dell'accesso ai servizi privati su un'istanza con accesso ai servizi privati e Private Service Connect non è supportata.
• La disattivazione dell'accesso ai servizi privati su un'istanza con accesso ai servizi privati e IP pubblico non è supportata.
• Se hai un'istanza che utilizza solo IP pubblico, l'attivazione contemporaneamente dell'accesso ai servizi privati e di Private Service Connect non è supportata. Innanzitutto, abilita l'accesso ai servizi privati e poi Private Service Connect.
• La lista consentita basata su IP tramite l'utilizzo di reti autorizzate non è supportata per le istanze per cui è abilitato Private Service Connect.

Come eseguire l'autorizzazione per Cloud SQL

Nota: queste opzioni ti consentono di controllare solo le connessioni consentite per collegarsi all'istanza. Devi comunque fornire un nome utente e una password del database per eseguire l'autenticazione con il motore del database.

Connettori di lingua Cloud SQL

I connettori dei linguaggi Cloud SQL sono librerie client che forniscono crittografia e autorizzazione IAM quando ti connetti a un'istanza Cloud SQL. Cloud SQL consiglia di utilizzare i connettori dei linguaggi di Cloud SQL per connettersi all'istanza Cloud SQL rispetto ad altre opzioni di connessione.

Puoi utilizzare queste librerie direttamente dal linguaggio di programmazione supportato. Forniscono la stessa autenticazione del proxy di autenticazione Cloud SQL senza richiedere un processo esterno. In questo modo, la sicurezza viene migliorata e i requisiti di configurazione per connettersi a Cloud SQL vengono ridotti. Anche i connettori dei linguaggi Cloud SQL utilizzano lo stesso codice quando si connettono utilizzando un indirizzo IP pubblico o privato.

Per iniziare, consulta Informazioni sui connettori di lingua Cloud SQL.

Proxy di autenticazione Cloud SQL

Il proxy di autenticazione Cloud SQL consente di autorizzare e proteggere le connessioni utilizzando le autorizzazioni Identity and Access Management (IAM). Il proxy di autenticazione Cloud SQL convalida le connessioni utilizzando le credenziali di un account utente o di servizio e inserendo la connessione in un livello SSL/TLS autorizzato per un'istanza Cloud SQL. Per ulteriori dettagli sul funzionamento del proxy di autenticazione Cloud SQL, consulta Informazioni sul proxy di autenticazione Cloud SQL.

L'utilizzo del proxy di autenticazione Cloud SQL è il metodo consigliato per autenticare le connessioni a un'istanza Cloud SQL perché è il metodo più sicuro.

Il proxy di autenticazione Cloud SQL è una libreria open source distribuita come file binario eseguibile. Il proxy di autenticazione Cloud SQL funge da server intermediario che ascolta le connessioni in entrata, le avvolge in SSL/TLS e poi le passa a un'istanza Cloud SQL.

Alcuni ambienti forniscono un meccanismo che si connette utilizzando il proxy di autenticazione Cloud SQL. Per istruzioni sulla connessione utilizzando questi ambienti, consulta una delle seguenti risorse:

• Connessione da Cloud Run
• Connessione da Cloud Run Functions
• Connessione dall'ambiente standard di App Engine
• Connessione dall'ambiente flessibile di App Engine
• Connessione da Google Kubernetes Engine

Certificati SSL/TLS autogestiti

Anziché utilizzare il proxy di autenticazione Cloud SQL per criptare le connessioni, è possibile configurare certificati SSL/TLS client/server specifici per un'istanza Cloud SQL. Questi certificati vengono utilizzati sia per convalidare il client e il server tra loro sia per criptare le connessioni tra di loro.

È vivamente consigliato di utilizzare certificati SSL/TLS con gestione indipendente per fornire la crittografia quando non utilizzi il proxy di autenticazione Cloud SQL. In caso contrario, i tuoi dati vengono trasmessi in modo non sicuro e potrebbero essere intercettati o ispezionati da una terza parte.

Per iniziare a utilizzare i certificati SSL/TLS autogestiti, consulta Autorizzazione con certificati SSL/TLS.

Reti autorizzate

Nota: ti consigliamo vivamente di utilizzare sempre certificati SSL/TLS con gestione indipendente quando utilizzi reti autorizzate per autenticare le connessioni. Se non è criptato, il tuo traffico potrebbe essere vulnerabile all'intercettazione da parte di terze parti.

A meno che non venga utilizzato il proxy di autenticazione Cloud SQL, le connessioni all'indirizzo IP pubblico di un'istanza sono consentite solo se provengono da una rete autorizzata. Le reti autorizzate sono indirizzi IP o intervalli di indirizzi IP che l'utente ha specificato come autorizzati a connettersi.

Attenzione: fai attenzione quando aggiungi le reti autorizzate. Poiché tutti i dispositivi di una rete spesso condividono lo stesso indirizzo IP esterno, l'autorizzazione di un singolo indirizzo potrebbe autorizzare tutti i dispositivi della stessa rete anziché un singolo client.

Per iniziare a utilizzare le reti autorizzate, consulta Autorizzazione con reti autorizzate.

Come eseguire l'autenticazione in Cloud SQL

L'autenticazione fornisce il controllo dell'accesso verificando l'identità di un utente. Per gli utenti finali, l'autenticazione viene eseguita quando l'utente inserisce le credenziali (un nome utente e una password). Per le applicazioni, l'autenticazione viene eseguita quando le credenziali di un utente vengono assegnate a un account di servizio.

Cloud SQL utilizza l'autenticazione integrata del database che si autentica utilizzando un nome utente e una password. Per ulteriori informazioni, consulta la sezione sulla creazione e gestione degli utenti PostgreSQL.

Cloud SQL è inoltre integrato con IAM per aiutarti a monitorare e gestire meglio l'accesso al database di utenti e account di servizio. Questa funzionalità è chiamata autenticazione del database IAM.

Scopri di più sull'autenticazione del database IAM.

Scopri di più sulla creazione e sulla gestione di utenti che utilizzano l'autenticazione IAM dei database.

Strumenti per la connessione a Cloud SQL

La tabella seguente contiene alcune opzioni per connettersi a Cloud SQL:

Opzione di connessione	Ulteriori informazioni
Proxy di autenticazione Cloud SQL	Informazioni sul proxy di autenticazione Cloud SQL Connessione tramite il proxy di autenticazione Cloud SQL Connessione tramite l'immagine Docker del proxy di autenticazione Cloud SQL
Interfaccia a riga di comando gcloud	gcloud sql connect
Connettori di lingua Cloud SQL	Esegui la connessione utilizzando i connettori Cloud SQL per Java, Python e Go.
Cloud Shell	Connessione tramite Cloud Shell
Cloud Code	Connessione tramite Cloud Code nell'IDE JetBrains
Eseguire la connessione utilizzando strumenti di amministrazione del database di terze parti
pgAdmin	pgAdmin.org per PostgreSQL
Toad Edge	Toad Edge per PostgreSQL
Blendo	Come connettere Google Cloud SQL PostgreSQL a Blendo

Esempi di codice

Puoi connetterti al proxy di autenticazione Cloud SQL da qualsiasi linguaggio che ti consenta di connetterti a una socket Unix o TCP. Di seguito sono riportati alcuni snippet di codice di esempi completi su GitHub per aiutarti a comprendere come interagiscono nella tua applicazione.

Connessione con TCP

Istruzione di chiamata del proxy di autenticazione Cloud SQL:

./cloud-sql-proxy INSTANCE_CONNECTION_NAME &

Python

Per visualizzare questo snippet nel contesto di un'applicazione web, consulta il file README su 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

Per visualizzare questo snippet nel contesto di un'applicazione web, consulta il file README su GitHub.

Nota:

• CLOUD_SQL_CONNECTION_NAME deve essere rappresentato come <MY-PROJECT>:<INSTANCE-REGION>:<INSTANCE-NAME>
• L'utilizzo dell'argomento ipTypes=PRIVATE forza SocketFactory a connettersi all'IP privato associato di un'istanza
• Consulta i requisiti della versione della fabbrica di socket JDBC per il file pom.xml qui .

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

Per visualizzare questo snippet nel contesto di un'applicazione web, consulta il file README su 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);
};

Vai

Per visualizzare questo snippet nel contesto di un'applicazione web, consulta il file README su 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#

Per visualizzare questo snippet nel contesto di un'applicazione web, consulta il file README su 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

Per visualizzare questo snippet nel contesto di un'applicazione web, consulta il file README su 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

Per visualizzare questo snippet nel contesto di un'applicazione web, consulta il file README su 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;
    }
}

Connessione con socket Unix

Istruzione di chiamata del proxy di autenticazione Cloud SQL:

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

Python

Per visualizzare questo snippet nel contesto di un'applicazione web, consulta il file README su 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

Per visualizzare questo snippet nel contesto di un'applicazione web, consulta il file README su GitHub.

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

public class ConnectorConnectionPoolFactory extends ConnectionPoolFactory {

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

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

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

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

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

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



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

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

Node.js

Per visualizzare questo snippet nel contesto di un'applicazione web, consulta il file README su 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#

Per visualizzare questo snippet nel contesto di un'applicazione web, consulta il file README su 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;
        }
    }
}

Vai

Per visualizzare questo snippet nel contesto di un'applicazione web, consulta il file README su 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

Per visualizzare questo snippet nel contesto di un'applicazione web, consulta il file README su 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

Per visualizzare questo snippet nel contesto di un'applicazione web, consulta il file README su 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;
    }
}

Risoluzione dei problemi

Se hai problemi di connessione, consulta le seguenti pagine per ricevere assistenza per il debugging o per trovare soluzioni ai problemi noti:

• Eseguire il debug dei problemi di connessione
• Errori di connettività noti
• Risoluzione dei problemi di connessione del proxy di autenticazione Cloud SQL
• Problemi di connessione comuni

Passaggi successivi

• Scopri come effettuare la connessione con la guida introduttiva a Cloud SQL per PostgreSQL.
• Scopri le best practice per la gestione delle connessioni al database.
• Scopri di più sull'autenticazione IAM dei database.
• Scopri come eseguire la connessione utilizzando un client psql da una macchina locale o Compute Engine.
• Scopri di più sulla configurazione della connettività IP.
• Scopri di più sul proxy di autenticazione Cloud SQL.
• Scopri le opzioni di assistenza.