Connettiti utilizzando i connettori di lingua Cloud SQL

I connettori Cloud SQL sono librerie che forniscono la crittografia e l'autorizzazione basata su Identity and Access Management (IAM) quando si connettono 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 l'utilizzo di un client di database o del 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 Cloud SQL Java
  • Il connettore Cloud SQL Python (apri in Colab)
  • Il connettore Cloud SQL Go
  • Il connettore Cloud SQL Node.js

Vantaggi

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

  • Autorizzazione IAM: Utilizza le autorizzazioni IAM per controllare chi o cosa può connettersi alle istanze Cloud SQL.
  • Praticità: elimina la necessità di gestire i certificati SSL, configurare le regole firewall o abilitare le reti autorizzate.

Prima di iniziare

  • Abilita l'API Cloud SQL Admin.

    Ruoli richiesti per abilitare le API

    Per abilitare le API, devi disporre del ruolo IAM Amministratore utilizzo servizi (roles/serviceusage.serviceUsageAdmin), che contiene l'autorizzazione serviceusage.services.enable. Scopri come concedere i ruoli.

    Abilitare l'API

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

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

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

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

Configurazione

Java

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

Installa

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

Per esempi di utilizzo di questa libreria nel contesto di un'applicazione, consulta queste applicazioni di esempio.

Autentica

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

Per attivare le credenziali in locale, utilizza il seguente gcloud comando:

    gcloud auth application-default login

Connettiti con IntelliJ

Per connettere IntelliJ all'istanza Cloud SQL, devi aggiungere la libreria come file JAR con le dipendenze nella sezione File aggiuntivi nella pagina delle impostazioni del driver. Ad esempio, i file JAR fat precompilati sono disponibili nella pagina delle release del connettore Cloud SQL Java a questo scopo.

Python

Il connettore Cloud SQL Python è 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 indirizzi IP alla lista consentita o gestire i certificati SSL.

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

Il driver supportato da MySQL è pymysql.

Installa

Per installare l'ultima release del connettore Cloud SQL Python, utilizza il comando pip install e specifica il driver pymysql per il tuo database:

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

Autentica

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

Per attivare le credenziali in locale, utilizza il seguente gcloud comando:

    gcloud auth application-default login

Vai

Il connettore Cloud SQL Go è un connettore Cloud SQL progettato per l'utilizzo con il linguaggio Go. Per una maggiore sicurezza, questo connettore utilizza una crittografia TLS 1.3 robusta, autenticata manualmente tra il connettore client e il proxy lato server, indipendentemente dal protocollo del database.

Installa

Puoi installare questo repository con go get:

    go get cloud.google.com/go/cloudsqlconn

Node.js

Il connettore Node.js è una libreria progettata per l'utilizzo con il runtime Node.js che consente di connetterti in modo sicuro all'istanza Cloud SQL.

Installa

Puoi installare la libreria con npm install:

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

Utilizza

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:mysql:///<DB_NAME>?cloudSqlInstance=<INSTANCE_CONNECTION_NAME>&
    // socketFactory=com.google.cloud.sql.mysql.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:mysql:///%s", DB_NAME));
    config.setUsername(DB_USER); // e.g. "root", "mysql"
    config.setPassword(DB_PASS); // e.g. "my-password"

    config.addDataSourceProperty("socketFactory", "com.google.cloud.sql.mysql.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");

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

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

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

Python

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

import os

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

import sqlalchemy


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

    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(ip_type=ip_type, refresh_strategy="LAZY")

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

    pool = sqlalchemy.create_engine(
        "mysql+pymysql://",
        creator=getconn,
        # ...
    )
    return pool

Vai

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

