Se connecter à l'aide des connecteurs de langage AlloyDB

Les connecteurs de langage AlloyDB sont des bibliothèques qui fournissent un processus simplifié pour établir des connexions sécurisées à votre cluster. Ils utilisent les éléments suivants:

• Connexions mTLS automatisées
• Prise en charge de l'autorisation basée sur Identity and Access Management (IAM)
• Authentification IAM automatisée

Les connecteurs de langage AlloyDB ne peuvent pas fournir de chemin d'accès réseau à un cluster AlloyDB s'il n'en existe pas déjà un.

Pour en savoir plus sur les connecteurs de langage AlloyDB, consultez la présentation des connecteurs de langage AlloyDB.

Cette page traite des connecteurs de langage AlloyDB suivants:

• Connecteur Java AlloyDB
• Connecteur AlloyDB Go
• Connecteur Python AlloyDB

Avant de commencer

1. Activez l'API AlloyDB Admin.

   Activer l'API

2. Créez une instance AlloyDB et configurez l'utilisateur par défaut.

   Pour en savoir plus sur la création d'une instance, consultez la section Créer une instance principale.

   Pour en savoir plus sur les rôles utilisateur, consultez la section Rôles IAM AlloyDB prédéfinis.

3. Configurez les rôles et autorisations suivants requis pour vous connecter à une instance AlloyDB:

   • roles/alloydb.client

   • roles/serviceusage.serviceUsageConsumer

     Pour en savoir plus sur les rôles et les autorisations requis, consultez la page Gérer l'authentification IAM.

Installer les connecteurs linguistiques AlloyDB

Java

Le connecteur Java AlloyDB est une bibliothèque qui fournit une autorisation et un chiffrement basés sur IAM lors de la connexion à une instance AlloyDB.

Installation

Pour Maven, vous pouvez installer le connecteur Java AlloyDB en ajoutant ce qui suit au fichier pom.xml de votre projet:

<!-- 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>

Pour Gradle, vous pouvez installer le connecteur Java AlloyDB en incluant les éléments suivants dans le fichier gradle.build de votre projet:

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

Le connecteur Python AlloyDB est une bibliothèque qui peut être utilisée avec un pilote de base de données pour permettre aux utilisateurs disposant des autorisations suffisantes de se connecter à une base de données AlloyDB sans avoir à ajouter manuellement les adresses IP à la liste d'autorisation.

Installation

Vous pouvez installer la bibliothèque du connecteur Python AlloyDB avec pip install.

Si vous utilisez pg8000, exécutez la commande suivante:

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

Python (asyncpg)

Le connecteur Python AlloyDB est une bibliothèque qui peut être utilisée avec un pilote de base de données pour permettre aux utilisateurs disposant des autorisations suffisantes de se connecter à une base de données AlloyDB sans avoir à ajouter manuellement les adresses IP à la liste d'autorisation.

Installation

Vous pouvez installer la bibliothèque du connecteur Python AlloyDB avec pip install.

Si vous utilisez asyncpg, exécutez la commande suivante:

Pour asyncpg, utilisez:

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

Pour en savoir plus sur l'utilisation des pilotes asynchrones, consultez la section Utilisation des pilotes asynchrones.

Go (pgx)

Le connecteur AlloyDB Go est un connecteur AlloyDB conçu pour être utilisé avec le langage Go.

Installation

Vous pouvez installer le connecteur AlloyDB Go avec go get.

Si vous utilisez pgx, exécutez la commande suivante:

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

Go (database/sql)

Le connecteur AlloyDB Go est un connecteur AlloyDB conçu pour être utilisé avec le langage Go.

Installation

Vous pouvez installer le connecteur AlloyDB Go avec go get.

Si vous utilisez database/sql, exécutez la commande suivante:

go get cloud.google.com/go/alloydbconn

Configurer les connecteurs linguistiques AlloyDB

Java

Pour utiliser le connecteur Java AlloyDB pour vous connecter à votre cluster AlloyDB, configurez-le en procédant comme suit.

Pour utiliser cet extrait dans le contexte d'une application Web, consultez le fichier README sur 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);
  }
}

Utiliser une adresse IP publique

