Eseguire la connessione utilizzando i connettori di lingua AlloyDB

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

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

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

Per ulteriori informazioni sui connettori di lingua AlloyDB, consulta la panoramica dei connettori di lingua AlloyDB.

Questa pagina illustra i seguenti connettori di lingua AlloyDB:

• Il connettore Java AlloyDB
• Il connettore AlloyDB Go
• Connettore Python AlloyDB

Prima di iniziare

1. Abilita l'API AlloyDB Admin.

   Attiva l'API

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

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

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

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

   • roles/alloydb.client

   • roles/serviceusage.serviceUsageConsumer

     Per ulteriori informazioni su quali ruoli e autorizzazioni sono 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 ti connetti a un'istanza AlloyDB.

Installazione

Per Maven, puoi installare il connettore Java AlloyDB aggiungendo quanto segue al 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 in gradle.build del 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 inserire manualmente gli IP nella lista consentita.

Installazione

Puoi installare la libreria AlloyDB Python Connector 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 inserire manualmente gli IP nella lista consentita.

Installazione

Puoi installare la libreria AlloyDB Python Connector con pip install.

Se utilizzi asyncpg, esegui il seguente comando:

Per asyncpg, utilizza:

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

Per ulteriori informazioni sull'utilizzo dei driver asincroni, consulta Utilizzo dei driver asincroni.

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 di lingua AlloyDB

Java

Per utilizzare il connettore Java 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);
  }
}

Utilizzare un IP pubblico

Se utilizzi un IP pubblico per connetterti al cluster AlloyDB, includere quanto segue:

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

Utilizzare Private Service Connect

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

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

Autenticazione IAM automatica

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

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

Python (pg8000)

Per utilizzare il connettore Python AlloyDB per connetterti al tuo cluster AlloyDB, configura il connettore seguendo i passaggi riportati di seguito, se utilizzi pg8000.

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

import pg8000
import sqlalchemy

from google.cloud.alloydb.connector 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)

    def getconn() -> pg8000.dbapi.Connection:
        conn: pg8000.dbapi.Connection = connector.connect(
            inst_uri,
            "pg8000",
            user=user,
            password=password,
            db=db,
        )
        return conn

    # create SQLAlchemy connection pool
    engine = sqlalchemy.create_engine(
        "postgresql+pg8000://",
        creator=getconn,
    )
    engine.dialect.description_encoding = None
    return engine, connector

Utilizzare un IP pubblico

Se utilizzi un IP pubblico per connetterti al cluster AlloyDB, sostituire 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

Utilizzare Private Service Connect

Se utilizzi Private Service Connect per connetterti all'istanza AlloyDB, incorpora 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 di lingua AlloyDB utilizzano l'autenticazione integrata. Puoi utilizzare l'autenticazione IAM automatica con il connettore Python AlloyDB. Per attivarla, 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 tuo cluster AlloyDB, configura il connettore seguendo i passaggi riportati di seguito, 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.alloydb.connector 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)

    async def getconn() -> asyncpg.Connection:
        conn: asyncpg.Connection = await connector.connect(
            inst_uri,
            "asyncpg",
            user=user,
            password=password,
            db=db,
        )
        return conn

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

Utilizzare un IP pubblico

Se utilizzi un IP pubblico per connetterti al cluster AlloyDB, sostituire 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

Utilizzare Private Service Connect

Se utilizzi Private Service Connect per connetterti all'istanza AlloyDB, incorpora 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 di lingua AlloyDB utilizzano l'autenticazione integrata. Puoi utilizzare l'autenticazione IAM automatica con il connettore Python AlloyDB. Per attivarla, 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 tuo cluster AlloyDB, configura il connettore seguendo i passaggi riportati di seguito, 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
}

Utilizzare un IP pubblico

Se utilizzi un IP pubblico per connetterti al cluster AlloyDB, sostituire la funzione d.Dial con quanto segue:

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

Utilizzare Private Service Connect

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

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

Autenticazione IAM automatica

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

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

Go (database/SQL)

Per utilizzare il connettore AlloyDB Go per connetterti al tuo cluster AlloyDB, configura il connettore seguendo i passaggi riportati di seguito, 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/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,
) (*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")
	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
}

Utilizzare un IP pubblico

Se utilizzi un IP pubblico per connetterti al cluster AlloyDB, sostituire la funzione RegisterDriver con quanto segue:

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

Utilizzare Private Service Connect

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

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

Autenticazione IAM automatica

Per impostazione predefinita, i connettori di lingua AlloyDB utilizzano l'autenticazione integrata. Puoi utilizzare l'autenticazione IAM automatica con il connettore AlloyDB Go. Per attivarla, sostituisci la funzione RegisterDriver con quanto segue:

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