package cloudsql

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

	"cloud.google.com/go/cloudsqlconn"
	"github.com/go-sql-driver/mysql"
)

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.", 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")
	)

	// WithLazyRefresh() Option is used to perform refresh
	// when needed, rather than on a scheduled interval.
	// This is recommended for serverless environments to
	// avoid background refreshes from throttling CPU.
	d, err := cloudsqlconn.NewDialer(context.Background(), cloudsqlconn.WithLazyRefresh())
	if err != nil {
		return nil, fmt.Errorf("cloudsqlconn.NewDialer: %w", err)
	}
	var opts []cloudsqlconn.DialOption
	if usePrivate != "" {
		opts = append(opts, cloudsqlconn.WithPrivateIP())
	}
	mysql.RegisterDialContext("cloudsqlconn",
		func(ctx context.Context, addr string) (net.Conn, error) {
			return d.Dial(ctx, instanceConnectionName, opts...)
		})

	dbURI := fmt.Sprintf("%s:%s@cloudsqlconn(localhost:3306)/%s?parseTime=true",
		dbUser, dbPwd, dbName)

	dbPool, err := sql.Open("mysql", 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 mysql = require('mysql2/promise');
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 a connection pool for a Cloud SQL instance
// of MySQL 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 = {
    ...clientOpts,
    user: process.env.DB_USER, // e.g. 'my-db-user'
    password: process.env.DB_PASS, // e.g. 'my-db-password'
    database: process.env.DB_NAME, // e.g. 'my-database'
    // ... Specify additional properties here.
    ...config,
  };
  // Establish a connection to the database.
  return mysql.createPool(dbConfig);
};

Applica

Utilizzando l'applicazione forzata del connettore, puoi applicare l'utilizzo solo del proxy di autenticazione Cloud SQL o dei connettori dei linguaggi di Cloud SQL per connetterti alle istanze Cloud SQL. Con l'applicazione forzata del connettore, Cloud SQL rifiuta le connessioni dirette al database.

Se utilizzi un'istanza abilitata a Private Service Connect, esiste una limitazione. Se l'istanza ha l'applicazione forzata del connettore abilitata, non puoi creare repliche di lettura per l'istanza. Allo stesso modo, se l'istanza ha repliche di lettura, non puoi abilitare l'applicazione forzata del connettore per l'istanza.

gcloud

Per applicare l'utilizzo solo del proxy di autenticazione Cloud SQL o dei connettori dei linguaggi di Cloud SQL per connetterti a un'istanza, utilizza il gcloud sql instances patch comando:

gcloud sql instances patch INSTANCE_NAME \
--connector-enforcement=REQUIRED

Sostituisci INSTANCE_NAME con il nome dell'istanza Cloud SQL.

REST

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

  • PROJECT_ID: l'ID o il numero del progetto che contiene l' Google Cloud istanza
  • INSTANCE_NAME: il nome dell'istanza Cloud SQL

Metodo HTTP e URL: 

PATCH https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_NAME

Corpo JSON della richiesta: 

{
  "kind": "sql#instance",
  "name": INSTANCE_NAME,
  "project": PROJECT_ID,
  "settings": {
  "connectorEnforcement": "REQUIRED",
  "kind": "sql#settings"
  }
}

Per inviare la richiesta, espandi una di queste opzioni:

Dovresti ricevere una risposta JSON simile alla seguente:

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_NAME",
  "status": "PENDING",
  "user": "user@example.com",
  "insertTime": "2020-01-16T02:32:12.281Z",
  "operationType": "UPDATE",
  "name": "OPERATION_ID",
  "targetId": "INSTANCE_NAME",
  "selfLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operations/OPERATION_ID",
  "targetProject": "PROJECT_ID"
}

Risoluzione dei problemi

Versioni dei driver

Assicurati di utilizzare l'ultima versione dei connettori Cloud SQL e del driver di database per evitare incompatibilità. Alcune versioni precedenti dei driver non sono supportate.

Percorsi di connessione

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

Debug dei problemi di connessione

Per ulteriore assistenza in caso di problemi di connessione, consulta le pagine Risolvere i problemi di connessione ed Eseguire il debug dei problemi di connessione.

Passaggi successivi