Connettiti utilizzando i connettori di linguaggio Cloud SQL

I connettori Cloud SQL sono librerie che forniscono crittografia e autorizzazione basata su Identity and Access Management (IAM) durante la connessione a un'istanza Cloud SQL. Non possono fornire un percorso di rete per 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 il proxy di autenticazione Cloud SQL. Consulta la pagina Informazioni sulle opzioni di connessione per saperne di più sulla connessione a un'istanza Cloud SQL.

In questa pagina sono descritti i seguenti connettori Cloud SQL:

  • Il connettore Java di Cloud SQL
  • Connettore Python per Cloud SQL (apri in Colab)
  • Il connettore Cloud SQL Go
  • Il 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 o cosa può connettersi alle tue istanze Cloud SQL.
  • Comodità: rimuove il requisito per gestire i certificati SSL, configurare le regole firewall o abilitare le reti autorizzate.

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 delle istanze, consulta Creare istanze.

    Per maggiori informazioni 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 autorizzazioni e crittografia basate su IAM durante la connessione a un'istanza Cloud SQL. Non può fornire un percorso di rete per un'istanza Cloud SQL, se non è già presente.

Installazione

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

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

Autenticazione

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 comando gcloud:

    gcloud auth application-default login

Connettiti con Intellij

Per connettere IntelliJ alla tua istanza Cloud SQL, devi aggiungere la libreria come jar con dipendenze nella sezione File aggiuntivi della pagina delle impostazioni del driver. Ad esempio, a questo scopo, puoi trovare dei fat jar predefiniti nella pagina Release del connettore Java di Cloud SQL.

Python

Il connettore Python di 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 inserire manualmente gli IP nella lista consentita o gestire i certificati SSL.

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

Il driver attualmente supportato per SQL Server è pytds .

Installazione

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

Autenticazione

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 comando gcloud:

    gcloud auth application-default login

Go

Il connettore Cloud SQL Go è un connettore Cloud SQL progettato per l'utilizzo con il linguaggio Go. Per maggiore sicurezza, questo connettore utilizza una solida 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 il runtime Node.js che ti consente di connetterti in modo sicuro alla tua 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, visualizza 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 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 is equivalent to setting the config options below:
    // jdbc:sqlserver://;user=<DB_USER>;password=<DB_PASS>;databaseName=<DB_NAME>;
    // socketFactoryClass=com.google.cloud.sql.sqlserver.SocketFactory;
    // socketFactoryConstructorArg=<INSTANCE_CONNECTION_NAME>

    // 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
        .setDataSourceClassName("com.microsoft.sqlserver.jdbc.SQLServerDataSource");
    config.setUsername(DB_USER); // e.g. "root", "sqlserver"
    config.setPassword(DB_PASS); // e.g. "my-password"
    config.addDataSourceProperty("databaseName", DB_NAME);

    config.addDataSourceProperty("socketFactoryClass",
        "com.google.cloud.sql.sqlserver.SocketFactory");
    config.addDataSourceProperty("socketFactoryConstructorArg", INSTANCE_CONNECTION_NAME);

    // The Java Connector provides SSL encryption, so it should be disabled
    // at the driver level.
    config.addDataSourceProperty("encrypt", "false");

    // ... 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 la pagina Come utilizzare questo connettore. Visualizza un esempio di codice per il test della connessione su GitHub.

import os

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

import sqlalchemy

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

    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.get("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

    connector = Connector(ip_type)

    connect_args = {}
    # If your SQL Server instance requires SSL, you need to download the CA
    # certificate for your instance and include cafile={path to downloaded
    # certificate} and validate_host=False. This is a workaround for a known issue.
    if os.environ.get("DB_ROOT_CERT"):  # e.g. '/path/to/my/server-ca.pem'
        connect_args = {
            "cafile": os.environ["DB_ROOT_CERT"],
            "validate_host": False,
        }

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

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

Go

Per istruzioni dettagliate sull'utilizzo della libreria, consulta la pagina relativa all' utilizzo. 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"
	mssql "github.com/denisenkom/go-mssqldb"
)

type csqlDialer struct {
	dialer     *cloudsqlconn.Dialer
	connName   string
	usePrivate bool
}

// DialContext adheres to the mssql.Dialer interface.
func (c *csqlDialer) DialContext(ctx context.Context, network, addr string) (net.Conn, error) {
	var opts []cloudsqlconn.DialOption
	if c.usePrivate {
		opts = append(opts, cloudsqlconn.WithPrivateIP())
	}
	return c.dialer.Dial(ctx, c.connName, opts...)
}

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

	dbURI := fmt.Sprintf("user id=%s;password=%s;database=%s;", dbUser, dbPwd, dbName)
	c, err := mssql.NewConnector(dbURI)
	if err != nil {
		return nil, fmt.Errorf("mssql.NewConnector: %w", err)
	}
	dialer, err := cloudsqlconn.NewDialer(context.Background())
	if err != nil {
		return nil, fmt.Errorf("cloudsqlconn.NewDailer: %w", err)
	}
	c.Dialer = &csqlDialer{
		dialer:     dialer,
		connName:   instanceConnectionName,
		usePrivate: usePrivate != "",
	}

	dbPool := sql.OpenDB(c)
	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 {Connection} = require('tedious');
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 TCP connection
// to a Cloud SQL instance of SQL Server.
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.getTediousOptions({
    instanceConnectionName: process.env.INSTANCE_CONNECTION_NAME,
    ipType: getIpType(),
  });
  const dbConfig = {
    // Please note that the `server` property here is not used and is only
    // defined due to a bug in the tedious driver
    // (ref: https://github.com/tediousjs/tedious/issues/1541)
    // With that in mind, do not try to change this value since it will have no
    // impact in how the connector works, this sample will be updated to remove
    // this property declaration as soon as the tedious driver bug is fixed
    server: '0.0.0.0', // e.g. '127.0.0.1'
    authentication: {
      type: 'default',
      options: {
        userName: process.env.DB_USER, // e.g. 'my-db-user'
        password: process.env.DB_PASS, // e.g. 'my-db-password'
      },
    },
    options: {
      ...clientOpts,
      // Please note that the `port` property here is not used and is only
      // defined due to a bug in the tedious driver
      // (ref: https://github.com/tediousjs/tedious/issues/1541)
      // With that in mind, do not try to change this value since it will have
      // no impact in how the connector works, this sample will be updated to
      // remove this property declaration as soon as the tedious driver bug is
      // fixed
      port: 9999,
      database: process.env.DB_NAME, // e.g. 'my-database'
      useColumnNames: true,
    },
    // ... Specify additional properties here.
    ...config,
  };

  // Establish a connection to the database.
  return new Connection(dbConfig);
};

Risolvere i problemi

Versioni del driver

Assicurati di utilizzare la versione più recente dei connettori Cloud SQL e del driver del 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 connettersi a un'istanza Cloud SQL utilizzando un indirizzo IP privato, la tua applicazione deve avere già accesso VPC.

Debug dei problemi di connessione

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

Passaggi successivi