Eseguire la connessione utilizzando i connettori di lingua AlloyDB

I connettori dei linguaggi AlloyDB sono librerie che forniscono una procedura semplificata per stabilire connessioni sicure al tuo cluster utilizzando quanto segue:

  • Connessioni mTLS automatizzate
  • Supporto dell'autorizzazione basata su Identity and Access Management (IAM)
  • Autenticazione IAM automatizzata

I connettori di linguaggio AlloyDB non possono fornire un percorso di rete a un cluster AlloyDB se non è già presente.

Per saperne di più sui connettori dei linguaggi AlloyDB, consulta Panoramica dei connettori dei linguaggi AlloyDB.

Questa pagina illustra i seguenti connettori di linguaggio AlloyDB:

  • Il connettore Java di AlloyDB
  • Il connettore AlloyDB Go
  • Il connettore Python di AlloyDB

Prima di iniziare

  1. Abilita l'API AlloyDB.

    Abilita l'API

  2. Crea un'istanza AlloyDB e configura l'utente predefinito.

    Per saperne di più sulla creazione di un'istanza, consulta Crea un'istanza principale.

    Per ulteriori informazioni sui ruoli utente, consulta Ruoli IAM AlloyDB predefiniti.

  3. Configura i seguenti ruoli e autorizzazioni necessari per connettersi a un'istanza AlloyDB:

    • roles/alloydb.client
    • roles/serviceusage.serviceUsageConsumer

      Per ulteriori informazioni sui ruoli e sulle autorizzazioni richiesti, consulta Gestire l'autenticazione IAM.

Installa i connettori dei linguaggi AlloyDB

Java

Il connettore Java AlloyDB è una libreria che fornisce autorizzazione e crittografia basate su IAM quando ci si connette a un'istanza AlloyDB. Se utilizzi Spring Boot, consulta Spring Boot AlloyDB starter.

Installazione

Per Maven, puoi installare il connettore Java di AlloyDB aggiungendo quanto segue al file pom.xml del tuo progetto:

<!-- Add the connector with the latest version -->
<dependency>
  <groupId>com.google.cloud</groupId>
  <artifactId>alloydb-jdbc-connector</artifactId>
  <version>0.4.0</version>
</dependency>

<!-- Add the driver with the latest version -->
<dependency>
  <groupId>org.postgresql</groupId>
  <artifactId>postgresql</artifactId>
  <version>46.6.0<</version>
</dependency>

<!-- Add HikariCP with the latest version -->
<dependency>
  <groupId>com.zaxxer</groupId>
  <artifactId>HikariCP</artifactId>
  <version>5.1.0</version>
</dependency>

Per Gradle, puoi installare il connettore Java AlloyDB includendo quanto segue nel file gradle.build del tuo progetto:

// Add connector with the latest version
implementation group: 'com.google.cloud.alloydb', name: 'alloydb-jdbc-connector', version: '0.4.0'

// Add driver with the latest version
implementation group: 'org.postgresql', name: 'postgresql', version: '46.6.0'

// Add HikariCP with the latest version
implementation group: 'com.zaxxer', name: 'HikariCP', version: '5.1.0'

Python (pg8000)

AlloyDB Python Connector è una libreria che può essere utilizzata insieme a un driver di database per consentire agli utenti con autorizzazioni sufficienti di connettersi a un database AlloyDB senza dover inserire manualmente gli IP nella lista consentita.

Installazione

Puoi installare la libreria del connettore Python di AlloyDB con pip install.

Se utilizzi pg8000, esegui il seguente comando:

pip install "google-cloud-alloydb-connector[pg8000]" sqlalchemy

Python (asyncpg)

AlloyDB Python Connector è una libreria che può essere utilizzata insieme a un driver di database per consentire agli utenti con autorizzazioni sufficienti di connettersi a un database AlloyDB senza dover inserire manualmente gli IP nella lista consentita.

Installazione

Puoi installare la libreria del connettore Python di AlloyDB con pip install.

Se utilizzi asyncpg, esegui questo comando:

Per asyncpg, utilizza:

pip install "google-cloud-alloydb-connector[asyncpg]" "sqlalchemy[asyncio]"

Per ulteriori informazioni sull'utilizzo del driver asincrono, vedi Utilizzo del driver asincrono.

Go (pgx)

Il connettore AlloyDB Go è un connettore AlloyDB progettato per l'utilizzo con il linguaggio Go.

Installazione

Puoi installare il connettore AlloyDB Go con go get.

Se utilizzi pgx, esegui il seguente comando:

