Os conectores de linguagem do AlloyDB são bibliotecas que oferecem um processo simplificado para estabelecer conexões seguras com seu cluster. Use o seguinte:
- Conexões mTLS automatizadas
- Suporte à autorização baseada 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 ele ainda não existir.
Para mais informações sobre os conectores de linguagem do AlloyDB, consulte a visão geral dos conectores de linguagem do AlloyDB.
Nesta página, você vai conhecer os seguintes conectores de linguagem do AlloyDB:
- O conector Java do AlloyDB
- O conector Go do AlloyDB
- O conector Python do AlloyDB
Antes de começar
Ative a API AlloyDB Admin.
Crie uma instância do AlloyDB e configure o usuário padrão.
Para mais informações sobre como criar uma instância, consulte Criar uma instância principal.
Para mais informações sobre os papéis do usuário, consulte Papéis predefinidos do IAM do AlloyDB.
Configure os seguintes papéis e permissões necessários para se conectar a uma instância do AlloyDB:
roles/alloydb.client
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.
Instale 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 Starter do Spring Boot AlloyDB.
Instalação
Para o Maven, instale 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, instale o conector Java do AlloyDB incluindo o seguinte
no gradle.build
do 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 conector do AlloyDB para Python é uma biblioteca que pode ser usada com um driver de banco de dados para permitir que usuários com permissões suficientes se conectem a um banco de dados do AlloyDB sem precisar incluir IPs manualmente na lista de permissões.
Instalação
É possível instalar a biblioteca do conector Python do AlloyDB com pip install
.
Se você estiver usando o pg8000, execute o seguinte comando:
pip install "google-cloud-alloydb-connector[pg8000]" sqlalchemy
Python (asyncpg)
O conector do AlloyDB para Python é uma biblioteca que pode ser usada com um driver de banco de dados para permitir que usuários com permissões suficientes se conectem a um banco de dados do AlloyDB sem precisar incluir IPs manualmente na lista de permissões.
Instalação
É possível instalar a biblioteca do conector Python do AlloyDB com pip install
.
Se você estiver usando o asyncpg, execute o seguinte comando:
Para asyncpg, use:
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 AlloyDB Go Connector com go get
.
Se você estiver usando pgx, execute o seguinte comando:
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 AlloyDB Go Connector 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 e se conectar ao cluster do AlloyDB, configure-o seguindo estas etapas.
Para usar esse snippet no contexto de um aplicativo da Web, consulte o README no GitHub.
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 autenticação integrada. É possível usar a autenticação automática do IAM com o conector Java do AlloyDB. Para ativar, inclua o seguinte:
config.addDataSourceProperty("alloydbEnableIAMAuth", "true");
Python (pg8000)
Para usar o conector Python do AlloyDB e se conectar ao cluster do AlloyDB, configure o conector seguindo estas etapas, se você estiver usando pg8000
.
Para usar esse snippet no contexto de um aplicativo da Web, consulte o README no GitHub.
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 autenticação integrada. Você pode usar a autenticação automática do IAM com o conector Python do AlloyDB. Para ativar, 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 Python do AlloyDB e se conectar ao cluster do AlloyDB, configure o conector seguindo estas etapas, se você estiver usando async
.
Para usar esse snippet no contexto de um aplicativo da Web, consulte o README no GitHub.
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 autenticação integrada. É possível usar a autenticação automática do IAM com o conector Python do AlloyDB. 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 Go do AlloyDB e se conectar ao cluster do AlloyDB, configure o conector seguindo estas etapas, se você estiver usando pgx
.
Para usar esse snippet no contexto de um aplicativo da Web, consulte o README no GitHub.
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 autenticação integrada.
É possível usar a autenticação automática do IAM com o conector Go do AlloyDB. Para ativar, 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 sobre as operações internas ao prefixo de métrica do sistema alloydb.googleapis.com
. Essas métricas ajudam o AlloyDB a melhorar a performance 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 e se conectar ao cluster do AlloyDB, configure o conector seguindo estas etapas, se você estiver usando database/sql
.
Para usar esse snippet no contexto de um aplicativo da Web, consulte o README no GitHub.
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 := pgxv5.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 := pgxv5.RegisterDriver(
"alloydb",
alloydbconn.WithDefaultDialOptions(alloydbconn.WithPSC())
)
Autenticação automática do IAM
Por padrão, os conectores de linguagem do AlloyDB usam autenticação integrada.
É possível usar a autenticação automática do IAM com o conector Go do AlloyDB. Para ativar, substitua
a função RegisterDriver
pelo seguinte:
cleanup, err := pgxv5.RegisterDriver(
"alloydb",
alloydbconn.WithIAMAuthN()
)
Desativar a telemetria integrada
A opção WithOptOutOfBuiltInTelemetry
desativa a exportação de métricas internas.
Por padrão, o discador informa sobre as operações internas ao prefixo de métrica do sistema alloydb.googleapis.com
. Essas métricas ajudam o AlloyDB a melhorar a performance 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:
cleanup, err := pgxv5.RegisterDriver(
"alloydb",
alloydbconn.WithOptOutOfBuiltInTelemetry(),
)