Ligue-se através dos conetores de linguagem do AlloyDB

Os AlloyDB Language Connectors são bibliotecas que oferecem um processo simplificado para estabelecer ligações seguras ao seu cluster. Use o seguinte:

• Ligações mTLS automatizadas
• Suporte de autorização baseada na gestão de identidade e de acesso (IAM)
• Autenticação IAM automatizada

Os conectores de linguagem do AlloyDB não podem fornecer um caminho de rede para um cluster do AlloyDB se já não existir um caminho de rede.

Para mais informações sobre os conetores de linguagem do AlloyDB, consulte a vista geral dos conetores de linguagem do AlloyDB.

Esta página aborda os seguintes conectores de linguagem do AlloyDB:

• O conetor Java do AlloyDB
• O conetor Go do AlloyDB
• O conector Python do AlloyDB

Antes de começar

1. Ative a API AlloyDB.

   Ative a API

2. Crie uma instância do AlloyDB e configure o utilizador predefinido.

   Para mais informações sobre como criar uma instância, consulte o artigo Crie uma instância principal.

   Para mais informações sobre as funções de utilizador, consulte o artigo Funções de IAM do AlloyDB predefinidas.

3. Configure as seguintes funções e autorizações necessárias para estabelecer ligação a uma instância do AlloyDB:

   • roles/alloydb.client

   • roles/serviceusage.serviceUsageConsumer

     Para mais informações sobre as funções e as autorizações necessárias, consulte o artigo Gerir a autenticação de IAM.

Instale os conetores de linguagem do AlloyDB

Java

O conetor Java do AlloyDB é uma biblioteca que fornece autorização e encriptação baseadas na IAM quando se liga a uma instância do AlloyDB. Se estiver a usar o Spring Boot, consulte o Spring Boot AlloyDB starter.

Instalação

Para o Maven, pode instalar o conector Java do AlloyDB adicionando o seguinte ao pom.xml do seu projeto:

<!-- 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 o Gradle, pode instalar o conector Java do AlloyDB incluindo o seguinte no ficheiro gradle.build do seu projeto:

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

O conetor Python do AlloyDB é uma biblioteca que pode ser usada juntamente com um controlador de base de dados para permitir que os utilizadores com autorizações suficientes se liguem a uma base de dados do AlloyDB sem terem de adicionar manualmente IPs à lista de autorizações.

Instalação

Pode instalar a biblioteca AlloyDB Python Connector com pip install.

Se estiver a usar o pg8000, execute o seguinte comando:

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

Python (asyncpg)

O conetor Python do AlloyDB é uma biblioteca que pode ser usada juntamente com um controlador de base de dados para permitir que os utilizadores com autorizações suficientes se liguem a uma base de dados do AlloyDB sem terem de adicionar manualmente IPs à lista de autorizações.

Instalação

Pode instalar a biblioteca AlloyDB Python Connector com pip install.

Se estiver a usar o asyncpg, execute o seguinte comando:

Para o asyncpg, use:

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

Para mais informações sobre a utilização de controladores assíncronos, consulte o artigo Utilização de controladores assíncronos.

Go (pgx)

O conetor AlloyDB Go é um conetor do AlloyDB concebido para utilização com a linguagem Go.

Instalação

Pode instalar o conetor Go do AlloyDB com go get.

Se estiver a usar o pgx, execute o seguinte comando:

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

Go (database/sql)

O conetor AlloyDB Go é um conetor do AlloyDB concebido para utilização com a linguagem Go.

Instalação

Pode instalar o conetor Go do AlloyDB com go get.

Se estiver a usar a base de dados/SQL, execute o seguinte comando:

go get cloud.google.com/go/alloydbconn

Configure os conetores de linguagem do AlloyDB

Java

Para usar o conector Java do AlloyDB para se ligar ao cluster do AlloyDB, configure-o através dos seguintes passos.

Para usar este fragmento no contexto de uma aplicação Web, consulte o README no 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úblico

Se estiver a usar o IP público para estabelecer ligação ao cluster do AlloyDB, inclua o seguinte:

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

Use o Private Service Connect

Se estiver a usar o Private Service Connect para estabelecer ligação à sua instância do AlloyDB, inclua o seguinte:

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

Autenticação IAM automática

Por predefinição, os conetores de linguagem do AlloyDB usam a autenticação incorporada. Pode usar a autenticação IAM automática com o conetor Java do AlloyDB. Para ativar, inclua o seguinte:

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