go get github.com/jackc/pgx/v5
go get cloud.google.com/go/alloydbconn

Go (database/sql)

Il connettore AlloyDB Go è un connettore AlloyDB progettato per l'utilizzo con il linguaggio Go.

Installazione

Puoi installare il connettore AlloyDB Go con go get.

Se utilizzi database/sql, esegui il seguente comando:

go get cloud.google.com/go/alloydbconn

Configura i connettori linguistici AlloyDB

Java

Per utilizzare il connettore Java AlloyDB per connetterti al cluster AlloyDB, configuralo seguendo questi passaggi.

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


import com.zaxxer.hikari.HikariConfig;
import com.zaxxer.hikari.HikariDataSource;

public class AlloyDbJdbcConnectorDataSourceFactory {

  public static final String ALLOYDB_DB = System.getenv("ALLOYDB_DB");
  public static final String ALLOYDB_USER = System.getenv("ALLOYDB_USER");
  public static final String ALLOYDB_PASS = System.getenv("ALLOYDB_PASS");
  public static final String ALLOYDB_INSTANCE_NAME = System.getenv("ALLOYDB_INSTANCE_NAME");

  static HikariDataSource createDataSource() {
    HikariConfig config = new HikariConfig();

    config.setJdbcUrl(String.format("jdbc:postgresql:///%s", ALLOYDB_DB));
    config.setUsername(ALLOYDB_USER); // e.g., "postgres"
    config.setPassword(ALLOYDB_PASS); // e.g., "secret-password"
    config.addDataSourceProperty("socketFactory", "com.google.cloud.alloydb.SocketFactory");
    // e.g., "projects/my-project/locations/us-central1/clusters/my-cluster/instances/my-instance"
    config.addDataSourceProperty("alloydbInstanceName", ALLOYDB_INSTANCE_NAME);

    return new HikariDataSource(config);
  }
}

Utilizza IP pubblico

Se utilizzi l'IP pubblico per connetterti al cluster AlloyDB, includi quanto segue:

config.addDataSourceProperty("alloydbIpType", "PUBLIC");

Utilizzare Private Service Connect

Se utilizzi Private Service Connect per connetterti all'istanza AlloyDB, includi quanto segue:

config.addDataSourceProperty("alloydbIpType", "PSC");

Autenticazione IAM automatica

Per impostazione predefinita, i connettori dei linguaggi AlloyDB utilizzano l'autenticazione integrata. Puoi utilizzare l'autenticazione IAM automatica con il connettore Java di AlloyDB. Per attivare, includi quanto segue:

config.addDataSourceProperty("alloydbEnableIAMAuth", "true");

Python (pg8000)

Per utilizzare il connettore Python di AlloyDB per connetterti al cluster AlloyDB, configura il connettore seguendo questi passaggi, se utilizzi pg8000.

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

import sqlalchemy

from google.cloud.alloydbconnector import Connector


def create_sqlalchemy_engine(
    inst_uri: str,
    user: str,
    password: str,
    db: str,
    refresh_strategy: str = "background",
) -> tuple[sqlalchemy.engine.Engine, Connector]:
    """Creates a connection pool for an AlloyDB instance and returns the pool
    and the connector. Callers are responsible for closing the pool and the
    connector.

    A sample invocation looks like:

        engine, connector = create_sqlalchemy_engine(
            inst_uri,
            user,
            password,
            db,
        )
        with engine.connect() as conn:
            time = conn.execute(sqlalchemy.text("SELECT NOW()")).fetchone()
            conn.commit()
            curr_time = time[0]
            # do something with query result
            connector.close()

    Args:
        instance_uri (str):
            The instance URI specifies the instance relative to the project,
            region, and cluster. For example:
            "projects/my-project/locations/us-central1/clusters/my-cluster/instances/my-instance"
        user (str):
            The database user name, e.g., postgres
        password (str):
            The database user's password, e.g., secret-password
        db (str):
            The name of the database, e.g., mydb
        refresh_strategy (Optional[str]):
            Refresh strategy for the AlloyDB Connector. Can be one of "lazy"
            or "background". For serverless environments use "lazy" to avoid
            errors resulting from CPU being throttled.
    """
    connector = Connector(refresh_strategy=refresh_strategy)

    # create SQLAlchemy connection pool
    engine = sqlalchemy.create_engine(
        "postgresql+pg8000://",
        creator=lambda: connector.connect(
            inst_uri,
            "pg8000",
            user=user,
            password=password,
            db=db,
        ),
    )
    engine.dialect.description_encoding = None
    return engine, connector

