# Conectar-se a clusters do Aurora DSQL com um conector Go
<a name="SECTION_program-with-go-pgx-connector"></a>

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
<a name="SECTION_program-with-go-pgx-connector-about"></a>

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?
<a name="SECTION_program-with-go-pgx-connector-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 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
<a name="SECTION_program-with-go-pgx-connector-benefits"></a>

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
<a name="SECTION_program-with-go-pgx-connector-features"></a>

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
<a name="SECTION_program-with-go-pgx-connector-prerequisites"></a>
+ 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
<a name="SECTION_program-with-go-pgx-connector-installation"></a>

Instale o conector usando os módulos do Go:

```
go get github.com/awslabs/aurora-dsql-connectors/go/pgx/dsql
```

## Início rápido
<a name="SECTION_program-with-go-pgx-connector-quick-start"></a>

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
<a name="SECTION_program-with-go-pgx-connector-configuration"></a>

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
<a name="SECTION_program-with-go-pgx-connector-connection-string"></a>

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
<a name="SECTION_program-with-go-pgx-connector-advanced"></a>

### Configuração do host
<a name="SECTION_program-with-go-pgx-connector-host-config"></a>

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
<a name="SECTION_program-with-go-pgx-connector-pool-tuning"></a>

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
<a name="SECTION_program-with-go-pgx-connector-single-connection"></a>

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
<a name="SECTION_program-with-go-pgx-connector-aws-profiles"></a>

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
<a name="SECTION_program-with-go-pgx-connector-occ-retry"></a>

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
<a name="SECTION_program-with-go-pgx-connector-examples"></a>

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 |