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 de IAM automatizada

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 la 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 AlloyDB para Go
• El conector de Python de AlloyDB

Antes de comenzar

1. Habilita la API de AlloyDB Admin.

   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 predefinidos de IAM de AlloyDB.

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

   • roles/alloydb.client

   • roles/serviceusage.serviceUsageConsumer

     Para obtener más información sobre los roles y permisos 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.

Instalación

En el caso de 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>

En el caso de Gradle, puedes instalar el conector de Java de AlloyDB si incluyes lo siguiente en el 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 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 que los usuarios con permisos suficientes se conecten 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 de controladores asíncronos, consulta Uso de controladores asíncronos.

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 AlloyDB para Go 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 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 idiomas de AlloyDB

Java

Para usar el conector de Java de 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);
  }
}

Cómo usar 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 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 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

Cómo usar una IP pública

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

Cómo usar una IP pública

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

Cómo usar 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 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 habilitarlo, reemplaza la función alloydbconn.NewDialer por lo siguiente:

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

Go (database/sql)

Para usar el conector de Go de AlloyDB y 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/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
}

Cómo usar 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 := 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 habilitarlo, reemplaza tu función RegisterDriver por lo siguiente:

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