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 cluster utilizzando quanto segue:

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

I connettori dei linguaggi 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 la panoramica dei connettori dei linguaggi AlloyDB.

Questa pagina illustra i seguenti connettori dei linguaggi AlloyDB:

• Il connettore Java AlloyDB
• Il connettore Go AlloyDB
• Il connettore Python 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 saperne di più sui ruoli utente, consulta Ruoli IAM AlloyDB predefiniti.

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

   • roles/alloydb.client

   • roles/serviceusage.serviceUsageConsumer

     Per saperne di più sui ruoli e sulle autorizzazioni necessari, consulta Gestire l'autenticazione IAM.

Installa i connettori dei linguaggi AlloyDB

Java

Il connettore Java AlloyDB è una libreria che fornisce l'autorizzazione e la crittografia basate su IAM quando ti connetti a un'istanza AlloyDB. Se utilizzi Spring Boot, consulta lo starter Spring Boot AlloyDB.

Installazione

Per Maven, puoi installare il connettore Java 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)

Il connettore Python AlloyDB è 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 aggiungere manualmente gli IP alla lista consentita.

Installazione

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

Se utilizzi pg8000, esegui il seguente comando:

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

Python (asyncpg)

Il connettore Python AlloyDB è 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 aggiungere manualmente gli IP alla lista consentita.

Installazione

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

Se utilizzi asyncpg, esegui il seguente comando:

Per asyncpg, utilizza:

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

Per saperne di più sull'utilizzo del driver asincrono, consulta Utilizzo del driver asincrono.

Go (pgx)

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

Installazione

Puoi installare il connettore Go AlloyDB 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 Go AlloyDB è un connettore AlloyDB progettato per l'utilizzo con il linguaggio Go.

Installazione

Puoi installare il connettore Go AlloyDB con go get.

Se utilizzi database/sql, esegui il seguente comando:

go get cloud.google.com/go/alloydbconn

Configura i connettori dei linguaggi AlloyDB

Java

Per utilizzare il connettore Java AlloyDB per connetterti al cluster AlloyDB, configurarlo 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 l'IP pubblico

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

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

Utilizza 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 AlloyDB. Per abilitarla, includi quanto segue:

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

Python (pg8000)

Per utilizzare il connettore Python 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 l'IP pubblico

Se utilizzi l'IP pubblico per connetterti al cluster AlloyDB, sostituisci la funzione di connessione con 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 public IP
          ip_type=IPTypes.PUBLIC,
      )
      return conn

Utilizza 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 AlloyDB. Per abilitarla, sostituisci la funzione di connessione con quanto segue:

  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 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 l'IP pubblico

Se utilizzi l'IP pubblico per connetterti al cluster AlloyDB, 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 ip_type to specify public IP
        ip_type=IPTypes.PUBLIC,
    )
    return conn

Utilizza 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 AlloyDB. Per abilitarla, 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 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 l'IP pubblico

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

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

Utilizza 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 Go AlloyDB. Per abilitarla, sostituisci la funzione alloydbconn.NewDialer con quanto segue:

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

Disattiva la telemetria integrata

L'opzione WithOptOutOfBuiltInTelemetry disattiva l'esportazione delle metriche interne. Per impostazione predefinita, il Dialer segnala le sue operazioni interne al prefisso della metrica di sistema alloydb.googleapis.com. 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 quando inizializzi un Dialer:

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

Go (database/sql)

Per utilizzare il connettore Go 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 l'IP pubblico

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

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

Utilizza 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 Go AlloyDB. Per abilitarla, sostituisci la funzione RegisterDriver con quanto segue:

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

Disattiva la telemetria integrata

L'opzione WithOptOutOfBuiltInTelemetry disattiva l'esportazione delle metriche interne. Per impostazione predefinita, il Dialer segnala le sue operazioni interne al prefisso della metrica di sistema alloydb.googleapis.com. 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 quando inizializzi un Dialer:

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