Utilizza IP pubblico

Se utilizzi l'IP pubblico per connetterti al cluster AlloyDB, sostituisci la funzione di connessione con la seguente:

  def getconn() -> pg8000.dbapi.Connection:
      conn: pg8000.dbapi.Connection = connector.connect(
          inst_uri,
          "pg8000",
          user=user,
          password=password,
          db=db,
          # use ip_type to specify public IP
          ip_type=IPTypes.PUBLIC,
      )
      return conn

Utilizzare Private Service Connect

Se utilizzi Private Service Connect per connetterti all'istanza AlloyDB, includi quanto segue:

  def getconn() -> pg8000.dbapi.Connection:
      conn: pg8000.dbapi.Connection = connector.connect(
          inst_uri,
          "pg8000",
          user=user,
          password=password,
          db=db,
          # use ip_type to specify PSC
          ip_type=IPTypes.PSC,
        )
      return conn

Autenticazione IAM automatica

Per impostazione predefinita, i connettori dei linguaggi AlloyDB utilizzano l'autenticazione integrata. Puoi utilizzare l'autenticazione IAM automatica con il connettore Python di AlloyDB. Per abilitare la funzionalità, sostituisci la funzione di connessione con la seguente:

  def getconn() -> pg8000.dbapi.Connection:
      conn: pg8000.dbapi.Connection = connector.connect(
          inst_uri,
          "pg8000",
          user=user,
          password=password,
          db=db,
          # use enable_iam_auth to enable IAM authentication
          enable_iam_auth=True,
      )
      return conn

Python (asyncpg)

Per utilizzare il connettore Python di AlloyDB per connetterti al cluster AlloyDB, configura il connettore seguendo questi passaggi, se utilizzi async.

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

import asyncpg
import sqlalchemy
import sqlalchemy.ext.asyncio

from google.cloud.alloydbconnector import AsyncConnector


async def create_sqlalchemy_engine(
    inst_uri: str,
    user: str,
    password: str,
    db: str,
    refresh_strategy: str = "background",
) -> tuple[sqlalchemy.ext.asyncio.engine.AsyncEngine, AsyncConnector]:
    """Creates a connection pool for an AlloyDB instance and returns the pool
    and the connector. Callers are responsible for closing the pool and the
    connector.

    A sample invocation looks like:

        engine, connector = await create_sqlalchemy_engine(
            inst_uri,
            user,
            password,
            db,
        )
        async with engine.connect() as conn:
            time = await conn.execute(sqlalchemy.text("SELECT NOW()")).fetchone()
            curr_time = time[0]
            # do something with query result
            await connector.close()

    Args:
        instance_uri (str):
            The instance URI specifies the instance relative to the project,
            region, and cluster. For example:
            "projects/my-project/locations/us-central1/clusters/my-cluster/instances/my-instance"
        user (str):
            The database user name, e.g., postgres
        password (str):
            The database user's password, e.g., secret-password
        db (str):
            The name of the database, e.g., mydb
        refresh_strategy (Optional[str]):
            Refresh strategy for the AlloyDB Connector. Can be one of "lazy"
            or "background". For serverless environments use "lazy" to avoid
            errors resulting from CPU being throttled.
    """
    connector = AsyncConnector(refresh_strategy=refresh_strategy)

    # create SQLAlchemy connection pool
    engine = sqlalchemy.ext.asyncio.create_async_engine(
        "postgresql+asyncpg://",
        async_creator=lambda: connector.connect(
            inst_uri,
            "asyncpg",
            user=user,
            password=password,
            db=db,
        ),
        execution_options={"isolation_level": "AUTOCOMMIT"},
    )
    return engine, connector

Utilizza IP pubblico

Se utilizzi l'IP pubblico per connetterti al cluster AlloyDB, sostituisci la funzione di connessione con la seguente:

  async def getconn() -> asyncpg.Connection:
    conn: asyncpg.Connection = await connector.connect(
        inst_uri,
        "asyncpg",
        user=user,
        password=password,
        db=db,
        # use ip_type to specify public IP
        ip_type=IPTypes.PUBLIC,
    )
    return conn

Utilizzare Private Service Connect

Se utilizzi Private Service Connect per connetterti all'istanza AlloyDB, includi quanto segue:

    async def getconn() -> asyncpg.Connection:
      conn: asyncpg.Connection = await connector.connect(
          inst_uri,
          "asyncpg",
          user=user,
          password=password,
          db=db,
          # use ip_type to specify PSC
          ip_type=IPTypes.PSC,
      )
      return conn

