Conectarse mediante los conectores de lenguaje de AlloyDB

Los conectores de lenguaje de AlloyDB son bibliotecas que proporcionan un proceso simplificado para establecer conexiones seguras con tu clúster. Para ello, usan lo siguiente:

  • Conexiones mTLS automatizadas
  • Compatibilidad con la autorización basada en Gestión de Identidades y Accesos (IAM)
  • Autenticación de gestión de identidades y accesos automatizada

AlloyDB Language Connectors no puede proporcionar una ruta de red a un clúster de AlloyDB si no hay ninguna.

Para obtener más información sobre los conectores de lenguaje de AlloyDB, consulta la información general sobre los conectores de lenguaje de AlloyDB.

En esta página se describen los siguientes conectores de lenguaje de AlloyDB:

  • Conector Java de AlloyDB
  • Conector Go de AlloyDB
  • Conector Python de AlloyDB

Antes de empezar

  1. Habilita la API AlloyDB.

    Habilitar la API

  2. Crea una instancia de AlloyDB y configura el usuario predeterminado.

    Para obtener más información sobre cómo crear una instancia, consulta Crear una instancia principal.

    Para obtener más información sobre los roles de usuario, consulta Roles de gestión de identidades y accesos predefinidos de AlloyDB.

  3. Configure los siguientes roles y permisos necesarios para conectarse a una instancia de AlloyDB:

Instalar los conectores de lenguaje de AlloyDB

Java

AlloyDB Java Connector es una biblioteca que proporciona autorización y cifrado basados en IAM al conectarse a una instancia de AlloyDB. Si usas Spring Boot, consulta el starter de Spring Boot AlloyDB.

Instalación

En Maven, puedes instalar el conector Java de AlloyDB añadiendo lo siguiente al archivo pom.xml de tu proyecto:

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

En Gradle, puedes instalar el conector Java de AlloyDB incluyendo lo siguiente en el archivo gradle.build de tu proyecto:

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

El conector de Python de AlloyDB es una biblioteca que se puede usar junto con un controlador de base de datos para permitir que los usuarios con permisos suficientes se conecten a una base de datos de AlloyDB sin tener que incluir manualmente IPs en una lista de permitidas.

Instalación

Puedes instalar la biblioteca del conector Python de AlloyDB con pip install.

Si usas pg8000, ejecuta el siguiente comando:

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

Python (asyncpg)

El conector de Python de AlloyDB es una biblioteca que se puede usar junto con un controlador de base de datos para permitir que los usuarios con permisos suficientes se conecten a una base de datos de AlloyDB sin tener que incluir manualmente IPs en una lista de permitidas.

Instalación

Puedes instalar la biblioteca del conector Python de AlloyDB con pip install.

Si usas asyncpg, ejecuta el siguiente comando:

En el caso de asyncpg, usa lo siguiente:

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

Para obtener más información sobre el uso del controlador asíncrono, consulta Uso del controlador asíncrono.

Go (pgx)

AlloyDB Go Connector es un conector de AlloyDB diseñado para usarse con el lenguaje Go.

Instalación

Puedes instalar el conector Go de AlloyDB con go get.

Si usas pgx, ejecuta el siguiente comando:

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

Go (database/sql)

AlloyDB Go Connector es un conector de AlloyDB diseñado para usarse con el lenguaje Go.

Instalación

Puedes instalar el conector Go de AlloyDB con go get.

Si usas database/sql, ejecuta el siguiente comando:

go get cloud.google.com/go/alloydbconn

Configurar los conectores de idiomas de AlloyDB

Java

Para usar el conector Java de AlloyDB y conectarte a tu clúster de AlloyDB, configúralo siguiendo estos pasos.

Para usar este fragmento en el contexto de una aplicación web, consulta el archivo README en 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);
  }
}

Usar IP pública

Si usas una IP pública para conectarte a tu clúster de AlloyDB, incluye lo siguiente:

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

Usar Private Service Connect

Si usas Private Service Connect para conectarte a tu instancia de AlloyDB, incluye lo siguiente:

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

Autenticación automática de gestión de identidades y accesos

De forma predeterminada, los conectores de lenguaje de AlloyDB usan la autenticación integrada. Puedes usar la autenticación automática de gestión de identidades y accesos con el conector Java de AlloyDB. Para habilitarlo, incluye lo siguiente:

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

Python (pg8000)

Para usar el conector de Python de AlloyDB y conectarte a tu clúster de AlloyDB, configura el conector siguiendo estos pasos si usas pg8000.