Python (pg8000)

Para usar o conector Python do AlloyDB para se ligar ao cluster do AlloyDB, configure o conector através dos seguintes passos, se estiver a usar o pg8000.

Para usar este fragmento no contexto de uma aplicação Web, consulte o README no 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úblico

Se estiver a usar o IP público para estabelecer ligação ao cluster do AlloyDB, substitua a função de ligação pelo seguinte:

  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

Use o Private Service Connect

Se estiver a usar o Private Service Connect para estabelecer ligação à sua instância do AlloyDB, inclua o seguinte:

  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

Autenticação IAM automática

Por predefinição, os conetores de linguagem do AlloyDB usam a autenticação incorporada. Pode usar a autenticação IAM automática com o conetor Python do AlloyDB. Para ativar, substitua a função de associação pelo seguinte:

  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 o conector Python do AlloyDB para se ligar ao cluster do AlloyDB, configure o conector através dos seguintes passos, se estiver a usar o async.

Para usar este fragmento no contexto de uma aplicação Web, consulte o README no 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úblico

Se estiver a usar o IP público para estabelecer ligação ao cluster do AlloyDB, substitua a função de ligação pelo seguinte:

  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

Use o Private Service Connect

Se estiver a usar o Private Service Connect para estabelecer ligação à sua instância do AlloyDB, inclua o seguinte:

    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

Autenticação IAM automática

Por predefinição, os conetores de linguagem do AlloyDB usam a autenticação incorporada. Pode usar a autenticação IAM automática com o conetor Python do AlloyDB. Para ativar, substitua a função de associação pelo seguinte:

  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 o conector Go do AlloyDB para se ligar ao cluster do AlloyDB, configure o conector através dos seguintes passos, se estiver a usar o pgx.

Para usar este fragmento no contexto de uma aplicação Web, consulte o README no 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úblico

Se estiver a usar o IP público para estabelecer ligação ao cluster do AlloyDB, substitua a função d.Dial pelo seguinte:

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

Use o Private Service Connect

Se estiver a usar o Private Service Connect para estabelecer ligação à sua instância do AlloyDB, inclua o seguinte:

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

Autenticação IAM automática

Por predefinição, os conetores de linguagem do AlloyDB usam a autenticação incorporada. Pode usar a autenticação IAM automática com o conetor Go do AlloyDB. Para ativar, substitua a função alloydbconn.NewDialer pelo seguinte:

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

Desative a telemetria incorporada

A opção WithOptOutOfBuiltInTelemetry desativa a exportação de métricas internas. Por predefinição, o Marcador comunica as respetivas operações internas ao prefixo da métrica do sistema alloydb.googleapis.com. Estas métricas ajudam o AlloyDB a melhorar o desempenho e a identificar problemas de conetividade do cliente. Esta opção é útil para aplicações que funcionam em ambientes onde a exportação de métricas de saída é restrita. Para desativar esta telemetria, forneça a seguinte opção ao inicializar um Dialer:

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

Go (database/sql)

Para usar o AlloyDB Go Connector para se ligar ao seu cluster do AlloyDB, configure o conector através dos seguintes passos, se estiver a usar o database/sql.

Para usar este fragmento no contexto de uma aplicação Web, consulte o README no 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úblico

Se estiver a usar o IP público para estabelecer ligação ao cluster do AlloyDB, substitua a função RegisterDriver pelo seguinte:

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

Use o Private Service Connect

Se estiver a usar o Private Service Connect para estabelecer ligação à sua instância do AlloyDB, inclua o seguinte:

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

Autenticação IAM automática

Por predefinição, os conetores de linguagem do AlloyDB usam a autenticação incorporada. Pode usar a autenticação IAM automática com o conetor Go do AlloyDB. Para ativar, substitua a função RegisterDriver pela seguinte:

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

Desative a telemetria incorporada

A opção WithOptOutOfBuiltInTelemetry desativa a exportação de métricas internas. Por predefinição, o Marcador comunica as respetivas operações internas ao prefixo da métrica do sistema alloydb.googleapis.com. Estas métricas ajudam o AlloyDB a melhorar o desempenho e a identificar problemas de conetividade do cliente. Esta opção é útil para aplicações que funcionam em ambientes onde a exportação de métricas de saída é restrita. Para desativar esta telemetria, forneça a seguinte opção ao inicializar um Dialer:

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