Autenticazione IAM automatica

Per impostazione predefinita, i connettori dei linguaggi AlloyDB utilizzano l'autenticazione integrata. Puoi utilizzare l'autenticazione IAM automatica con il connettore Python di AlloyDB. Per abilitare la funzionalità, sostituisci la funzione di connessione con quanto segue:

  async def getconn() -> asyncpg.Connection:
    conn: asyncpg.Connection = await connector.connect(
        inst_uri,
        "asyncpg",
        user=user,
        password=password,
        db=db,
        # use enable_iam_auth to enable IAM authentication
        enable_iam_auth=True,
    )
    return conn

Go (pgx)

Per utilizzare il connettore Go di AlloyDB per connetterti al cluster AlloyDB, configura il connettore seguendo questi passaggi, se utilizzi pgx.

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

import (
	"context"
	"fmt"
	"net"

	"cloud.google.com/go/alloydbconn"
	"github.com/jackc/pgx/v5/pgxpool"
)

// connectPgx establishes a connection to your database using pgxpool and the
// AlloyDB Go Connector (aka alloydbconn.Dialer)
//
// The function takes an instance URI, a username, a password, and a database
// name. Usage looks like this:
//
//	pool, cleanup, err := connectPgx(
//	  context.Background(),
//	  "projects/myproject/locations/us-central1/clusters/mycluster/instances/myinstance",
//	  "postgres",
//	  "secretpassword",
//	  "mydb",
//	)
//
// In addition to a *pgxpool.Pool type, the function returns a cleanup function
// that should be called when you're done with the database connection.
func connectPgx(
	ctx context.Context, instURI, user, pass, dbname string,
	opts ...alloydbconn.Option,
) (*pgxpool.Pool, func() error, error) {
	// First initialize the dialer. alloydbconn.NewDialer accepts additional
	// options to configure credentials, timeouts, etc.
	//
	// For details, see:
	// https://pkg.go.dev/cloud.google.com/go/alloydbconn#Option
	d, err := alloydbconn.NewDialer(ctx, opts...)
	if err != nil {
		noop := func() error { return nil }
		return nil, noop, fmt.Errorf("failed to init Dialer: %v", err)
	}
	// The cleanup function will stop the dialer's background refresh
	// goroutines. Call it when you're done with your database connection to
	// avoid a goroutine leak.
	cleanup := func() error { return d.Close() }

	dsn := fmt.Sprintf(
		// sslmode is disabled, because the Dialer will handle the SSL
		// connection instead.
		"user=%s password=%s dbname=%s sslmode=disable",
		user, pass, dbname,
	)

	// Prefer pgxpool for applications.
	// For more information, see:
	// https://github.com/jackc/pgx/wiki/Getting-started-with-pgx#using-a-connection-pool
	config, err := pgxpool.ParseConfig(dsn)
	if err != nil {
		return nil, cleanup, fmt.Errorf("failed to parse pgx config: %v", err)
	}

	// Tell pgx to use alloydbconn.Dialer to connect to the instance.
	config.ConnConfig.DialFunc = func(ctx context.Context, _ string, _ string) (net.Conn, error) {
		return d.Dial(ctx, instURI)
	}

	// Establish the connection.
	pool, connErr := pgxpool.NewWithConfig(ctx, config)
	if connErr != nil {
		return nil, cleanup, fmt.Errorf("failed to connect: %s", connErr)
	}

	return pool, cleanup, nil
}

Utilizza IP pubblico

Se utilizzi l'IP pubblico per connetterti al cluster AlloyDB, sostituisci la funzione d.Dial con la seguente:

d.Dial(ctx, instURI, alloydbconn.WithPublicIP())

Utilizzare Private Service Connect

Se utilizzi Private Service Connect per connetterti all'istanza AlloyDB, includi quanto segue:

  d.Dial(ctx, instURI, alloydbconn.WithPSC())

Autenticazione IAM automatica

Per impostazione predefinita, i connettori dei linguaggi AlloyDB utilizzano l'autenticazione integrata. Puoi utilizzare l'autenticazione IAM automatica con il connettore AlloyDB Go. Per abilitare, sostituisci la funzione alloydbconn.NewDialer con quanto segue:

d, err := alloydbconn.NewDialer(ctx, alloydbconn.WithIAMAuthN())

Disattivare la telemetria integrata

