Eseguire la connessione utilizzando i connettori di lingua AlloyDB

Per semplificare la creazione di connessioni sicure dalla tua applicazione a un cluster AlloyDB per PostgreSQL, puoi utilizzare gli AlloyDB Language Connector. Queste librerie client offrono le seguenti funzionalità:

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

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

Per saperne di più sui connettori di linguaggio AlloyDB, consulta la panoramica dei connettori di linguaggio AlloyDB.

Questa pagina illustra i seguenti connettori di linguaggio AlloyDB:

• Connettore Java per AlloyDB
• Connettore Go per AlloyDB
• Connettore Python per 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 di AlloyDB predefiniti.

3. Configura i seguenti ruoli IAM necessari per connetterti a un'istanza AlloyDB:

   • Client AlloyDB (roles/alloydb.client)

   • Service Usage Consumer (roles/serviceusage.serviceUsageConsumer)

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

Installa gli AlloyDB Language Connector

Java

Il connettore Java per 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 per 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>1.12.1</version>
</dependency>

<!-- Add the driver with the latest version -->
<dependency>
  <groupId>org.postgresql</groupId>
  <artifactId>postgresql</artifactId>
  <version>42.7.5</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 per AlloyDB includendo quanto segue nel file build.gradle del tuo progetto:

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

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

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

Python (pg8000)

Il connettore Python di AlloyDB funziona con i driver di database pg8000 (sincrono) e asyncpg (asincrono) per consentire alle entità con autorizzazioni sufficienti di connettersi a un database AlloyDB senza inserire manualmente gli indirizzi IP nella lista consentita.

Installazione

Puoi installare la libreria AlloyDB Python Connector con pip install.

Se utilizzi pg8000, esegui questo comando:

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

Python (asyncpg)

Il connettore Python di AlloyDB funziona con i driver di database pg8000 (sincrono) e asyncpg (asincrono) per consentire alle entità con autorizzazioni sufficienti di connettersi a un database AlloyDB senza inserire manualmente gli indirizzi IP nella lista consentita.

Installazione

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

Se utilizzi asyncpg, esegui questo comando:

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 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 questi comandi:

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

go get cloud.google.com/go/alloydbconn

Configura gli AlloyDB Language Connector

Java

Per utilizzare il connettore Java per AlloyDB per connetterti al tuo 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 un 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, gli AlloyDB Language Connector utilizzano l'autenticazione integrata. Puoi utilizzare l'autenticazione IAM automatica con il connettore Java per AlloyDB. Per attivarlo, includi quanto segue:

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

Python (pg8000)

Per utilizzare il connettore Python di AlloyDB per connetterti al tuo 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 un 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, gli AlloyDB Language Connector utilizzano l'autenticazione integrata. Puoi utilizzare l'autenticazione IAM automatica con il connettore Python di AlloyDB. Per abilitarlo, 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 di AlloyDB per connetterti al tuo cluster AlloyDB, configura il connettore seguendo questi passaggi, se utilizzi asyncpg.

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 un 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, gli AlloyDB Language Connector utilizzano l'autenticazione integrata. Puoi utilizzare l'autenticazione IAM automatica con il connettore Python di 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 di AlloyDB per connetterti al tuo 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 un 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, gli AlloyDB Language Connector utilizzano l'autenticazione integrata. Puoi utilizzare l'autenticazione IAM automatica con il connettore Go di AlloyDB. Per abilitarlo, 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 genera report sulle sue operazioni interne con il prefisso della metrica di sistema alloydb.googleapis.com. Queste metriche aiutano AlloyDB a migliorare le prestazioni 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 tuo 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/postgres"
)

// 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,
	// postgres.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 := postgres.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 un IP pubblico per connetterti al cluster AlloyDB, sostituisci la funzione RegisterDriver con quanto segue:

cleanup, err := postgres.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 := postgres.RegisterDriver(
  "alloydb",
  alloydbconn.WithDefaultDialOptions(alloydbconn.WithPSC()),
)

Autenticazione IAM automatica

Per impostazione predefinita, gli AlloyDB Language Connector utilizzano l'autenticazione integrata. Puoi utilizzare l'autenticazione IAM automatica con il connettore Go di AlloyDB. Per abilitarlo, sostituisci la funzione RegisterDriver con quanto segue:

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

Disattiva 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 della metrica di sistema alloydb.googleapis.com. Queste metriche aiutano AlloyDB a migliorare le prestazioni 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, specifica la seguente opzione durante l'inizializzazione di un Dialer:

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