Si vous utilisez une adresse IP publique pour vous connecter à votre cluster AlloyDB, incluez les éléments suivants:

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

Utiliser Private Service Connect

Si vous utilisez Private Service Connect pour vous connecter à votre instance AlloyDB, incluez les éléments suivants:

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

Authentification IAM automatique

Par défaut, les connecteurs de langage AlloyDB utilisent une authentification intégrée. Vous pouvez utiliser l'authentification IAM automatique avec le connecteur Java AlloyDB. Pour l'activer, incluez les éléments suivants:

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

Python (pg8000)

Pour utiliser le connecteur Python AlloyDB pour vous connecter à votre cluster AlloyDB, configurez le connecteur en procédant comme suit si vous utilisez pg8000.

Pour utiliser cet extrait dans le contexte d'une application Web, consultez le fichier README sur 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

Utiliser une adresse IP publique

Si vous utilisez une adresse IP publique pour vous connecter à votre cluster AlloyDB, remplacez votre fonction de connexion par la suivante:

  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

Utiliser Private Service Connect

Si vous utilisez Private Service Connect pour vous connecter à votre instance AlloyDB, incluez les éléments suivants:

  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

Authentification IAM automatique

Par défaut, les connecteurs de langage AlloyDB utilisent une authentification intégrée. Vous pouvez utiliser l'authentification IAM automatique avec le connecteur Python AlloyDB. Pour l'activer, remplacez votre fonction de connexion par la suivante:

  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)

Pour utiliser le connecteur Python AlloyDB pour vous connecter à votre cluster AlloyDB, configurez le connecteur en procédant comme suit si vous utilisez async.

Pour utiliser cet extrait dans le contexte d'une application Web, consultez le fichier README sur 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

Utiliser une adresse IP publique

Si vous utilisez une adresse IP publique pour vous connecter à votre cluster AlloyDB, remplacez votre fonction de connexion par la suivante:

  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

Utiliser Private Service Connect

Si vous utilisez Private Service Connect pour vous connecter à votre instance AlloyDB, incluez les éléments suivants:

    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

Authentification IAM automatique

Par défaut, les connecteurs de langage AlloyDB utilisent une authentification intégrée. Vous pouvez utiliser l'authentification IAM automatique avec le connecteur Python AlloyDB. Pour l'activer, remplacez votre fonction de connexion par ce qui suit:

  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)

Pour utiliser le connecteur AlloyDB Go pour vous connecter à votre cluster AlloyDB, configurez le connecteur en procédant comme suit si vous utilisez pgx.

Pour utiliser cet extrait dans le contexte d'une application Web, consultez le fichier README sur 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
}

Utiliser une adresse IP publique

Si vous utilisez une adresse IP publique pour vous connecter à votre cluster AlloyDB, remplacez votre fonction d.Dial par la suivante:

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

Utiliser Private Service Connect

Si vous utilisez Private Service Connect pour vous connecter à votre instance AlloyDB, incluez les éléments suivants:

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

Authentification IAM automatique

Par défaut, les connecteurs de langage AlloyDB utilisent une authentification intégrée. Vous pouvez utiliser l'authentification IAM automatique avec le connecteur AlloyDB Go. Pour l'activer, remplacez la fonction alloydbconn.NewDialer par ce qui suit:

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

Go (database/sql)

Pour utiliser le connecteur AlloyDB Go pour vous connecter à votre cluster AlloyDB, configurez le connecteur en procédant comme suit si vous utilisez database/sql.

Pour utiliser cet extrait dans le contexte d'une application Web, consultez le fichier README sur 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
}

Utiliser une adresse IP publique

Si vous utilisez une adresse IP publique pour vous connecter à votre cluster AlloyDB, remplacez votre fonction RegisterDriver par la suivante:

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

Utiliser Private Service Connect

Si vous utilisez Private Service Connect pour vous connecter à votre instance AlloyDB, incluez les éléments suivants:

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

Authentification IAM automatique

Par défaut, les connecteurs de langage AlloyDB utilisent une authentification intégrée. Vous pouvez utiliser l'authentification IAM automatique avec le connecteur AlloyDB Go. Pour l'activer, remplacez votre fonction RegisterDriver par ce qui suit:

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