L'opzione WithOptOutOfBuiltInTelemetry disattiva l'esportazione delle metriche interne. Per impostazione predefinita, il dialer genera report sulle sue operazioni interne con il prefisso alloydb.googleapis.com della metrica di sistema. Queste metriche aiutano AlloyDB a migliorare il rendimento e a identificare i problemi di connettività dei client. Questa opzione è utile per le applicazioni che operano in ambienti in cui l'esportazione delle metriche in uscita è limitata. Per disattivare questa telemetria, fornisci la seguente opzione durante l'inizializzazione di un dialer:

  d.Dial(ctx, instURI, alloydbconn.WithOptOutOfBuiltInTelemetry())

Go (database/sql)

Per utilizzare il connettore Go di AlloyDB per connetterti al cluster AlloyDB, configura il connettore seguendo questi passaggi, se utilizzi database/sql.

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

import (
	"database/sql"
	"fmt"

	"cloud.google.com/go/alloydbconn"
	"cloud.google.com/go/alloydbconn/driver/pgxv5"
)

// connectDatabaseSQL establishes a connection to your database using the Go
// standard library's database/sql package and using the AlloyDB Go Connector
// (aka alloydbconn.Dialer)
//
// The function takes an instance URI, a username, a password, and a database
// name. Usage looks like this:
//
//	db, cleanup, err := connectDatabaseSQL(
//	  "projects/myproject/locations/us-central1/clusters/mycluster/instances/myinstance",
//	  "postgres",
//	  "secretpassword",
//	  "mydb",
//	)
//
// In addition to a *db.SQL type, the function returns a cleanup function that
// should be called when you're done with the database connection.
func connectDatabaseSQL(
	instURI, user, pass, dbname string,
	opts ...alloydbconn.Option,
) (*sql.DB, func() error, error) {
	// First, register the AlloyDB driver. Note, the driver's name is arbitrary
	// and must only match what you use below in sql.Open. Also,
	// pgxv5.RegisterDriver accepts options to configure credentials, timeouts,
	// etc.
	//
	// For details, see:
	// https://pkg.go.dev/cloud.google.com/go/alloydbconn#Option
	//
	// The cleanup function will stop the dialer's background refresh
	// goroutines. Call it when you're done with your database connection to
	// avoid a goroutine leak.
	cleanup, err := pgxv5.RegisterDriver("alloydb", opts...)
	if err != nil {
		return nil, cleanup, err
	}

	db, err := sql.Open(
		"alloydb",
		fmt.Sprintf(
			// sslmode is disabled, because the Dialer will handle the SSL
			// connection instead.
			"host=%s user=%s password=%s dbname=%s sslmode=disable",
			instURI, user, pass, dbname,
		),
	)
	return db, cleanup, err
}

Utilizza IP pubblico

Se utilizzi l'IP pubblico per connetterti al cluster AlloyDB, sostituisci la funzione RegisterDriver con la seguente:

cleanup, err := pgxv5.RegisterDriver(
  "alloydb",
  alloydbconn.WithDefaultDialOptions(alloydbconn.WithPublicIP())
)

Utilizzare Private Service Connect

Se utilizzi Private Service Connect per connetterti all'istanza AlloyDB, includi quanto segue:

  cleanup, err := pgxv5.RegisterDriver(
    "alloydb",
    alloydbconn.WithDefaultDialOptions(alloydbconn.WithPSC())
)

Autenticazione IAM automatica

Per impostazione predefinita, i connettori dei linguaggi AlloyDB utilizzano l'autenticazione integrata. Puoi utilizzare l'autenticazione IAM automatica con il connettore AlloyDB Go. Per abilitare la funzionalità, sostituisci la funzione RegisterDriver con quanto segue:

cleanup, err := pgxv5.RegisterDriver(
  "alloydb",
  alloydbconn.WithIAMAuthN()
)

Disattivare la telemetria integrata

L'opzione WithOptOutOfBuiltInTelemetry disattiva l'esportazione delle metriche interne. Per impostazione predefinita, il dialer genera report sulle sue operazioni interne con il prefisso alloydb.googleapis.com della metrica di sistema. Queste metriche aiutano AlloyDB a migliorare il rendimento e a identificare i problemi di connettività dei client. Questa opzione è utile per le applicazioni che operano in ambienti in cui l'esportazione delle metriche in uscita è limitata. Per disattivare questa telemetria, fornisci la seguente opzione durante l'inizializzazione di un dialer:

cleanup, err := pgxv5.RegisterDriver(
  "alloydb",
  alloydbconn.WithOptOutOfBuiltInTelemetry(),
)