# Conectores para o Aurora DSQL
O Aurora DSQL oferece conectores especializados que estendem os drivers de banco de dados existentes para que a autenticação do IAM e a integração com serviços da AWS sejam consistentes. Esses conectores são projetados para funcionar com linguagens e frameworks de programação conhecidos, mantendo a compatibilidade com os fluxos de trabalho existentes do PostgreSQL.
Conectores adicionais estão planejados para versões futuras. Para ver as informações mais recentes sobre a disponibilidade de conectores, consulte o [repositório de exemplos do Aurora DSQL](https://github.com/aws-samples/aurora-dsql-samples).
# Conectar-se a clusters do Aurora DSQL com um conector JDBC
O [conector do Aurora DSQL para JDBC](https://github.com/awslabs/aurora-dsql-connectors/tree/main/java/jdbc) foi projetado como um plug-in de autenticação que estende a funcionalidade do driver JDBC do PostgreSQL para permitir que as aplicações se autentiquem com o Aurora DSQL usando credenciais do IAM. O conector não se conecta diretamente ao banco de dados, mas oferece uma autenticação perfeita do IAM no driver JDBC subjacente do PostgreSQL.
O conector do Aurora DSQL para JDBC foi criado para funcionar com o [driver JDBC do PostgreSQL](https://github.com/pgjdbc/pgjdbc) e oferece uma integração perfeita com os requisitos de autenticação do IAM do Aurora DSQL.
Em conjunto com o driver JDBC do PostgreSQL, o conector do Aurora DSQL para JDBC permite a autenticação baseada no IAM para o Aurora DSQL. Ele possibilita uma profunda integração com serviços de autenticação da AWS, como o [AWS Identity and Access Management](https://aws.amazon.com/iam/) (IAM).
## Sobre o conector
O Aurora DSQL é um serviço de banco de dados SQL distribuído que oferece alta disponibilidade e escalabilidade para aplicações compatíveis com o PostgreSQL. O Aurora DSQL exige autenticação baseada no IAM com tokens de tempo limitado para os quais os drivers JDBC não oferecem suporte nativo.
A ideia principal por trás do conector do Aurora DSQL para JDBC é adicionar uma camada de autenticação sobre o driver JDBC do PostgreSQL que gerencie a geração de tokens do IAM, permitindo que os usuários se conectem ao Aurora DSQL sem alterar seus fluxos de trabalho JDBC existentes.
### O que é a autenticação do Aurora DSQL?
Na autenticação do Aurora DSQL, a **autenticação** envolve:
+ **Autenticação do IAM**: todas as conexões usam autenticação baseada no IAM com tokens de tempo limitado.
+ **Geração de tokens**: os tokens de autenticação são gerados usando credenciais da AWS e têm vida útil configurável
O conector do Aurora DSQL para JDBC foi projetado para entender esses requisitos e gerar tokens de autenticação do IAM automaticamente ao estabelecer conexões.
### Benefícios do conector do Aurora DSQL para JDBC
Embora o Aurora DSQL ofereça uma interface compatível com o PostgreSQL, os drivers existentes do PostgreSQL no momento não atendem aos requisitos de autenticação do IAM do Aurora DSQL. O conector do Aurora DSQL para JDBC permite que os clientes continuem usando seus fluxos de trabalho existentes do PostgreSQL e, ao mesmo tempo, habilitem a autenticação do IAM por meio de:
+ **Geração automática de tokens**: os tokens do IAM são gerados automaticamente usando credenciais da AWS.
+ **Integração perfeita**: funciona com padrões de conexão JDBC existentes.
+ **Suporte a credenciais da AWS**: aceita vários provedores de credenciais da AWS (padrão, baseado em perfil etc.)
### Usar o conector do Aurora DSQL para JDBC com agrupamento de conexões
O conector do Aurora DSQL para JDBC funciona com bibliotecas de agrupamento de conexões, como a HikariCP. O conector gerencia a geração de tokens do IAM durante o estabelecimento da conexão, permitindo que os grupos de conexões operem normalmente.
## Atributos principais
Geração automática de tokens
Os tokens do IAM são gerados automaticamente usando credenciais da AWS.
Integração perfeita
Funciona com padrões de conexão JDBC existentes sem exigir alterações no fluxo de trabalho.
Suporte a credenciais da AWS
Aceita vários provedores de credenciais da AWS (padrão, baseado em perfil etc.).
Compatibilidade com o agrupamento de conexões
Funciona perfeitamente com bibliotecas de agrupamento de conexões, como a HikariCP.
## Pré-requisitos
Antes de começar, você deve cumprir os seguintes pré-requisitos:
+ [Criar um cluster no Aurora DSQL](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/getting-started.html).
+ Instalar o Java Development Kit (JDK). Ter a versão 17 ou posterior.
+ Configurar as permissões apropriadas do IAM para permitir que sua aplicação se conecte ao Aurora DSQL.
+ Credenciais da AWS configuradas (por meio da AWS CLI, de variáveis de ambiente ou perfis do IAM).
## Usar o conector do Aurora DSQL para JDBC
Para usar o conector do Aurora DSQL para JDBC em sua aplicação Java, siga estas etapas:
1. Adicione as seguintes dependências ao seu projeto Maven:
```
software.amazon.dsql
aurora-dsql-jdbc-connector
1.0.0
```
Para projetos Gradle, adicione esta dependência:
```
implementation("software.amazon.dsql:aurora-dsql-jdbc-connector:1.0.0")
```
1. Crie uma conexão básica com seu cluster do Aurora DSQL usando o formato de conector da AWS do DSQL PostgreSQL:
```
import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.ResultSet;
import java.sql.SQLException;
import java.sql.Statement;
public class DsqlJdbcConnectorExample {
public static void main(String[] args) {
// Using AWS DSQL PostgreSQL Connector prefix
String jdbcUrl = "jdbc:aws-dsql:postgresql://your-cluster.dsql.us-east-1.on.aws/postgres?user=admin";
try (Connection connection = DriverManager.getConnection(jdbcUrl)) {
// Use the connection
try (Statement statement = connection.createStatement()) {
// Create a table
statement.execute("CREATE TABLE IF NOT EXISTS test_table (id UUID PRIMARY KEY DEFAULT gen_random_uuid(), name VARCHAR(100))");
// Insert data
statement.execute("INSERT INTO test_table (name) VALUES ('Test Name')");
// Query data
try (ResultSet resultSet = statement.executeQuery("SELECT * FROM test_table")) {
while (resultSet.next()) {
System.out.println("ID: " + resultSet.getInt("id") + ", Name: " + resultSet.getString("name"));
}
}
}
} catch (SQLException e) {
e.printStackTrace();
}
}
}
```
### Propriedades de configuração
O conector do Aurora DSQL para JDBC comporta as seguintes propriedades de conexão:
usuário
Determina o usuário para a conexão e o método de geração de tokens usado. Exemplo: `admin`
token-duration-secs
Duração em segundos para a validade do token. Para ter mais informações sobre limites de token, consulte [For more information on token limits, see Generating an authentication token in Amazon Aurora DSQL](SECTION_authentication-token.md).
perfil
Usado para instanciar um ProfileCredentialsProvider para geração de tokens com o nome de perfil fornecido.
região
Região da AWS para conexões do Aurora DSQL. Ela é opcional. Quando fornecida, substituirá a região extraída do URL.
banco de dados
O nome do banco de dados ao qual se conectar. O padrão é `postgres`.
### Registro em log
Ative o registro em log para solucionar qualquer problema que você possa enfrentar ao usar o conector JDBC do Aurora DSQL.
O conector usa o sistema de registro em log integrado (java.util.logging) do Java. Você pode configurar os níveis de registro em log criando um arquivo `logging.properties`:
```
# Set root logger level to INFO for clean output
.level = INFO
# Show Aurora DSQL Connector for JDBC FINE logs for detailed debugging
software.amazon.dsql.level = FINE
# Console handler configuration
handlers = java.util.logging.ConsoleHandler
java.util.logging.ConsoleHandler.level = FINE
java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter
# Detailed formatter pattern with timestamp and logger name
java.util.logging.SimpleFormatter.format = %1$tH:%1$tM:%1$tS.%1$tL [%4$s] %3$s - %5$s%n
```
### Exemplos
Para ver exemplos e casos de uso mais abrangentes, consulte o [repositório do conector do Aurora DSQL para JDBC](https://github.com/awslabs/aurora-dsql-connectors/tree/main/java/jdbc/examples).
# Conector do Aurora DSQL para Python
O [conector do Aurora DSQL para Python](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector) integra a autenticação do IAM para conectar aplicações Python aos clusters do Amazon Aurora DSQL. Internamente, ele utiliza bibliotecas de cliente [psycopg](https://github.com/psycopg/psycopg), [psycopg2](https://github.com/psycopg/psycopg2) e [asyncpg](https://github.com/MagicStack/asyncpg).
O conector do Aurora DSQL para Python foi projetado como um plug-in de autenticação que estende a funcionalidade das bibliotecas de cliente psycopg, psycopg2 e asyncpg para permitir que as aplicações se autentiquem com o Amazon Aurora DSQL usando credenciais do IAM. O conector não se conecta diretamente ao banco de dados, mas oferece uma autenticação perfeita do IAM nas bibliotecas de cliente subjacentes.
## Sobre o conector
O Amazon Aurora DSQL é um serviço de banco de dados SQL distribuído que oferece alta disponibilidade e escalabilidade para aplicações compatíveis com o PostgreSQL. O Aurora DSQL exige autenticação baseada no IAM com tokens de tempo limitado para os quais as bibliotecas do Python existentes não oferecem suporte nativo.
A ideia por trás do conector do Aurora DSQL para Python é adicionar uma camada de autenticação sobre as bibliotecas de cliente psycopg, psycopg2 e asyncpg que lide com a geração de tokens do IAM, permitindo que os usuários se conectem ao Aurora DSQL sem alterar os respectivos fluxos de trabalho existentes.
### O que é a autenticação do Aurora DSQL?
Na autenticação do Aurora DSQL, a autenticação envolve:
+ **Autenticação do IAM**: todas as conexões usam autenticação baseada no IAM com tokens de tempo limitado.
+ **Geração de tokens:** os tokens de autenticação são gerados com o uso de credenciais da AWS e têm vida útil configurável.
O conector do Aurora DSQL para Python foi projetado para entender esses requisitos e gerar tokens de autenticação do IAM automaticamente ao estabelecer conexões.
### Recursos
+ **Autenticação automática do IAM**: os tokens do IAM são gerados automaticamente utilizando credenciais da AWS.
+ **Desenvolvido em psycopg, psycopg2 e asyncpg**: utiliza as bibliotecas de cliente psycopg, psycopg2 e asncpg.
+ **Integração perfeita**: funciona com os padrões de conexão psycopg, psycopg2 e asyncpg existentes sem exigir alterações no fluxo de trabalho.
+ **Descoberta automática de regiões**: extrai a região da AWS do nome de host do cluster do DSQL.
+ **Suporte a credenciais da AWS**: aceita vários provedores de credenciais da AWS (padrão, baseado em perfil, personalizado).
+ **Compatibilidade do grupo de conexões**: funciona com o grupo de conexões integrado psycopg, psycopg2 e asyncpg.
## Guia de início rápido
### Requisitos
+ Python 3.10 ou posterior
+ [Acesso a um cluster do Aurora DSQL](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/getting-started.html)
+ Configurar as permissões apropriadas do IAM para permitir que sua aplicação se conecte ao Aurora DSQL.
+ Credenciais da AWS configuradas (por meio da AWS CLI, de variáveis de ambiente ou perfis do IAM).
### Instalação
```
pip install aurora-dsql-python-connector
```
#### Instale a psycopg, a psycopg2 ou a asyncpg separadamente.
O instalador do conector do Aurora DSQL para Python não instala as bibliotecas subjacentes. É necessário instalá-las separadamente, por exemplo:
```
# Install psycopg and psycopg pool
pip install "psycopg[binary,pool]"
```
```
# Install psycopg2
pip install psycopg2-binary
```
```
# Install asyncpg
pip install asyncpg
```
**Observação:**
Somente a biblioteca necessária deve ser instalada. Portanto, se o cliente for usar a psycopg, somente ela precisará ser instalada. Se o cliente for usar a psycopg2, somente ela precisará ser instalada. Se o cliente for usar a asyncpg, somente ela precisará ser instalada.
Se o cliente precisar de mais de uma, todas as bibliotecas necessárias precisarão ser instaladas.
### Uso básico
#### psycopg
```
import aurora_dsql_psycopg as dsql
config = {
'host': "your-cluster.dsql.us-east-1.on.aws",
'region': "us-east-1",
'user': "admin",
}
conn = dsql.connect(**config)
with conn.cursor() as cur:
cur.execute("SELECT 1")
result = cur.fetchone()
print(result)
```
#### psycopg2
```
import aurora_dsql_psycopg2 as dsql
config = {
'host': "your-cluster.dsql.us-east-1.on.aws",
'region': "us-east-1",
'user': "admin",
}
conn = dsql.connect(**config)
with conn.cursor() as cur:
cur.execute("SELECT 1")
result = cur.fetchone()
print(result)
```
#### asyncpg
```
import asyncio
import aurora_dsql_asyncpg as dsql
config = {
'host': "your-cluster.dsql.us-east-1.on.aws",
'region': "us-east-1",
'user': "admin",
}
conn = await dsql.connect(**config)
result = await conn.fetchrow("SELECT 1")
await conn.close()
print(result)
```
#### Usar apenas o host
##### psycopg
```
import aurora_dsql_psycopg as dsql
conn = dsql.connect("your-cluster.dsql.us-east-1.on.aws")
```
##### psycopg2
```
import aurora_dsql_psycopg2 as dsql
conn = dsql.connect("your-cluster.dsql.us-east-1.on.aws")
```
##### asyncpg
```
import asyncio
import aurora_dsql_asyncpg as dsql
conn = await dsql.connect("your-cluster.dsql.us-east-1.on.aws")
```
#### Usar apenas o ID do cluster
##### psycopg
```
import aurora_dsql_psycopg as dsql
conn = dsql.connect("your-cluster")
```
##### psycopg2
```
import aurora_dsql_psycopg2 as dsql
conn = dsql.connect("your-cluster")
```
##### asyncpg
```
import asyncio
import aurora_dsql_asyncpg as dsql
conn = await dsql.connect("your-cluster")
```
**Observação:**
No cenário “usar apenas o ID do cluster”, a região que foi definida anteriormente na máquina é usada, por exemplo:
```
aws configure set region us-east-1
```
Se a região não tiver sido definida ou o ID do cluster fornecido estiver em uma região diferente, a conexão falhará. Para que funcione, forneça a região como parâmetro, como no exemplo abaixo:
##### psycopg
```
import aurora_dsql_psycopg as dsql
config = {
"region": "us-east-1",
}
conn = dsql.connect("your-cluster", **config)
```
##### psycopg2
```
import aurora_dsql_psycopg2 as dsql
config = {
"region": "us-east-1",
}
conn = dsql.connect("your-cluster", **config)
```
##### asyncpg
```
import asyncio
import aurora_dsql_asyncpg as dsql
config = {
"region": "us-east-1",
}
conn = await dsql.connect("your-cluster", **config)
```
### String de conexão
#### psycopg
```
import aurora_dsql_psycopg as dsql
conn = dsql.connect("postgresql://your-cluster.dsql.us-east-1.on.aws/postgres?user=admin&token_duration_secs=15")
```
#### psycopg2
```
import aurora_dsql_psycopg2 as dsql
conn = dsql.connect("postgresql://your-cluster.dsql.us-east-1.on.aws/postgres?user=admin&token_duration_secs=15")
```
#### asyncpg
```
import asyncio
import aurora_dsql_asyncpg as dsql
conn = await dsql.connect("postgresql://your-cluster.dsql.us-east-1.on.aws/postgres?user=admin&token_duration_secs=15")
```
### Configuração avançada
#### psycopg
```
import aurora_dsql_psycopg as dsql
config = {
'host': "your-cluster.dsql.us-east-1.on.aws",
'region': "us-east-1",
'user': "admin",
"profile": "default",
"token_duration_secs": "15",
}
conn = dsql.connect(**config)
with conn.cursor() as cur:
cur.execute("SELECT 1")
result = cur.fetchone()
print(result)
```
#### psycopg2
```
import aurora_dsql_psycopg2 as dsql
config = {
'host': "your-cluster.dsql.us-east-1.on.aws",
'region': "us-east-1",
'user': "admin",
"profile": "default",
"token_duration_secs": "15",
}
conn = dsql.connect(**config)
with conn.cursor() as cur:
cur.execute("SELECT 1")
result = cur.fetchone()
print(result)
```
#### asyncpg
```
import asyncio
import aurora_dsql_asyncpg as dsql
config = {
'host': "your-cluster.dsql.us-east-1.on.aws",
'region': "us-east-1",
'user': "admin",
"profile": "default",
"token_duration_secs": "15",
}
conn = await dsql.connect(**config)
result = await conn.fetchrow("SELECT 1")
await conn.close()
print(result)
```
### Opções de configuração
| Opção | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| host | string | Sim | Nome do host ou ID do cluster do DSQL |
| user | string | Não | Nome de usuário do DSQL. Padrão: admin |
| dbname | string | Não | Database name. Padrão: postgres |
| region | string | Não | Região da AWS (detectada automaticamente por meio do nome do host, se não for fornecido). |
| port | int | Não | O padrão é 5432. |
| custom\$1credentials\$1provider | CredentialProvider | Não | Provedor de credenciais personalizadas da AWS |
| profile | string | Não | O nome do perfil do IAM. Padrão: padrão. |
| token\$1duration\$1secs | int | Não | Tempo de expiração do token em segundos. |
Todas as opções de conexão padrão das bibliotecas psycopg, psycopg2 e asyncpg subjacentes também são aceitas, com exceção dos parâmetros asyncpg **krbsrvname** e **gsslib**, que não são aceitos pelo DSQL.
### Usar o conector do Aurora DSQL para Python com um grupo de conexões
O conector do Aurora DSQL para Python funciona com o grupo de conexões integrado psycopg, psycopg2 e asyncpg. O conector gerencia a geração de tokens do IAM durante o estabelecimento da conexão, permitindo que os grupos de conexões operem normalmente.
#### psycopg
Em relação à psycopg, o conector implementa uma classe de conexão chamada DSQLConnection que pode ser transmitida diretamente ao construtor psycopg\$1pool.ConnectionPool. Para operações assíncronas, também há uma versão assíncrona da classe chamada DSQLaSyncConnection.
```
from psycopg_pool import ConnectionPool as PsycopgPool
...
pool = PsycopgPool(
"",
connection_class=dsql.DSQLConnection,
kwargs=conn_params,
min_size=2,
max_size=8,
max_lifetime=3300
)
```
**Observação: configuração da conexão max\$1lifetime**
O parâmetro max\$1lifetime deve ser definido como menos de 3.600 segundos (uma hora), pois essa é a duração máxima da conexão permitida pelo banco de dados Aurora DSQL. Definir um max\$1lifetime inferior permite que o grupo de conexões gerencie de modo proativo a reciclagem de conexões, o que é mais eficiente do que lidar com erros de tempo limite de conexão do banco de dados.
#### psycopg2
Para psycopg2, o conector fornece uma classe chamada AuroraDSQLThreadedConnectionPool que herda de psycopg2.pool.ThreadedConnectionPool. A classe AuroraDSQLThreadedConnectionPool só substitui o método interno \$1connect. O restante da implementação é fornecido pelo psycopg2.pool.ThreadedConnectionPool inalterado.
```
import aurora_dsql_psycopg2 as dsql
pool = dsql.AuroraDSQLThreadedConnectionPool(
minconn=2,
maxconn=8,
**conn_params,
)
```
#### asyncpg
Para asyncpg, o conector fornece uma função create\$1pool que exibe uma instância de asyncpg.Pool.
```
import asyncio
import os
import aurora_dsql_asyncpg as dsql
pool_params = {
'host': "your-cluster.dsql.us-east-1.on.aws",
'user': "admin",
"min_size": 2,
"max_size": 5,
}
pool = await dsql.create_pool(**pool_params)
```
## Autenticação
O conector processa automaticamente a autenticação do DSQL gerando tokens com o uso do gerador de tokens do cliente do DSQL. Se a região da AWS não for fornecida, ela será automaticamente analisada por meio do nome do host fornecido.
Para acessar mais informações sobre autenticação no Aurora DSQL, consulte o [guia do usuário](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/authentication-authorization.html).
### Admin versus usuários regulares
+ Usuários chamados `"admin"` utilizam automaticamente tokens de autenticação de admin.
+ Todos os outros usuários utilizam tokens de autenticação diferentes de admin.
+ Os tokens são gerados dinamicamente para cada conexão.
## Exemplos
Para ver o código de exemplo completo, consulte os exemplos conforme indicado nas seções abaixo. Para receber instruções sobre como executar os exemplos, consulte os arquivos LEIAME dos exemplos.
### psycopg
[LEIAME dos exemplos](https://github.com/awslabs/aurora-dsql-connectors/blob/main/python/connector/examples/psycopg/README.md)
| Descrição | Exemplos |
| --- | --- |
| Usar o conector do Aurora DSQL para Python para conexões básicas | [Exemplo básico de conexão](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/psycopg/src/example_preferred.py) |
| Usar o conector do Aurora DSQL para Python para conexões assíncronas básicas | [Exemplo básico de conexão assíncrona](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/psycopg/src/alternatives/no_connection_pool/example_async_with_no_connection_pool.py) |
| Usar o conector do Aurora DSQL para Python com grupo de conexões | [Exemplo básico de conexão com grupo de conexões](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/psycopg/src/alternatives/pool/example_with_nonconcurrent_connection_pool.py) |
| | [Exemplo de conexões simultâneas com grupo de conexões](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/psycopg/src/example_preferred.py) |
| Usar o conector do Aurora DSQL para Python com grupo de conexões assíncronas | [Exemplo básico de conexão com grupo de conexões assíncronas](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/psycopg/src/alternatives/pool/example_with_async_connection_pool.py) |
### psycopg2
[LEIAME dos exemplos](https://github.com/awslabs/aurora-dsql-connectors/blob/main/python/connector/examples/psycopg2/README.md)
| Descrição | Exemplos |
| --- | --- |
| Usar o conector do Aurora DSQL para Python para conexões básicas | [Exemplo básico de conexão](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/psycopg2/src/example_preferred.py) |
| Usar o conector do Aurora DSQL para Python com grupo de conexões | [Exemplo básico de conexão com grupo de conexões](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/psycopg2/src/alternatives/pool/example_with_nonconcurrent_connection_pool.py) |
| | [Exemplo de conexões simultâneas com grupo de conexões](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/psycopg2/src/example_preferred.py) |
### asyncpg
[LEIAME dos exemplos](https://github.com/awslabs/aurora-dsql-connectors/blob/main/python/connector/examples/asyncpg/README.md)
| Descrição | Exemplos |
| --- | --- |
| Usar o conector do Aurora DSQL para Python para conexões básicas | [Exemplo básico de conexão](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/asyncpg/src/example_preferred.py) |
| Usar o conector do Aurora DSQL para Python com grupo de conexões | [Exemplo básico de conexão com grupo de conexões](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/asyncpg/src/alternatives/pool/example_with_nonconcurrent_connection_pool.py) |
| | [Exemplo de conexões simultâneas com grupo de conexões](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/asyncpg/src/example_preferred.py) |
# Conectar-se a clusters do Aurora DSQL com um conector Go
O [conector do Aurora DSQL para Go](https://github.com/awslabs/aurora-dsql-connectors/tree/main/go/pgx) encapsula o [pgx](https://github.com/jackc/pgx) com a autenticação automática do IAM. O conector gerencia a geração de tokens, a configuração SSL e o gerenciamento de conexões para que você se concentre na lógica da aplicação.
## Sobre o conector
O Aurora DSQL exige autenticação baseada no IAM com tokens de tempo limitado para os quais os drivers Go do PostgreSQL não oferecem suporte nativo. O conector do Aurora DSQL para Go adiciona uma camada de autenticação sobre o driver pgx que gerencia a geração de tokens do IAM, permitindo que você se conecte ao Aurora DSQL sem alterar seus fluxos de trabalho existentes do pgx.
### O que é a autenticação do Aurora DSQL?
Na autenticação do Aurora DSQL, a **autenticação** envolve:
+ **Autenticação do IAM**: todas as conexões usam autenticação baseada no IAM com tokens de tempo limitado.
+ **Geração de token**: o conector gera tokens de autenticação usando credenciais da AWS, e esses tokens têm vida útil configurável
O conector do Aurora DSQL para Go foi projetado para entender esses requisitos e gerar tokens de autenticação do IAM automaticamente ao estabelecer conexões.
### Benefícios do conector do Aurora DSQL para Go
O conector do Aurora DSQL para Go permite que você continue usando seus fluxos de trabalho existentes do pgx e, ao mesmo tempo, habilite a autenticação do IAM por meio de:
+ **Geração automática de tokens**: o conector gera tokens do IAM automaticamente para cada conexão
+ **Agrupamento de conexões**: suporte integrado para `pgxpool` com geração automática de tokens por conexão
+ **Configuração flexível**: suporte a endpoints completos ou IDs de cluster com detecção automática de região.
+ **Suporte a credenciais da AWS**: aceita perfis e provedores de credenciais personalizados da AWS.
## Atributos principais
Gerenciamento automático de tokens
O conector gera tokens do IAM automaticamente para cada nova conexão usando credenciais pré-resolvidas.
Agrupamento de conexões
Agrupamento de conexões por meio de `pgxpool` com geração automática de tokens por conexão.
Configuração flexível de hosts
Oferece suporte a endpoints completos de cluster e IDs de cluster com detecção automática de região.
Segurança SSL
O SSL está sempre habilitado com o modo de verificação completa e a negociação direta de TLS.
## Pré-requisitos
+ Go 1.24 ou posterior.
+ Credenciais da AWS configuradas.
+ Um cluster do Aurora DSQL.
O conector usa a [cadeia de credenciais padrão do AWS SDK para Go v2](https://docs.aws.amazon.com/sdk-for-go/v2/developer-guide/configure-gosdk.html#specifying-credentials), que resolve as credenciais na seguinte ordem:
1. Variáveis de ambiente (AWS\$1ACCESS\$1KEY\$1ID, AWS\$1SECRET\$1ACCESS\$1KEY)
1. Arquivo de credenciais compartilhadas (\$1/.aws/credentials)
1. Arquivo de configuração compartilhado (\$1/.aws/config)
1. Perfil do IAM para o Amazon EC2/ECS/Lambda
## Instalação
Instale o conector usando os módulos do Go:
```
go get github.com/awslabs/aurora-dsql-connectors/go/pgx/dsql
```
## Início rápido
O seguinte exemplo mostra como criar um grupo de conexões e executar uma consulta:
```
package main
import (
"context"
"log"
"github.com/awslabs/aurora-dsql-connectors/go/pgx/dsql"
)
func main() {
ctx := context.Background()
// Create a connection pool
pool, err := dsql.NewPool(ctx, dsql.Config{
Host: "your-cluster.dsql.us-east-1.on.aws",
})
if err != nil {
log.Fatal(err)
}
defer pool.Close()
// Execute a query
var greeting string
err = pool.QueryRow(ctx, "SELECT 'Hello, DSQL!'").Scan(&greeting)
if err != nil {
log.Fatal(err)
}
log.Println(greeting)
}
```
## Opções de configuração
O conector aceita as seguintes opções de configuração:
| Campo | Tipo | Padrão | Descrição |
| --- | --- | --- | --- |
| Host | string | (obrigatório) | Endpoint do cluster ou ID do cluster |
| Região | string | (detectado automaticamente) | Região da AWS; obrigatória se o host for um ID de cluster |
| Usuário | string | admin | Usuário do banco de dados |
| Banco de dados | string | “postgres” | Nome do banco de dados |
| Porta | int | 5432 | Database port |
| Perfil | string | "" | Nome do perfil da AWS para credenciais |
| TokenDurationSecs | int | 900 (15 min) | Duração da validade do token em segundos (máximo permitido: 1 semana, padrão: 15 min) |
| MaxConns | int32 | 0 | Máximo de conexões do grupo (0 = padrão pgxpool) |
| MinConns | int32 | 0 | Mínimo de conexões do grupo (0 = padrão pgxpool) |
| MaxConnLifetime | time.Duration | 55 minutos | Vida útil máxima da conexão |
## Formato de string da conexão
O conector é compatível com os formatos de string de conexão do PostgreSQL e do DSQL:
```
postgres://[user@]host[:port]/[database][?param=value&...]
dsql://[user@]host[:port]/[database][?param=value&...]
```
Parâmetros de consulta compatíveis:
+ `region`: região da AWS
+ `profile`: nome do perfil da AWS
+ `tokenDurationSecs`: duração da validade do token em segundos
Exemplos:
```
// Full endpoint (region auto-detected)
pool, _ := dsql.NewPool(ctx, "postgres://admin@cluster.dsql.us-east-1.on.aws/postgres")
// Using dsql:// scheme (also supported)
pool, _ := dsql.NewPool(ctx, "dsql://admin@cluster.dsql.us-east-1.on.aws/postgres")
// With explicit region
pool, _ := dsql.NewPool(ctx, "postgres://admin@cluster.dsql.us-east-1.on.aws/mydb?region=us-east-1")
// With AWS profile
pool, _ := dsql.NewPool(ctx, "postgres://admin@cluster.dsql.us-east-1.on.aws/postgres?profile=dev")
```
## Uso avançado
### Configuração do host
O conector aceita dois formatos de host:
**Endpoint completo** (região detectada automaticamente):
```
pool, _ := dsql.NewPool(ctx, dsql.Config{
Host: "your-cluster.dsql.us-east-1.on.aws",
})
```
**ID do cluster** (região obrigatória):
```
pool, _ := dsql.NewPool(ctx, dsql.Config{
Host: "your-cluster-id",
Region: "us-east-1",
})
```
### Ajuste da configuração do grupo
Configure o grupo de conexões para a workload:
```
pool, err := dsql.NewPool(ctx, dsql.Config{
Host: "your-cluster.dsql.us-east-1.on.aws",
MaxConns: 20,
MinConns: 5,
MaxConnLifetime: time.Hour,
MaxConnIdleTime: 30 * time.Minute,
HealthCheckPeriod: time.Minute,
})
```
### Uso de conexão única
Para scripts simples ou quando o agrupamento de conexões não é necessário:
```
conn, err := dsql.Connect(ctx, dsql.Config{
Host: "your-cluster.dsql.us-east-1.on.aws",
})
if err != nil {
log.Fatal(err)
}
defer conn.Close(ctx)
// Use the connection
rows, err := conn.Query(ctx, "SELECT * FROM users")
```
### Usar perfis da AWS
Especifique um perfil da AWS para credenciais:
```
pool, err := dsql.NewPool(ctx, dsql.Config{
Host: "your-cluster.dsql.us-east-1.on.aws",
Profile: "production",
})
```
## Nova tentativa de OCC
O Aurora DSQL usa o controle de simultaneidade otimista (OCC). Quando duas transações modificam os mesmos dados, a primeira a confirmar vence e a segunda recebe um erro de OCC.
O pacote `occretry` fornece ajudantes para nova tentativa automática com recuo exponencial e instabilidade. Instale-o com:
```
go get github.com/awslabs/aurora-dsql-connectors/go/pgx/occretry
```
Use `WithRetry` para gravações transacionais:
```
err := occretry.WithRetry(ctx, pool, occretry.DefaultConfig(), func(tx pgx.Tx) error {
_, err := tx.Exec(ctx, "UPDATE accounts SET balance = balance - $1 WHERE id = $2", 100, fromID)
if err != nil {
return err
}
_, err = tx.Exec(ctx, "UPDATE accounts SET balance = balance + $1 WHERE id = $2", 100, toID)
return err
})
```
Para declarações DDL ou únicas, use `ExecWithRetry`:
```
err := occretry.ExecWithRetry(ctx, pool, occretry.DefaultConfig(),
"CREATE TABLE IF NOT EXISTS users (id UUID PRIMARY KEY, name TEXT)")
```
**Importante**
`WithRetry` gerencia `BEGIN`/`COMMIT`/`ROLLBACK` internamente. Seu retorno de chamada recebe uma transação e deve conter somente operações de banco de dados e ser seguro para tentar novamente.
## Exemplos
Para ver exemplos e casos de uso mais abrangentes, consulte [exemplos do conector do Aurora DSQL para Go](https://github.com/awslabs/aurora-dsql-connectors/tree/main/go/pgx/example).
| Exemplo | Descrição |
| --- | --- |
| [example\$1preferred](https://github.com/awslabs/aurora-dsql-connectors/tree/main/go/pgx/example/src/example_preferred.go) | Recomendado: grupo de conexões com consultas simultâneas |
| [transaction](https://github.com/awslabs/aurora-dsql-connectors/tree/main/go/pgx/example/src/transaction) | Tratamento de transações com BEGIN/COMMIT/ROLLBACK |
| [occ\$1retry](https://github.com/awslabs/aurora-dsql-connectors/tree/main/go/pgx/example/src/occ_retry) | Tratamento de conflitos de OCC com recuo exponencial |
| [connection\$1string](https://github.com/awslabs/aurora-dsql-connectors/tree/main/go/pgx/example/src/connection_string) | Uso de strings de conexão para configuração |
# Conectores do Aurora DSQL para Node.js
O conector do Aurora DSQL para node-postgres e o conector do Aurora DSQL para Postgres.js são plug-ins de autenticação que estendem a funcionalidade dos clientes node-postgres e Postgres.js para permitir que as aplicações se autentiquem com o Aurora DSQL usando credenciais do IAM.
# Conector do Aurora SQL para node-postgres
O [conector do Aurora DSQL para node-postgres](https://github.com/awslabs/aurora-dsql-connectors/tree/main/node/node-postgres) é um conector Node.js desenvolvido em [node-postgres](https://node-postgres.com/) que integra a autenticação do IAM para conectar aplicações JavaScript/TypeScript aos clusters do Amazon Aurora DSQL.
O conector do Aurora DSQL foi projetado como um plug-in de autenticação que estende a funcionalidade do cliente e do grupo do node-postgres para permitir que as aplicações se autentiquem com o Amazon Aurora DSQL utilizando credenciais do IAM.
## Sobre o conector
O Amazon Aurora DSQL é um banco de dados distribuído nativo da nuvem com compatibilidade com o PostgreSQL. Embora ele exija autenticação do IAM e tokens com limite de tempo, os drivers de banco de dados Node.js tradicionais não têm esse suporte integrado.
O conector do Aurora DSQL para node-postgres preenche essa lacuna implementando um middleware de autenticação que funciona perfeitamente com o node-postgres. Essa abordagem permite que os desenvolvedores mantenham seu código node-postgres existente e, ao mesmo tempo, tenham acesso seguro baseado em IAM aos clusters do Aurora DSQL por meio do gerenciamento automatizado de tokens.
### O que é a autenticação do Aurora DSQL?
Na autenticação do Aurora DSQL, a autenticação envolve:
+ **Autenticação do IAM**: todas as conexões usam autenticação baseada no IAM com tokens de tempo limitado.
+ **Geração de tokens:** os tokens de autenticação são gerados com o uso de credenciais da AWS e têm vida útil configurável.
O conector do Aurora DSQL para node-postgres foi projetado para entender esses requisitos e gerar tokens de autenticação do IAM automaticamente ao estabelecer conexões.
### Recursos
+ **Autenticação automática do IAM**: trata da geração e atualização de tokens do DSQL.
+ **Desenvolvido em node-postgres**: utiliza o conhecido cliente PostgreSQL para Node.js.
+ **Integração perfeita**: funciona com padrões existentes de conexão do node-postgres.
+ **Descoberta automática de regiões**: extrai a região da AWS do nome de host do cluster do DSQL.
+ **Suporte completo ao TypeScript**: oferece segurança total de tipos.
+ **Suporte a credenciais da AWS**: aceita vários provedores de credenciais da AWS (padrão, baseado em perfil, personalizado).
+ **Compatibilidade com agrupamento de conexões**: funciona perfeitamente com o agrupamento de conexões integrado.
## Aplicação de exemplo
Há uma aplicação de exemplo incluída em [exemplo](https://github.com/awslabs/aurora-dsql-connectors/tree/main/node/node-postgres/example), que mostra como usar o conector do Aurora DSQL para node-postgres. Para executar o exemplo incluído, consulte o respectivo [LEIAME](https://github.com/awslabs/aurora-dsql-connectors/blob/main/node/node-postgres/example/README.md)
## Guia de início rápido
### Requisitos
+ Node.js 20
+ [Acesso a um cluster do Aurora DSQL](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/getting-started.html)
+ Configurar as permissões apropriadas do IAM para permitir que sua aplicação se conecte ao Aurora DSQL.
+ Credenciais da AWS configuradas (por meio da AWS CLI, de variáveis de ambiente ou perfis do IAM).
## Instalação
```
npm install @aws/aurora-dsql-node-postgres-connector
```
## Dependências de pares
```
npm install @aws-sdk/credential-providers @aws-sdk/dsql-signer pg tsx
npm install --save-dev @types/pg
```
## Usage
### Conexão do cliente
```
import { AuroraDSQLClient } from "@aws/aurora-dsql-node-postgres-connector";
const client = new AuroraDSQLClient({
host: "",
user: "admin",
});
await client.connect();
const result = await client.query("SELECT NOW()");
await client.end();
```
### Conexão do grupo
```
import { AuroraDSQLPool } from "@aws/aurora-dsql-node-postgres-connector";
const pool = new AuroraDSQLPool({
host: "",
user: "admin",
max: 3,
idleTimeoutMillis: 60000,
});
const result = await pool.query("SELECT NOW()");
```
### Uso avançado
```
import { fromNodeProviderChain } from "@aws-sdk/credential-providers";
import { AuroraDSQLClient } from "@aws/aurora-dsql-node-postgres-connector";
const client = new AuroraDSQLClient({
host: "example.dsql.us-east-1.on.aws",
user: "admin",
customCredentialsProvider: fromNodeProviderChain(), // Optionally provide custom credentials provider
});
await client.connect();
const result = await client.query("SELECT NOW()");
await client.end();
```
## Opções de configuração
| Opção | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| host | string | Sim | Nome do host do cluster do DSQL |
| username | string | Sim | Nome de usuário do DSQL |
| database | string | Não | Nome do banco de dados |
| region | string | Não | Região da AWS (detectada automaticamente por meio do nome do host, se não for fornecido). |
| port | number | Não | O padrão é 5432. |
| customCredentialsProvider | AwsCredentialIdentity / AwsCredentialIdentityProvider | Não | Provedor de credenciais personalizadas da AWS |
| profile | string | Não | O nome do perfil do IAM. Tem como padrão “padrão”. |
| tokenDurationSecs | number | Não | Tempo de expiração do token em segundos. |
Todos os outros parâmetros de [Cliente](https://node-postgres.com/apis/client)/[Grupo](https://node-postgres.com/apis/pool) são aceitos.
## Autenticação
O conector processa automaticamente a autenticação do DSQL gerando tokens com o uso do gerador de tokens do cliente do DSQL. Se a região da AWS não for fornecida, ela será automaticamente analisada por meio do nome do host fornecido.
Para acessar mais informações sobre autenticação no Aurora DSQL, consulte o [guia do usuário](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/authentication-authorization.html).
### Admin versus usuários regulares
+ Usuários chamados “admin” utilizam automaticamente tokens de autenticação de admin.
+ Todos os outros usuários utilizam tokens de autenticação regulares.
+ Os tokens são gerados dinamicamente para cada conexão.
# Conector do Aurora SQL para Postgres.js
O [conector do Aurora DSQL para Postgres.js](https://github.com/awslabs/aurora-dsql-connectors/tree/main/node/postgres-js) é um conector Node.js desenvolvido em [Postgres.js](https://github.com/porsager/postgres) que integra a autenticação do IAM para conectar aplicações Javascript aos clusters do Amazon Aurora DSQL.
O conector do Aurora DSQL para Postgres.js foi projetado como um plug-in de autenticação que estende a funcionalidade do cliente do Postgres.js para permitir que as aplicações se autentiquem com o Amazon Aurora DSQL utilizando credenciais do IAM. O conector não se conecta diretamente ao banco de dados, mas oferece uma autenticação perfeita do IAM no driver subjacente do Postgres.js.
## Sobre o conector
O Amazon Aurora DSQL é um serviço de banco de dados SQL distribuído que oferece alta disponibilidade e escalabilidade para aplicações compatíveis com o PostgreSQL. O Aurora DSQL exige autenticação baseada no IAM com tokens de tempo limitado que não são aceitos pelos drivers Node.js.
A ideia por trás do conector do Aurora DSQL para Postgres.js é adicionar uma camada de autenticação sobre o cliente do Postgres.js que gerencia a geração de tokens do IAM, permitindo que os usuários se conectem ao Aurora DSQL sem alterar os respectivos fluxos de trabalho do Postgres.js existentes.
O conector do Aurora DSQL para Postgres.js funciona com a maioria das versões do Postgres.js. Os usuários fornecem a própria versão instalando o Postgres.js diretamente.
### O que é a autenticação do Aurora DSQL?
Na autenticação do Aurora DSQL, a autenticação envolve:
+ **Autenticação do IAM**: todas as conexões usam autenticação baseada no IAM com tokens de tempo limitado.
+ **Geração de tokens:** os tokens de autenticação são gerados com o uso de credenciais da AWS e têm vida útil configurável.
O conector do Aurora DSQL para Postgres.js foi projetado para entender esses requisitos e gerar tokens de autenticação do IAM automaticamente ao estabelecer conexões.
### Recursos
+ **Autenticação automática do IAM**: trata da geração e atualização de tokens do DSQL.
+ **Desenvolvido em Postgres.js**: utiliza o rápido cliente do PostgreSQL para Node.js.
+ **Integração perfeita**: funciona com padrões existentes de conexão do Postgres.js.
+ **Descoberta automática de regiões**: extrai a região da AWS do nome de host do cluster do DSQL.
+ **Suporte completo ao TypeScript**: oferece segurança total de tipos.
+ **Suporte a credenciais da AWS**: aceita vários provedores de credenciais da AWS (padrão, baseado em perfil, personalizado).
+ **Compatibilidade com agrupamento de conexões**: funciona perfeitamente com o agrupamento de conexões integrado do Postgres.js.
## Guia de início rápido
### Requisitos
+ Node.js 20
+ [Acesso a um cluster do Aurora DSQL](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/getting-started.html)
+ Configurar as permissões apropriadas do IAM para permitir que sua aplicação se conecte ao Aurora DSQL.
+ Credenciais da AWS configuradas (por meio da AWS CLI, de variáveis de ambiente ou perfis do IAM).
### Instalação
```
npm install @aws/aurora-dsql-postgresjs-connector
# Postgres.js is a peer-dependency, so users must install it themselves
npm install postgres
```
### Uso básico
```
import { auroraDSQLPostgres } from '@aws/aurora-dsql-postgresjs-connector';
const sql = auroraDSQLPostgres({
host: 'your-cluster.dsql.us-east-1.on.aws',
username: 'admin',
});
// Execute queries
const result = await sql`SELECT current_timestamp`;
console.log(result);
// Clean up
await sql.end();
```
#### Utilizar o ID do cluster em vez do host
```
const sql = auroraDSQLPostgres({
host: 'your-cluster-id',
region: 'us-east-1',
username: 'admin',
});
```
### String de conexão
```
const sql = AuroraDSQLPostgres(
'postgres://admin@your-cluster.dsql.us-east-1.on.aws'
);
const result = await sql`SELECT current_timestamp`;
```
### Configuração avançada
```
import { fromNodeProviderChain } from '@aws-sdk/credential-providers';
const sql = AuroraDSQLPostgres({
host: 'your-cluster.dsql.us-east-1.on.aws',
database: 'postgres',
username: 'admin',
customCredentialsProvider: fromNodeProviderChain(), // Optionally provide custom credentials provider
tokenDurationSecs: 3600, // Token expiration (seconds)
// Standard Postgres.js options
max: 20, // Connection pool size
ssl: { rejectUnauthorized: false } // SSL configuration
});
```
## Opções de configuração
| Opção | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| host | string | Sim | Nome do host ou ID do cluster do DSQL |
| database | string? | Não | Nome do banco de dados |
| username | string? | Não | Nome de usuário do banco de dados (usará admin se não for fornecido) |
| region | string? | Não | Região da AWS (detectada automaticamente por meio do nome do host, se não for fornecido). |
| customCredentialsProvider | AwsCredentialIdentityProvider? | Não | Provedor de credenciais personalizadas da AWS |
| tokenDurationSecs | number? | Não | Tempo de expiração do token em segundos. |
Todas as [opções padrão do Postgres.js](https://github.com/porsager/postgres?tab=readme-ov-file#connection-details) também são aceitas.
## Autenticação
O conector processa automaticamente a autenticação do DSQL gerando tokens com o uso do gerador de tokens do cliente do DSQL. Se a região da AWS não for fornecida, ela será automaticamente analisada por meio do nome do host fornecido.
Para acessar mais informações sobre autenticação no Aurora DSQL, consulte o [guia do usuário](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/authentication-authorization.html).
### Admin versus usuários regulares
+ Usuários chamados “admin” utilizam automaticamente tokens de autenticação de admin.
+ Todos os outros usuários utilizam tokens de autenticação regulares.
+ Os tokens são gerados dinamicamente para cada conexão.
## Exemplo de uso
Exemplos de JavaScript usando o conector do Aurora DSQL para Postgres.js estão disponíveis no GitHub. Para ver instruções sobre como executar os exemplos, consulte o [diretório de exemplos](https://github.com/awslabs/aurora-dsql-connectors/tree/main/node/postgres-js/example).
| Descrição | Exemplo |
| --- | --- |
| Agrupamento de conexões com consultas simultâneas, incluindo criação de tabelas, inserções e leituras em vários operadores | [Exemplo de grupo de conexões (preferencial)](https://github.com/awslabs/aurora-dsql-connectors/blob/main/node/postgres-js/example/src/example_preferred.js) |
| Operações CRUD (criar tabela, inserir, selecionar, excluir) sem grupo de conexões | [Exemplo sem grupo de conexões](https://github.com/awslabs/aurora-dsql-connectors/blob/main/node/postgres-js/example/src/alternatives/no_connection_pool/example_with_no_connection_pool.js) |
# Conectar-se a clusters do Aurora DSQL com um conector Ruby
O [conector do Aurora DSQL para Ruby](https://github.com/awslabs/aurora-dsql-connectors/tree/main/ruby/pg) é um conector Ruby desenvolvido em [pg](https://github.com/ged/ruby-pg) que integra a autenticação do IAM para conectar aplicações Ruby aos clusters do Amazon Aurora DSQL.
O conector gerencia a geração de tokens, a configuração SSL e o agrupamento de conexões para que você se concentre na lógica da aplicação.
## Sobre o conector
O Amazon Aurora DSQL exige autenticação do IAM com tokens de tempo limitado para os quais os drivers PostgreSQL do Ruby existentes não oferecem suporte nativo. O conector do Aurora DSQL para Ruby adiciona uma camada de autenticação sobre o driver pg que gerencia a geração de tokens do IAM, permitindo que você se conecte ao Aurora DSQL sem alterar seus fluxos de trabalho existentes do pg.
### O que é a autenticação do Aurora DSQL?
Na autenticação do Aurora DSQL, a **autenticação** envolve:
+ **Autenticação do IAM**: todas as conexões usam autenticação baseada no IAM com tokens de tempo limitado.
+ **Geração de token**: o conector gera tokens de autenticação usando credenciais da AWS, e esses tokens têm vida útil configurável
O conector do Aurora DSQL para Ruby entende esses requisitos e gera tokens de autenticação do IAM automaticamente ao estabelecer conexões.
### Recursos
+ **Autenticação automática do IAM:** lida com a geração e atualização de tokens do Aurora DSQL
+ **Desenvolvido em pg:** agrupa o popular gem do PostgreSQL para Ruby
+ **Integração perfeita:** funciona com fluxos de trabalho de pg gem existentes
+ **Agrupamento de conexões:** suporte integrado por meio do `connection_pool` gem com aplicação de max\$1lifetime
+ **Detecção automática de região:** extrai a região da AWS do nome de host do cluster do Aurora DSQL
+ **Suporte a credenciais da AWS:** aceita perfis e provedores de credenciais personalizados da AWS
+ **Nova tentativa de OCC:** opte por uma nova tentativa de controle de simultaneidade otimista com recuo exponencial
## Aplicativo de exemplo
Para ver um exemplo completo, consulte a [aplicação de exemplo](https://github.com/awslabs/aurora-dsql-connectors/tree/main/ruby/pg/example) no GitHub.
## Guia de início rápido
### Requisitos
+ Ruby 3.1 ou posterior
+ [Acesso a um cluster do Aurora DSQL](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/getting-started.html)
+ Credenciais da AWS configuradas (por meio da CLI da AWS, de variáveis de ambiente ou perfis do IAM)
## Instalação
Adicione a seu Gemfile:
```
gem "aurora-dsql-ruby-pg"
```
Ou instale diretamente:
```
gem install aurora-dsql-ruby-pg
```
## Usage
### Conexão do grupo
```
require "aurora_dsql_pg"
# Create a connection pool with OCC retry enabled
pool = AuroraDsql::Pg.create_pool(
host: "your-cluster.dsql.us-east-1.on.aws",
occ_max_retries: 3
)
# Read
pool.with do |conn|
result = conn.exec("SELECT 'Hello, DSQL!'")
puts result[0]["?column?"]
end
# Write — you must wrap writes in a transaction
pool.with do |conn|
conn.transaction do
conn.exec_params("INSERT INTO users (id, name) VALUES (gen_random_uuid(), $1)", ["Alice"])
end
end
pool.shutdown
```
### Conexão única
Para scripts simples ou quando o agrupamento de conexões não é necessário:
```
conn = AuroraDsql::Pg.connect(host: "your-cluster.dsql.us-east-1.on.aws")
conn.exec("SELECT 1")
conn.close
```
### Uso avançado
**Configuração do host**
O conector é compatível com endpoints de cluster completos (região detectada automaticamente) e IDs de cluster (região obrigatória):
```
# Full endpoint (region auto-detected)
pool = AuroraDsql::Pg.create_pool(
host: "your-cluster.dsql.us-east-1.on.aws"
)
# Cluster ID (region required)
pool = AuroraDsql::Pg.create_pool(
host: "your-cluster-id",
region: "us-east-1"
)
```
**AWS Perfis do**
Especifique um perfil da AWS para credenciais:
```
pool = AuroraDsql::Pg.create_pool(
host: "your-cluster.dsql.us-east-1.on.aws",
profile: "production"
)
```
**Formato de string da conexão**
O conector é compatível com os formatos de string de conexão do PostgreSQL:
```
postgres://[user@]host[:port]/[database][?param=value&...]
postgresql://[user@]host[:port]/[database][?param=value&...]
```
Parâmetros de consulta compatíveis: `region`, `profile`, `tokenDurationSecs`.
```
# Full endpoint with profile
pool = AuroraDsql::Pg.create_pool(
"postgres://admin@cluster.dsql.us-east-1.on.aws/postgres?profile=dev"
)
```
**Nova tentativa de OCC**
O Aurora DSQL usa o controle de simultaneidade otimista (OCC). Quando duas transações modificam os mesmos dados, a primeira a confirmar vence e a segunda recebe um erro de OCC.
A nova tentativa do OCC é opcional. Defina `occ_max_retries` ao criar o agrupamento para ativar a nova tentativa automática com recuo exponencial e instabilidade em `pool.with`:
```
pool = AuroraDsql::Pg.create_pool(
host: "your-cluster.dsql.us-east-1.on.aws",
occ_max_retries: 3
)
pool.with do |conn|
conn.transaction do
conn.exec_params("UPDATE accounts SET balance = balance - $1 WHERE id = $2", [100, from_id])
conn.exec_params("UPDATE accounts SET balance = balance + $1 WHERE id = $2", [100, to_id])
end
end
```
**Atenção**
O `pool.with` NÃO agrupa automaticamente seu bloco em uma transação. Você deve chamar `conn.transaction` por conta própria para operações de gravação. Em caso de conflito de OCC, o conector reexecuta o bloco inteiro, portanto, ele deve conter somente operações de banco de dados e ser seguro tentar novamente.
Para pular a nova tentativa de chamadas individuais, passe `retry_occ: false`:
```
pool.with(retry_occ: false) do |conn|
conn.exec("SELECT 1")
end
```
## Opções de configuração
| Campo | Tipo | Padrão | Descrição |
| --- | --- | --- | --- |
| host | String | (obrigatório) | Endpoint do cluster ou ID do cluster |
| region | String | (detectado automaticamente) | Região da AWS; obrigatória se o host for um ID de cluster |
| usuário | String | admin | Usuário do banco de dados |
| banco de dados | String | “postgres” | Nome do banco de dados |
| porta | Inteiro | 5432 | Database port |
| perfil | String | nulo | Nome do perfil da AWS para credenciais |
| token\$1duration | Inteiro | 900 (15 min) | Duração da validade do token em segundos (máximo permitido: 1 semana, padrão: 15 min) |
| credentials\$1provider | Aws::Credentials | nulo | Provedor de credenciais personalizadas |
| max\$1lifetime | Inteiro | 3300 (55 min) | Vida útil máxima da conexão em segundos |
| application\$1name | String | nulo | Prefixo ORM para application\$1name |
| Logger | Logger | nulo | Registrador para avisos de nova tentativa de OCC |
| occ\$1max\$1retries | Inteiro | nulo (desabilitado) | Máximo de novas tentativas de OCC em pool.with; habilita a nova tentativa quando definido |
`create_pool` também aceita uma palavra-chave `pool:` com um hash de opções que você passa diretamente para `ConnectionPool.new`. Se você omitir `pool:`, o conector assume `{size: 5, timeout: 5}` como padrão. As chaves fornecidas substituem somente esses padrões específicos.
```
pool = AuroraDsql::Pg.create_pool(
host: "your-cluster.dsql.us-east-1.on.aws",
pool: { size: 10, timeout: 10 }
)
```
## Autenticação
O conector gerencia automaticamente a autenticação do Aurora DSQL gerando tokens com o uso de credenciais da AWS. Se você não fornecer a região da AWS, o conector a analisará a partir do nome do host.
Para obter mais informações sobre autenticação no Aurora DSQL, consulte [Autenticação e autorização para o Aurora DSQL](authentication-authorization.md).
### Admin versus usuários regulares
+ Usuários chamados “admin” utilizam automaticamente tokens de autenticação de admin.
+ Todos os outros usuários utilizam tokens de autenticação regulares.
+ O conector gera tokens dinamicamente para cada conexão
# Conectar-se a clusters do Aurora DSQL com um conector .NET
O [conector do Amazon Aurora DSQL para .NET](https://github.com/awslabs/aurora-dsql-connectors/tree/main/dotnet/npgsql) é um conector .NET desenvolvido em [Npgsql](https://www.npgsql.org/) que integra a autenticação do IAM para conectar aplicações .NET aos clusters do Amazon Aurora DSQL.
O conector gerencia a geração de tokens, a configuração SSL e o agrupamento de conexões para que você se concentre na lógica da aplicação.
## Sobre o conector
O Amazon Aurora DSQL exige autenticação do IAM com tokens de tempo limitado para os quais os drivers PostgreSQL do .NET existentes não oferecem suporte nativo. O conector do Aurora DSQL para .NET adiciona uma camada de autenticação sobre o Npgsql que gerencia a geração de tokens do IAM, permitindo que você se conecte ao Aurora DSQL sem alterar seus fluxos de trabalho existentes do Npgsql.
### O que é a autenticação do Aurora DSQL?
Na autenticação do Aurora DSQL, a **autenticação** envolve:
+ **Autenticação do IAM**: todas as conexões usam autenticação baseada no IAM com tokens de tempo limitado.
+ **Geração de token**: o conector gera tokens de autenticação usando credenciais da AWS, e esses tokens têm vida útil configurável
O conector do Aurora DSQL para .NET entende esses requisitos e gera tokens de autenticação do IAM automaticamente ao estabelecer conexões.
### Recursos
+ **Autenticação automática do IAM:** lida com a geração e atualização de tokens do Aurora DSQL
+ **Desenvolvido em Npgsql:** agrupa o popular driver PostgreSQL para.NET
+ **Integração perfeita:** funciona com fluxos de trabalho de Npgsql existentes
+ **Agrupamento de conexões:** suporte integrado por meio do `NpgsqlDataSource` com aplicação de vida útil máxima
+ **Detecção automática de região:** extrai a região da AWS do nome de host do cluster do Aurora DSQL
+ **Suporte a credenciais da AWS:** aceita perfis e provedores de credenciais personalizados da AWS
+ **Nova tentativa de OCC:** opte por uma nova tentativa de controle de simultaneidade otimista com recuo exponencial
+ **Aplicação de SSL:** sempre usa SSL com o modo `verify-full` e negociação direta de TLS
## Aplicativo de exemplo
Para ver um exemplo completo, consulte a [aplicação de exemplo](https://github.com/awslabs/aurora-dsql-connectors/tree/main/dotnet/npgsql/example) no GitHub.
## Guia de início rápido
### Requisitos
+ .NET 8.0 ou posterior
+ [Acesso a um cluster do Aurora DSQL](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/getting-started.html)
+ Credenciais da AWS configuradas (por meio da CLI da AWS, de variáveis de ambiente ou perfis do IAM)
## Instalação
Adicione o pacote ao seu projeto:
```
dotnet add package Amazon.AuroraDsql.Npgsql
```
## Usage
### Conexão do grupo
```
using Amazon.AuroraDsql.Npgsql;
// Create a connection pool
await using var ds = await AuroraDsql.CreateDataSourceAsync(new DsqlConfig
{
Host = "your-cluster.dsql.us-east-1.on.aws",
OccMaxRetries = 3
});
// Read
await using (var conn = await ds.OpenConnectionAsync())
{
await using var cmd = conn.CreateCommand();
cmd.CommandText = "SELECT 'Hello, DSQL!'";
var greeting = await cmd.ExecuteScalarAsync();
Console.WriteLine(greeting);
}
// Transactional write with OCC retry
await ds.WithTransactionRetryAsync(async conn =>
{
await using var cmd = conn.CreateCommand();
cmd.CommandText = "INSERT INTO users (id, name) VALUES (gen_random_uuid(), @name)";
cmd.Parameters.AddWithValue("name", "Alice");
await cmd.ExecuteNonQueryAsync();
});
```
### Conexão única
Para scripts simples ou quando você não tem o agrupamento de conexões:
```
await using var conn = await AuroraDsql.ConnectAsync(new DsqlConfig
{
Host = "your-cluster.dsql.us-east-1.on.aws"
});
await using var cmd = conn.CreateCommand("SELECT 1");
await cmd.ExecuteScalarAsync();
```
### Nova tentativa de OCC
O Aurora DSQL usa o controle de simultaneidade otimista (OCC). Quando duas transações modificam os mesmos dados, a primeira a confirmar vence e a segunda recebe um erro de OCC.
A nova tentativa do OCC é opcional. Defina `OccMaxRetries` na configuração para habilitar nova tentativa automática com recuo exponencial e instabilidade. Use `WithTransactionRetryAsync` para gravações transacionais:
```
await ds.WithTransactionRetryAsync(async conn =>
{
await using var cmd = conn.CreateCommand();
cmd.CommandText = "UPDATE accounts SET balance = balance - 100 WHERE id = @from";
cmd.Parameters.AddWithValue("from", fromId);
await cmd.ExecuteNonQueryAsync();
cmd.CommandText = "UPDATE accounts SET balance = balance + 100 WHERE id = @to";
cmd.Parameters.Clear();
cmd.Parameters.AddWithValue("to", toId);
await cmd.ExecuteNonQueryAsync();
});
```
Para declarações DDL ou únicas, use `ExecWithRetryAsync`:
```
await ds.ExecWithRetryAsync("CREATE TABLE IF NOT EXISTS users (id UUID PRIMARY KEY, name TEXT)");
```
**Importante**
`WithTransactionRetryAsync` gerencia `BEGIN`/`COMMIT`/`ROLLBACK` internamente e abre uma nova conexão para cada tentativa. Seu retorno de chamada deve conter somente operações de banco de dados e ser seguro tentar novamente.
## Opções de configuração
O conector também aceita strings de conexão `postgres://` e `postgresql://` com os parâmetros de consulta `region` e `profile`.
| Campo | Tipo | Padrão | Descrição |
| --- | --- | --- | --- |
| Host | string | (obrigatório) | Endpoint do cluster ou ID do cluster de 26 caracteres |
| Region | string? | (detectado automaticamente) | Região da AWS; obrigatória se o Host for um ID de cluster |
| User | string | "admin" | Usuário do banco de dados |
| Database | string | "postgres" | Nome do banco de dados |
| Port | int | 5432 | Database port |
| Profile | string? | null | Nome do perfil da AWS para credenciais |
| CustomCredentialsProvider | AWSCredentials? | null | Provedor de credenciais da AWS personalizadas |
| TokenDurationSecs | int? | null (SDK padrão, 900s) | Duração da validade do token em segundos |
| OccMaxRetries | int? | null (desabilitado) | Máximo padrão de novas tentativas de OCC para métodos de nova tentativa na fonte de dados |
| OrmPrefix | string? | null | Prefixo ORM prefixado a application\$1name |
| LoggerFactory | ILoggerFactory? | null | Fábrica de loggers para novas tentativas, avisos e diagnósticos |
| ConfigureConnectionString | Action? | null | Retorno de chamada para substituir as configurações do agrupamento ou definir propriedades adicionais da string de conexão Npgsql. SSL e Enlist são invariantes de segurança e não podem ser substituídos. |
## Autenticação
O conector gerencia automaticamente a autenticação do Aurora DSQL gerando tokens com o uso de credenciais da AWS. Se você não fornecer a região da AWS, o conector a analisará a partir do nome do host.
Para obter mais informações sobre autenticação no Aurora DSQL, consulte [Autenticação e autorização para o Aurora DSQL](authentication-authorization.md).
### Admin versus usuários regulares
+ Usuários chamados “admin” utilizam automaticamente tokens de autenticação de admin.
+ Todos os outros usuários utilizam tokens de autenticação regulares.
+ O conector gera tokens dinamicamente para cada conexão