Para usar este fragmento en el contexto de una aplicación web, consulta el archivo README en 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

Usar IP pública

Si usas una IP pública para conectarte a tu clúster de AlloyDB, sustituye tu función de conexión por la siguiente:

  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

Usar Private Service Connect

Si usas Private Service Connect para conectarte a tu instancia de AlloyDB, incluye lo siguiente:

  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

Autenticación automática de gestión de identidades y accesos

De forma predeterminada, los conectores de lenguaje de AlloyDB usan la autenticación integrada. Puedes usar la autenticación automática de gestión de identidades y accesos con el conector Python de AlloyDB. Para habilitarlo, sustituye tu función de conexión por la siguiente:

  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)

Para usar el conector de Python de AlloyDB y conectarte a tu clúster de AlloyDB, configura el conector siguiendo estos pasos si usas async.

Para usar este fragmento en el contexto de una aplicación web, consulta el archivo README en 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

Usar IP pública

Si usas una IP pública para conectarte a tu clúster de AlloyDB, sustituye tu función de conexión por la siguiente:

  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

Usar Private Service Connect

Si usas Private Service Connect para conectarte a tu instancia de AlloyDB, incluye lo siguiente:

    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

Autenticación automática de gestión de identidades y accesos

De forma predeterminada, los conectores de lenguaje de AlloyDB usan la autenticación integrada. Puedes usar la autenticación automática de gestión de identidades y accesos con el conector Python de AlloyDB. Para habilitarlo, sustituye tu función de conexión por la siguiente:

  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)

Para usar el conector Go de AlloyDB y conectarte a tu clúster de AlloyDB, configura el conector siguiendo estos pasos si usas pgx.

Para usar este fragmento en el contexto de una aplicación web, consulta el archivo README en 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
}

Usar IP pública

Si usas una IP pública para conectarte a tu clúster de AlloyDB, sustituye tu función d.Dial por la siguiente:

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

Usar Private Service Connect

Si usas Private Service Connect para conectarte a tu instancia de AlloyDB, incluye lo siguiente:

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

Autenticación automática de gestión de identidades y accesos

De forma predeterminada, los conectores de lenguaje de AlloyDB usan la autenticación integrada. Puedes usar la autenticación automática de gestión de identidades y accesos con el conector Go de AlloyDB. Para habilitarla, sustituye la función alloydbconn.NewDialer por lo siguiente:

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

Inhabilitar la telemetría integrada

La opción WithOptOutOfBuiltInTelemetry inhabilita la exportación de métricas internas. De forma predeterminada, el marcador informa sobre sus operaciones internas al prefijo de métrica del sistema alloydb.googleapis.com. Estas métricas ayudan a AlloyDB a mejorar el rendimiento e identificar problemas de conectividad de los clientes. Esta opción es útil para las aplicaciones que funcionan en entornos en los que se restringe la exportación de métricas salientes. Para inhabilitar esta telemetría, proporciona la siguiente opción al inicializar un Dialer:

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

Go (database/sql)

Para usar el conector Go de AlloyDB y conectarte a tu clúster de AlloyDB, configura el conector siguiendo estos pasos si usas database/sql.

Para usar este fragmento en el contexto de una aplicación web, consulta el archivo README en 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
}

Usar IP pública

Si usas una IP pública para conectarte a tu clúster de AlloyDB, sustituye tu función RegisterDriver por la siguiente:

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

Usar Private Service Connect

Si usas Private Service Connect para conectarte a tu instancia de AlloyDB, incluye lo siguiente:

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

Autenticación automática de gestión de identidades y accesos

De forma predeterminada, los conectores de lenguaje de AlloyDB usan la autenticación integrada. Puedes usar la autenticación automática de gestión de identidades y accesos con el conector Go de AlloyDB. Para habilitarla, sustituye tu función RegisterDriver por la siguiente:

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

Inhabilitar la telemetría integrada

La opción WithOptOutOfBuiltInTelemetry inhabilita la exportación de métricas internas. De forma predeterminada, el marcador informa sobre sus operaciones internas al prefijo de métrica del sistema alloydb.googleapis.com. Estas métricas ayudan a AlloyDB a mejorar el rendimiento e identificar problemas de conectividad de los clientes. Esta opción es útil para las aplicaciones que funcionan en entornos en los que se restringe la exportación de métricas salientes. Para inhabilitar esta telemetría, proporciona la siguiente opción al inicializar un Dialer:

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