# Conectar-se a clusters do Aurora DSQL com um conector Ruby
<a name="SECTION_program-with-dsql-connector-for-ruby-pg"></a>

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
<a name="SECTION_program-with-dsql-connector-for-ruby-pg-about"></a>

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?
<a name="SECTION_program-with-dsql-connector-for-ruby-pg-authentication"></a>

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
<a name="SECTION_program-with-dsql-connector-for-ruby-pg-features"></a>
+ **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
<a name="SECTION_program-with-dsql-connector-for-ruby-pg-example-application"></a>

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
<a name="SECTION_program-with-dsql-connector-for-ruby-pg-quick-start"></a>

### Requisitos
<a name="SECTION_program-with-dsql-connector-for-ruby-pg-requirements"></a>
+ 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
<a name="SECTION_program-with-dsql-connector-for-ruby-pg-installation"></a>

Adicione a seu Gemfile:

```
gem "aurora-dsql-ruby-pg"
```

Ou instale diretamente:

```
gem install aurora-dsql-ruby-pg
```

## Usage
<a name="SECTION_program-with-dsql-connector-for-ruby-pg-usage"></a>

### Conexão do grupo
<a name="SECTION_program-with-dsql-connector-for-ruby-pg-pool-connection"></a>

```
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
<a name="SECTION_program-with-dsql-connector-for-ruby-pg-single-connection"></a>

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
<a name="SECTION_program-with-dsql-connector-for-ruby-pg-advanced"></a>

**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
<a name="SECTION_program-with-dsql-connector-for-ruby-pg-configuration"></a>


| 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
<a name="SECTION_program-with-dsql-connector-for-ruby-pg-auth"></a>

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
<a name="SECTION_program-with-dsql-connector-for-ruby-pg-admin-vs-regular"></a>
+ 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