O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Conectar usando os conectores de linguagem do AlloyDB

Para simplificar o estabelecimento de conexões seguras do seu aplicativo com um cluster do AlloyDB para PostgreSQL, use os conectores de linguagem do AlloyDB. Essas bibliotecas de cliente oferecem os seguintes recursos:

Conexões mTLS automatizadas
Suporte à autorização com base no Identity and Access Management (IAM)
Autenticação automatizada do IAM

Os conectores de linguagem do AlloyDB não podem fornecer um caminho de rede para um cluster do AlloyDB se um caminho de rede ainda não estiver presente.

Para mais informações sobre os conectores de linguagem do AlloyDB, consulte Visão geral dos conectores de linguagem do AlloyDB.

Nesta página, você conhecerá os seguintes conectores de linguagem do AlloyDB:

O conector Java do AlloyDB
O conector do AlloyDB para Go
O conector do AlloyDB para Python

Antes de começar

Ative a API AlloyDB.

Ativar a API
Criar uma instância do AlloyDB e configurar o usuário padrão.

Para mais informações sobre como criar uma instância, consulte Criar uma instância primária.

Para mais informações sobre papéis do usuário, consulte Papéis predefinidos do IAM do AlloyDB.
Configure os seguintes papéis do IAM necessários para se conectar a uma instância do AlloyDB:
- Cliente do AlloyDB (roles/alloydb.client)
- Consumidor do Service Usage (roles/serviceusage.serviceUsageConsumer)
  
  Para mais informações sobre quais papéis e permissões são necessários, consulte Gerenciar a autenticação do IAM.

Instalar os conectores de linguagem do AlloyDB

Java

O conector Java do AlloyDB é uma biblioteca que fornece autorização e criptografia baseadas em IAM ao se conectar a uma instância do AlloyDB. Se você estiver usando o Spring Boot, consulte o Spring Boot AlloyDB starter.

Instalação

Para o Maven, é possível instalar o conector Java do AlloyDB adicionando o seguinte ao pom.xml do projeto:

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

Para o Gradle, é possível instalar o conector Java do AlloyDB incluindo o seguinte no build.gradle do seu projeto:

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

O conector do AlloyDB para Python funciona com os drivers de banco de dados pg8000 (síncronos) e asyncpg (assíncronos) para permitir que principais com permissões suficientes se conectem a um banco de dados do AlloyDB sem incluir manualmente endereços IP na lista de permissões.

Instalação

É possível instalar a biblioteca do conector do AlloyDB para Python com pip install.

Se você estiver usando pg8000, execute o seguinte comando:

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

Python (asyncpg)

Instalação

É possível instalar a biblioteca do conector do AlloyDB para Python com pip install.

Se você estiver usando asyncpg, execute o seguinte comando:

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

Para mais informações sobre o uso do driver assíncrono, consulte Uso do driver assíncrono.

Go (pgx)

O conector do AlloyDB para Go é projetado para uso com essa linguagem.

Instalação

É possível instalar o conector do AlloyDB para Go com go get.

Se você estiver usando pgx, execute os seguintes comandos:

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

Go (database/sql)

O conector do AlloyDB para Go é projetado para uso com essa linguagem.

Instalação

É possível instalar o conector do AlloyDB para Go com go get.

Se você estiver usando database/sql, execute o seguinte comando:

go get cloud.google.com/go/alloydbconn

Configurar os conectores de linguagem do AlloyDB

Java

Para usar o conector Java do AlloyDB para se conectar ao cluster do AlloyDB, configure-o seguindo as etapas abaixo.

Para usar esse snippet no contexto de um aplicativo da 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 você estiver usando um IP público para se conectar ao cluster do AlloyDB, inclua o seguinte:

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

Usar o Private Service Connect

Se você estiver usando o Private Service Connect para se conectar à instância do AlloyDB, inclua o seguinte:

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

Autenticação automática do IAM

