Connessione tramite i connettori Cloud SQL

I connettori Cloud SQL sono librerie che forniscono crittografia e autorizzazione basata su IAM quando ti connetti a un'istanza Cloud SQL. Non possono fornire un percorso di rete a un'istanza Cloud SQL, se non è già presente.

Altri modi per connettersi a un'istanza Cloud SQL includono utilizzare un client di database o il proxy di autenticazione Cloud SQL. Per ulteriori informazioni sulla connessione a un'istanza Cloud SQL, consulta la pagina Informazioni sulle opzioni di connessione.

Questa pagina illustra i seguenti connettori Cloud SQL:

  • Il connettore Java di Cloud SQL
  • Il connettore Python Cloud SQL (aperto in Colab)
  • Il connettore Cloud SQL Go

Vantaggi

L'utilizzo di un connettore Cloud SQL offre i seguenti vantaggi:

  • Autorizzazione IAM: utilizza le autorizzazioni di gestione di identità e accessi (IAM) per controllare chi o cosa può connettersi alle istanze Cloud SQL.
  • Praticità:rimuove il requisito per gestire i certificati SSL, configurare le regole firewall o abilitare le reti autorizzate.
  • Autenticazione database IAM: fornisce supporto per la funzionalità di autenticazione automatica dei database IAM di Cloud SQL.

Prima di iniziare

  • Abilitare l'API Cloud SQL Admin.

    Abilita l'API

  • Creare un'istanza Cloud SQL, inclusa la configurazione dell'utente predefinito.

    Per maggiori informazioni sulla creazione di istanze, consulta la pagina Creare istanze.

    Per saperne di più sulla configurazione dell'utente predefinito, consulta Impostare la password per l'account utente predefinito.

  • Configura i ruoli e le autorizzazioni necessari per la connessione a un'istanza Cloud SQL.

Configurazione

Java

Il connettore Java di Cloud SQL è una libreria che fornisce autorizzazione e crittografia basate su IAM quando si connette a un'istanza Cloud SQL. Non può fornire un percorso di rete a un'istanza Cloud SQL, se non è già presente.

Installazione

Per istruzioni sulla creazione e l'utilizzo dei driver per JDBC e R2DBC con il connettore Java di Cloud SQL, consulta i seguenti link:

JDBC: Connessione a Postgres tramite JDBC.

R2DBC: connessione a Postgres tramite R2DBC.

Per alcuni esempi di libreria utilizzata nel contesto di un'applicazione, guarda queste applicazioni di esempio.

Autenticazione

Questa libreria utilizza le credenziali predefinite delle applicazioni per autenticare la connessione al server Cloud SQL.

Per attivare le credenziali localmente, utilizza il seguente comando gcloud:

    gcloud auth application-default login

Connettiti con Intellij

Per connettere IntelliJ all'istanza Cloud SQL, dovrai aggiungere la libreria come un jar con dipendenze nella sezione File aggiuntivi sulla pagina delle impostazioni del driver. Ad esempio, i jar grassi predefiniti sono disponibili alla pagina Release del connettore Java di Cloud SQL a questo scopo.

Python

Il connettore Python Cloud SQL è una libreria che può essere utilizzata insieme a un driver di database per consentire agli utenti con autorizzazioni sufficienti di connettersi a un database Cloud SQL senza dover aggiungere manualmente gli IP alla lista consentita o gestire i certificati SSL.

Per esempi interattivi di utilizzo del connettore Python Cloud SQL, apri il blocco note del connettore Python Cloud SQL.

Il driver attualmente supportato per PostgreSQL è pg8000 .

Installazione

Per installare la release più recente, segui queste istruzioni.

Autenticazione

Questa libreria utilizza le credenziali predefinite delle applicazioni per autenticare la connessione al server Cloud SQL.

Per attivare le credenziali localmente, utilizza il seguente comando gcloud:

    gcloud auth application-default login

Go

Il connettore Cloud SQL Go è un connettore Cloud SQL progettato per essere utilizzato con il linguaggio Go. Per migliorare la sicurezza, questo connettore utilizza la robusta crittografia TLS 1.3 autenticata manualmente tra il connettore client e il proxy lato server, indipendentemente dal protocollo del database.

Installazione

Puoi installare questo repository con go get:

    go get cloud.google.com/go/cloudsqlconn

Utilizzo

Java

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

cloud-sql/postgres/servlet/src/main/java/com/example/cloudsql/ConnectorConnectionPoolFactory.java 
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);

    // The ipTypes argument can be used to specify a comma delimited list of preferred IP types
    // for connecting to a Cloud SQL instance. The argument ipTypes=PRIVATE will force the
    // SocketFactory to connect with an instance's associated private IP.
    config.addDataSourceProperty("ipTypes", "PUBLIC,PRIVATE");

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

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

