Connettiti utilizzando i connettori di lingua Cloud SQL

I connettori Cloud SQL sono librerie che forniscono crittografia e Autorizzazione basata su Identity and Access Management (IAM) per la connessione a un di 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 utilizzando un client di database o Proxy di autenticazione Cloud SQL. Consulta: la sezione Informazioni sulle opzioni di connessione pagina per saperne di più sulla connessione a un'istanza Cloud SQL.

Questa pagina illustra i seguenti connettori Cloud SQL:

  • Connettore Java di Cloud SQL
  • Connettore Python Cloud SQL (Apri in Colab)
  • Il connettore Cloud SQL Go
  • Connettore Node.js di Cloud SQL

Vantaggi

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

  • Autorizzazione IAM: utilizza le autorizzazioni IAM per controllare chi e cosa può connettersi alle tue istanze Cloud SQL.
  • Comodità: rimuove la necessità di gestire i certificati SSL, configurare le regole del firewall o attivare le reti autorizzate.
  • Autenticazione del database IAM: fornisce assistenza per L'aggiornamento automatico di autenticazione dei database IAM.

Prima di iniziare

  • Abilita l'API Cloud SQL Admin.

    Enable the API

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

    Per ulteriori informazioni sulla creazione di istanze, consulta Creare istanze.

    Per ulteriori informazioni sulla configurazione dell'utente predefinito, consulta Imposta la password per l'account utente predefinito.

  • Configurare i ruoli autorizzazioni necessarie per connettersi a un'istanza Cloud SQL.

Configurazione

Java

Il connettore Java di Cloud SQL è una libreria che fornisce Autorizzazione e crittografia basate su IAM per la connessione a di Cloud SQL. Non può fornire un percorso di rete a un un'istanza Cloud SQL, se non ne esiste già una.

Installazione

Per istruzioni su come creare e utilizzare i driver per JDBC e R2DBC con il connettore Java Cloud SQL, consulta i seguenti link:

Per esempi di questa libreria utilizzata nel contesto di un'applicazione, dai un'occhiata a questi applicazioni di esempio.

Autenticazione

Questa libreria utilizza le Credenziali predefinite dell'applicazione per autenticare la connessione al server Cloud SQL.

Per attivare le credenziali localmente, utilizza quanto segue Comando gcloud:

    gcloud auth application-default login

Connettiti a IntelliJ

Per connettere IntelliJ all'istanza Cloud SQL, dovrai aggiungere la libreria come jar con dipendenze nella Sezione File aggiuntivi nella pagina delle impostazioni del driver. Ad esempio, per questo scopo puoi trovare i file JAR precompilati nella pagina Uscite del connettore Java per Cloud SQL.

Python

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

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

I driver supportati da PostgreSQL sono pg8000 e asyncpg.

Installazione

Per installare la release più recente del connettore Python di Cloud SQL, utilizza il comando pip install e specifica il driver pg8000 o asyncpg per il database:

    pip install "cloud-sql-python-connector[pg8000]"

o

    pip install "cloud-sql-python-connector[asyncpg]"

Autenticazione

Questa libreria utilizza le credenziali predefinite dell'applicazione per autenticare la connessione al server Cloud SQL.

Per attivare le credenziali localmente, utilizza quanto segue Comando gcloud:

    gcloud auth application-default login

Vai

Il connettore Cloud SQL Go è un connettore Cloud SQL progettato per l'utilizzo con la lingua Go. Per una maggiore sicurezza, questo connettore utilizza solide 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

Node.js

Il Connettore Node.js è una libreria progettata per essere utilizzata con Node.js che ti consente di connetterti in modo sicuro all'istanza Cloud SQL.

Installazione

Puoi installare la libreria con npm install:

    npm install @google-cloud/cloud-sql-connector

Utilizzo

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


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

Vedi Come utilizzare questo connettore per istruzioni dettagliate sull'uso della libreria. Visualizza un esempio di codice per il test della connessione su GitHub.

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

Vai

Vedi Utilizzo per istruzioni dettagliate sull'uso della libreria. Visualizza un esempio di codice per il test della connessione su GitHub.

package cloudsql

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

	"cloud.google.com/go/cloudsqlconn"
	"github.com/jackc/pgx/v5"
	"github.com/jackc/pgx/v5/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
}

Node.js

Per istruzioni dettagliate sull'utilizzo della libreria, consulta Utilizzo.

const Knex = require('knex');
const {Connector} = require('@google-cloud/cloud-sql-connector');

// In case the PRIVATE_IP environment variable is defined then we set
// the ipType=PRIVATE for the new connector instance, otherwise defaults
// to public ip type.
const getIpType = () =>
  process.env.PRIVATE_IP === '1' || process.env.PRIVATE_IP === 'true'
    ? 'PRIVATE'
    : 'PUBLIC';

// connectWithConnector initializes connection pool for a Cloud SQL instance
// of Postgres using the Cloud SQL Node.js Connector.
const connectWithConnector = 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 connector = new Connector();
  const clientOpts = await connector.getOptions({
    instanceConnectionName: process.env.INSTANCE_CONNECTION_NAME,
    ipType: getIpType(),
  });
  const dbConfig = {
    client: 'pg',
    connection: {
      ...clientOpts,
      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);
};

Risoluzione dei problemi

Versioni driver

Assicurati di utilizzare la versione più recente dei connettori Cloud SQL e il driver di database per evitare incompatibilità. Alcune versioni precedenti di driver non supportati.

Percorsi di connessione

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

Debug dei problemi di connessione

Per ulteriore assistenza sui problemi di connessione, consulta Risoluzione dei problemi e Debug dei problemi di connessione. pagine.

Passaggi successivi