Por padrão, os conectores de linguagem do AlloyDB usam a autenticação integrada. É possível usar a autenticação automática do IAM com o conector Java do AlloyDB. Para ativá-lo, inclua o seguinte:

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

Python (pg8000)

Para usar o conector do AlloyDB para Python para se conectar ao cluster do AlloyDB, configure o conector seguindo as etapas abaixo, se estiver usando pg8000.

Para usar esse snippet no contexto de um aplicativo da 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 você estiver usando um IP público para se conectar ao cluster do AlloyDB, substitua a função de conexã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

Usar o Private Service Connect

Se você estiver usando o Private Service Connect para se conectar à 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 automática do IAM

Por padrão, os conectores de linguagem do AlloyDB usam a autenticação integrada. É possível usar a autenticação automática do IAM com o conector do Python para AlloyDB. Para ativá-lo, substitua a função de conexã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 do AlloyDB para Python para se conectar ao cluster do AlloyDB, configure o conector seguindo as etapas abaixo, se estiver usando o asyncpg.

Para usar esse snippet no contexto de um aplicativo da 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 você estiver usando um IP público para se conectar ao cluster do AlloyDB, substitua a função de conexã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

Usar o Private Service Connect

Se você estiver usando o Private Service Connect para se conectar à 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 automática do IAM

Por padrão, os conectores de linguagem do AlloyDB usam a autenticação integrada. É possível usar a autenticação automática do IAM com o conector do AlloyDB para Python. Para ativar, substitua a função de conexã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 do AlloyDB para Go para se conectar ao cluster do AlloyDB, configure o conector seguindo as etapas abaixo, se estiver usando o pgx.

Para usar esse snippet no contexto de um aplicativo da 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 você estiver usando um IP público para se conectar ao cluster do AlloyDB, substitua a função d.Dial pelo seguinte:

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

Usar o Private Service Connect

Se você estiver usando o Private Service Connect para se conectar à instância do AlloyDB, inclua o seguinte:

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

Autenticação automática do IAM

Por padrão, os conectores de linguagem do AlloyDB usam a autenticação integrada. É possível usar a autenticação automática do IAM com o conector do AlloyDB para Go. Para ativá-la, substitua a função alloydbconn.NewDialer pelo seguinte:

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

Desativar a telemetria integrada

A opção WithOptOutOfBuiltInTelemetry desativa a exportação de métricas internas. Por padrão, o discador informa as operações internas ao prefixo de métrica do sistema alloydb.googleapis.com. Essas métricas ajudam o AlloyDB a melhorar o desempenho e identificar problemas de conectividade do cliente. Essa opção é útil para aplicativos que operam em ambientes em que a exportação de métricas de saída é restrita. Para desativar essa telemetria, forneça a seguinte opção ao inicializar um discador:

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

Go (database/sql)

Para usar o conector do AlloyDB para Go para se conectar ao cluster do AlloyDB, configure o conector seguindo as etapas abaixo, se estiver usando o database/sql.

Para usar esse snippet no contexto de um aplicativo da Web, consulte o README no 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
}

Usar IP público

Se você estiver usando um IP público para se conectar ao cluster do AlloyDB, substitua a função RegisterDriver pelo seguinte:

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

Usar o Private Service Connect

Se você estiver usando o Private Service Connect para se conectar à instância do AlloyDB, inclua o seguinte:

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

Autenticação automática do IAM

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

Desativar a telemetria integrada

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

Conectar usando os conectores de linguagem do AlloyDB Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Antes de começar

Instalar os conectores de linguagem do AlloyDB

Java

Instalação

Python (pg8000)

Instalação

Python (asyncpg)

Instalação

Go (pgx)

Instalação

Go (database/sql)

Instalação

Configurar os conectores de linguagem do AlloyDB

Java

Python (pg8000)

Python (asyncpg)

Go (pgx)

Go (database/sql)

Conectar usando os conectores de linguagem do AlloyDB