Python

Per istruzioni dettagliate sull'uso della libreria, consulta Come utilizzare questo connettore. Visualizza il codice di esempio del test di connessione su GitHub.

cloud-sql/postgres/sqlalchemy/connect_connector.py 
import os

from google.cloud.sql.connector import Connector, IPTypes
import pg8000

import sqlalchemy

def connect_with_connector() -> sqlalchemy.engine.base.Engine:
    """
    Initializes a connection pool for a Cloud SQL instance of Postgres.

    Uses the Cloud SQL Python Connector package.
    """
    # 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.

    instance_connection_name = os.environ["INSTANCE_CONNECTION_NAME"]  # e.g. 'project:region:instance'
    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'

    ip_type = IPTypes.PRIVATE if os.environ.get("PRIVATE_IP") else IPTypes.PUBLIC

    # initialize Cloud SQL Python Connector object
    connector = Connector()

    def getconn() -> pg8000.dbapi.Connection:
        conn: pg8000.dbapi.Connection = connector.connect(
            instance_connection_name,
            "pg8000",
            user=db_user,
            password=db_pass,
            db=db_name,
            ip_type=ip_type,
        )
        return conn

    # The Cloud SQL Python Connector can be used with SQLAlchemy
    # using the 'creator' argument to 'create_engine'
    pool = sqlalchemy.create_engine(
        "postgresql+pg8000://",
        creator=getconn,
        # ...
    )
    return pool

Go

Per istruzioni dettagliate sull'utilizzo della libreria, consulta la sezione Utilizzo. Visualizza il codice di esempio del test di connessione su GitHub.

cloudsql/postgres/database-sql/connect_connector.go 
package cloudsql

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

	"cloud.google.com/go/cloudsqlconn"
	"github.com/jackc/pgx/v4"
	"github.com/jackc/pgx/v4/stdlib"
)

func connectWithConnector() (*sql.DB, error) {
	mustGetenv := func(k string) string {
		v := os.Getenv(k)
		if v == "" {
			log.Fatalf("Fatal Error in connect_connector.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 passwords and other secrets safe.
	var (
		dbUser                 = mustGetenv("DB_USER")                  // e.g. 'my-db-user'
		dbPwd                  = mustGetenv("DB_PASS")                  // e.g. 'my-db-password'
		dbName                 = mustGetenv("DB_NAME")                  // e.g. 'my-database'
		instanceConnectionName = mustGetenv("INSTANCE_CONNECTION_NAME") // e.g. 'project:region:instance'
		usePrivate             = os.Getenv("PRIVATE_IP")
	)

	dsn := fmt.Sprintf("user=%s password=%s database=%s", dbUser, dbPwd, dbName)
	config, err := pgx.ParseConfig(dsn)
	if err != nil {
		return nil, err
	}
	var opts []cloudsqlconn.Option
	if usePrivate != "" {
		opts = append(opts, cloudsqlconn.WithDefaultDialOptions(cloudsqlconn.WithPrivateIP()))
	}
	d, err := cloudsqlconn.NewDialer(context.Background(), opts...)
	if err != nil {
		return nil, err
	}
	// Use the Cloud SQL connector to handle connecting to the instance.
	// This approach does *NOT* require the Cloud SQL proxy.
	config.DialFunc = func(ctx context.Context, network, instance string) (net.Conn, error) {
		return d.Dial(ctx, instanceConnectionName)
	}
	dbURI := stdlib.RegisterConnConfig(config)
	dbPool, err := sql.Open("pgx", dbURI)
	if err != nil {
		return nil, fmt.Errorf("sql.Open: %w", err)
	}
	return dbPool, nil
}

Risolvere i problemi

Versioni driver

Per evitare incompatibilità, assicurati di utilizzare la versione più recente dei connettori Cloud SQL e del driver di database. Alcune versioni meno recenti dei driver non sono supportate

Percorsi di connessione

I connettori Cloud SQL forniscono l'autorizzazione per le connessioni, ma non forniscono nuovi percorsi per la connettività. Ad esempio, per connetterti a un'istanza Cloud SQL utilizzando un indirizzo IP privato, la tua applicazione deve avere già l'accesso VPC.

Debug dei problemi di connessione

Per ulteriori informazioni sui problemi di connessione, consulta le pagine Risoluzione dei problemi e Debug dei problemi di connessione.

Passaggi successivi