Conéctate con los conectores de lenguaje de AlloyDB

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

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

Los conectores de lenguaje de 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 lenguaje de AlloyDB, consulta Descripción general de los conectores de lenguaje de AlloyDB.

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

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

Antes de comenzar

1. Habilita la API de AlloyDB.

   Habilita la API

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

   Para obtener más información sobre la creación de una instancia, consulta Crea una instancia principal.

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

3. Configura las siguientes funciones y permisos necesarios para conectarte a una instancia de AlloyDB:

   • roles/alloydb.client

   • roles/serviceusage.serviceUsageConsumer

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

Instala los conectores de lenguaje de AlloyDB

Java

El conector de Java de 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 iniciador de AlloyDB de Spring Boot.

Instalación

Para Maven, puedes instalar el conector de Java de AlloyDB si agregas lo siguiente a 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>

Para Gradle, puedes instalar el conector de Java de AlloyDB si incluyes lo siguiente en 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 a los usuarios con permisos suficientes conectarse a una base de datos de AlloyDB sin tener que incluir IPs en la lista de entidades permitidas de forma manual.

Instalación

Puedes instalar la biblioteca del conector de 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 a los usuarios con permisos suficientes conectarse a una base de datos de AlloyDB sin tener que incluir IPs en la lista de entidades permitidas de forma manual.

Instalación

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

Si usas asyncpg, ejecuta el siguiente comando:

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

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

Instalación

Puedes instalar el conector de 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)

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

Instalación

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

Si usas database/sql, ejecuta el siguiente comando:

go get cloud.google.com/go/alloydbconn

Configura los conectores de lenguaje de AlloyDB

Java

Para usar el conector de Java de AlloyDB para conectarte a tu clúster de AlloyDB, configúralo con los siguientes pasos.

Para ver 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 lenguaje de AlloyDB usan la autenticación integrada. Puedes usar la autenticación automática de IAM con el conector de Java de AlloyDB. Para habilitarla, incluye lo siguiente:

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

Python (pg8000)

Para usar el conector de Python de AlloyDB para conectarte a tu clúster de AlloyDB, configura el conector con los siguientes pasos si usas pg8000.

Para ver 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 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 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 lenguaje de 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 para conectarte a tu clúster de AlloyDB, configura el conector con los siguientes pasos si usas async.

Para ver 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 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 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 lenguaje de 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:

  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 ver 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 tu 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 lenguaje de AlloyDB usan la autenticación integrada. Puedes usar la autenticación automática de IAM con el conector de Go de AlloyDB. Para habilitarla, 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 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 y a identificar problemas de conectividad del cliente. Esta opción es útil para aplicaciones que operan en entornos en los que se restringe la exportación de métricas salientes. Para inhabilitar esta telemetría, proporciona la siguiente opción cuando inicialices un marcador:

  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 ver 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 tu función RegisterDriver por lo siguiente:

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

Autenticación automática de IAM

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

cleanup, err := pgxv5.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 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 y a identificar problemas de conectividad del cliente. Esta opción es útil para aplicaciones que operan en entornos en los que se restringe la exportación de métricas salientes. Para inhabilitar esta telemetría, proporciona la siguiente opción cuando inicialices un marcador:

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