Conéctate con los conectores de lenguaje de AlloyDB

Para simplificar el establecimiento de conexiones seguras desde tu aplicación a un clúster de AlloyDB para PostgreSQL, puedes usar los conectores de lenguajes para AlloyDB. Estas bibliotecas cliente proporcionan las siguientes capacidades:

• Conexiones mTLS automatizadas
• Compatibilidad con la autorización basada en Identity and Access Management (IAM)
• Autenticación de IAM automatizada

Los conectores de lenguajes para AlloyDB no pueden proporcionar una ruta de red a un clúster de AlloyDB si aún no hay una.

Para obtener más información sobre los conectores de lenguajes para AlloyDB, consulta Descripción general de los conectores de lenguajes para AlloyDB.

En esta página, se analizan los siguientes conectores de lenguajes para AlloyDB:

• El conector de Java para AlloyDB
• Conector de Go para AlloyDB
• El conector de Python para AlloyDB

Antes de comenzar

1. Habilita la API de 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 Crea una instancia principal.

   Para obtener más información sobre los roles de usuario, consulta Roles de IAM predefinidos de AlloyDB.

3. Configura los siguientes roles de IAM necesarios para conectarte a una instancia de AlloyDB:

   • Cliente de AlloyDB (roles/alloydb.client)

   • Consumidor de Service Usage (roles/serviceusage.serviceUsageConsumer)

     Para obtener más información sobre qué roles y permisos se requieren, consulta Administra la autenticación de IAM.

Instala los conectores de lenguajes para AlloyDB

Java

El conector de Java para AlloyDB es una biblioteca que proporciona encriptación y autorización basadas en IAM cuando se conecta a una instancia de AlloyDB. Si usas Spring Boot, consulta el inicio de AlloyDB para Spring Boot.

Instalación

En el caso de Maven, puedes instalar el conector de Java para AlloyDB agregando 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>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>

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

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

El conector de AlloyDB para Python funciona con los controladores de base de datos pg8000 (síncrono) y asyncpg (asíncrono) para permitir que las principales con permisos suficientes se conecten a una base de datos de AlloyDB sin incluir direcciones IP en la lista de entidades permitidas de forma manual.

Instalación

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

Si usas pg8000, ejecuta el siguiente comando:

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

Python (asyncpg)

El conector de AlloyDB para Python funciona con los controladores de base de datos pg8000 (síncrono) y asyncpg (asíncrono) para permitir que las principales con permisos suficientes se conecten a una base de datos de AlloyDB sin incluir direcciones IP en la lista de entidades permitidas de forma manual.

Instalación

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

Si usas asyncpg, ejecuta el siguiente comando:

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)

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

Instalación

Puedes instalar el conector de AlloyDB para Go con go get.

Si usas pgx, ejecuta los siguientes comandos:

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

Go (database/sql)

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

Instalación

Puedes instalar el conector de AlloyDB para Go con go get.

Si usas database/sql, ejecuta el siguiente comando:

go get cloud.google.com/go/alloydbconn

Configura los conectores de lenguajes para AlloyDB

Java

Para usar el conector de Java para AlloyDB y conectarte a tu clúster de AlloyDB, configúralo con los siguientes 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);
  }
}

Usa una IP pública

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

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

Usa 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 IAM

De forma predeterminada, los conectores de lenguajes para AlloyDB usan la autenticación integrada. Puedes usar la autenticación automática de IAM con el conector de Java para 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 con los siguientes 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

Usa una IP pública

Si usas una IP pública para conectarte a tu clúster de AlloyDB, reemplaza 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

Usa 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 IAM

De forma predeterminada, los conectores de lenguajes para AlloyDB usan la autenticación integrada. Puedes usar la autenticación automática de IAM con el conector de Python de AlloyDB. Para habilitarla, reemplaza tu función de conexión por lo 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 con los siguientes pasos si usas asyncpg.

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

Usa una IP pública

Si usas una IP pública para conectarte a tu clúster de AlloyDB, reemplaza 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

Usa 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 IAM

De forma predeterminada, los conectores de lenguajes para AlloyDB usan la autenticación integrada. Puedes usar la autenticación automática de IAM con el conector de Python de AlloyDB. Para habilitarlo, reemplaza tu función de conexión por lo 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 de Go de AlloyDB para conectarte a tu clúster de AlloyDB, configura el conector con los siguientes 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
}

Usa una IP pública

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

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

Usa 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 IAM

De forma predeterminada, los conectores de lenguajes para AlloyDB usan la autenticación integrada. Puedes usar la autenticación automática de IAM con el conector de Go para AlloyDB. Para habilitarlo, reemplaza la función alloydbconn.NewDialer por lo siguiente:

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

Inhabilita la telemetría integrada

La opción WithOptOutOfBuiltInTelemetry inhabilita la exportación de métricas internas. De forma predeterminada, el Dialer 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 y a identificar problemas de conectividad del cliente. Esta opción es útil para las aplicaciones que operan en entornos en los que la exportación de métricas salientes está restringida. Para inhabilitar esta telemetría, proporciona la siguiente opción cuando inicialices un Dialer:

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

Go (database/sql)

Para usar el conector de Go de AlloyDB para conectarte a tu clúster de AlloyDB, configura el conector con los siguientes 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/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
}

Usa una IP pública

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

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

Usa Private Service Connect

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

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

Autenticación automática de IAM

De forma predeterminada, los conectores de lenguajes para AlloyDB usan la autenticación integrada. Puedes usar la autenticación automática de IAM con el conector de AlloyDB para Go. Para habilitarla, reemplaza la función RegisterDriver por lo siguiente:

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

Inhabilita la telemetría integrada

La opción WithOptOutOfBuiltInTelemetry inhabilita la exportación de métricas internas. De forma predeterminada, el Dialer 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 y a identificar problemas de conectividad del cliente. Esta opción es útil para las aplicaciones que operan en entornos en los que la exportación de métricas salientes está restringida. Para inhabilitar esta telemetría, proporciona la siguiente opción cuando inicialices un Dialer:

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