# Conexión a clústeres de Aurora DSQL con un conector de Go
<a name="SECTION_program-with-go-pgx-connector"></a>

El [conector de Aurora DSQL para Go](https://github.com/awslabs/aurora-dsql-connectors/tree/main/go/pgx) envuelve [pgx](https://github.com/jackc/pgx) con la autenticación IAM automática. El conector se encarga de la generación de tokens, la configuración SSL y la gestión de conexiones para que usted pueda centrarse en la lógica de su aplicación.

## Acerca del conector
<a name="SECTION_program-with-go-pgx-connector-about"></a>

Aurora DSQL requiere una autenticación basada en IAM con tokens de duración limitada que los controladores de Go PostgreSQL existentes no admiten de forma nativa. El conector de Aurora DSQL para Go añade una capa de autenticación sobre el controlador pgx que gestiona la generación de tokens IAM, lo que le permite conectarse a Aurora DSQL sin cambiar sus flujos de trabajo de pgx existentes.

### ¿Qué es la autenticación de Aurora DSQL?
<a name="SECTION_program-with-go-pgx-connector-authentication"></a>

En Aurora DSQL, la **autenticación** implica:
+ **Autenticación de IAM**: todas las conexiones utilizan la autenticación basada en IAM con tokens de tiempo limitado
+ **Generación de tokens**: el conector genera tokens de autenticación utilizando credenciales de AWS, y estos tokens tienen una duración configurable.

El conector de Aurora DSQL para Go está diseñado para comprender estos requisitos y generar automáticamente los tokens de autenticación de IAM al establecer las conexiones.

### Ventajas del conector de Aurora DSQL para Go
<a name="SECTION_program-with-go-pgx-connector-benefits"></a>

El conector de Aurora DSQL para Go le permite seguir utilizando sus flujos de trabajo de pgx existentes, al tiempo que habilita la autenticación de IAM a través de:
+ **Generación automática de tokens**: el conector genera automáticamente tokens de IAM para cada conexión.
+ **Agrupación de conexiones**: soporte integrado para `pgxpool` con generación automática de tokens por conexión.
+ **Configuración flexible**: compatibilidad con puntos de conexión completos o ID de clúster con detección automática de región.
+ **Compatibilidad con credenciales de AWS**: admite perfiles de AWS y proveedores de credenciales personalizados.

## Características principales de
<a name="SECTION_program-with-go-pgx-connector-features"></a>

Administración automática de tokens  
El conector genera automáticamente los tokens de IAM para cada nueva conexión mediante credenciales previamente resueltas.

Grupo de conexiones  
Agrupación de conexiones mediante `pgxpool` con generación automática de tokens por conexión.

Configuración de host flexible  
Admite tanto puntos de conexión de clúster completos como ID de clúster con detección automática de región.

Seguridad SSL  
SSL siempre está habilitado con el modo de verificación completa y negociación TLS directa.

## Requisitos previos
<a name="SECTION_program-with-go-pgx-connector-prerequisites"></a>
+ Go 1.24 o posterior
+ Credenciales de AWS configuradas
+ Un clúster de Aurora DSQL

El conector usa la [cadena de credenciales predeterminada del SDK de AWS para Go v2](https://docs.aws.amazon.com/sdk-for-go/v2/developer-guide/configure-gosdk.html#specifying-credentials), que resuelve las credenciales en el siguiente orden:

1. Variables de entorno (AWS\$1ACCESS\$1KEY\$1ID, AWS\$1SECRET\$1ACCESS\$1KEY)

1. Archivo de credenciales compartidas (\$1/.aws/credentials)

1. Archivo de configuración compartido (\$1/.aws/config)

1. Rol de IAM para Amazon EC2/ECS/Lambda

## Instalación
<a name="SECTION_program-with-go-pgx-connector-installation"></a>

Instale el conector mediante los módulos Go:

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

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

En el siguiente ejemplo, se muestra cómo crear un grupo de conexiones y ejecutar una 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)
}
```

## Opciones de configuración
<a name="SECTION_program-with-go-pgx-connector-configuration"></a>

El conector es compatible con las siguientes opciones de configuración:


| Campo | Tipo | Predeterminado | Descripción | 
| --- | --- | --- | --- | 
| Host | cadena | (obligatorio) | Punto de conexión de clúster o ID de clúster | 
| Región | cadena | (detectado automáticamente) | Región de AWS; obligatorio si el host es un ID de clúster | 
| Usuario | cadena | "admin" | Usuario de base de datos | 
| Database | cadena | "postgres" | Nombre de base de datos | 
| Puerto | int | 5432 | Database port (Puerto de base de datos) | 
| Perfil | cadena | "" | Nombre de perfil de AWS para las credenciales | 
| TokenDurationSecs | int | 900 (15 minutos) | Duración de validez del token en segundos (máximo permitido: 1 semana, valor predeterminado: 15 minutos) | 
| MaxConns | int32 | 0 | Conexiones máximas de grupo (0 = pgxpool predeterminado) | 
| MinConns | int32 | 0 | Conexiones de grupo mínimas (0 = pgxpool predeterminado) | 
| MaxConnLifetime | time.Duration | 55 minutos | Tiempo máximo de conexión | 

## Formato de la cadena de conexión
<a name="SECTION_program-with-go-pgx-connector-connection-string"></a>

El conector admite los formatos de cadena de conexión PostgreSQL y DSQL:

```
postgres://[user@]host[:port]/[database][?param=value&...]
dsql://[user@]host[:port]/[database][?param=value&...]
```

Parámetros de consulta compatibles:
+ `region`: región de AWS
+ `profile`: nombre de perfil de AWS
+ `tokenDurationSecs`: duración de la validez del token en segundos

Ejemplos:

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

### Configuración de host
<a name="SECTION_program-with-go-pgx-connector-host-config"></a>

El conector admite dos formatos de host:

**Punto de conexión completo** (región detectada automáticamente):

```
pool, _ := dsql.NewPool(ctx, dsql.Config{
    Host: "your-cluster.dsql.us-east-1.on.aws",
})
```

**ID de clúster** (región requerida):

```
pool, _ := dsql.NewPool(ctx, dsql.Config{
    Host:   "your-cluster-id",
    Region: "us-east-1",
})
```

### Ajuste de configuración de grupo
<a name="SECTION_program-with-go-pgx-connector-pool-tuning"></a>

Configure el grupo de conexiones para su carga de trabajo:

```
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 conexión única
<a name="SECTION_program-with-go-pgx-connector-single-connection"></a>

Para scripts simples o cuando no es necesaria la agrupación de conexiones:

```
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")
```

### Uso de perfiles de AWS
<a name="SECTION_program-with-go-pgx-connector-aws-profiles"></a>

Especificación de un perfil de AWS para credenciales:

```
pool, err := dsql.NewPool(ctx, dsql.Config{
    Host:    "your-cluster.dsql.us-east-1.on.aws",
    Profile: "production",
})
```

## Reintento de OCC
<a name="SECTION_program-with-go-pgx-connector-occ-retry"></a>

Aurora DSQL utiliza control de simultaneidad optimista (OCC). Cuando dos transacciones modifican los mismos datos, la primera en confirmarse tiene prioridad y la segunda recibe un error de OCC.

El paquete `occretry` proporciona ayudantes para el reintento automático con retroceso exponencial y fluctuación. Instálelo con:

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

Use `WithRetry` para escrituras transaccionales:

```
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 instrucciones DDL o simples, use `ExecWithRetry`:

```
err := occretry.ExecWithRetry(ctx, pool, occretry.DefaultConfig(),
    "CREATE TABLE IF NOT EXISTS users (id UUID PRIMARY KEY, name TEXT)")
```

**importante**  
`WithRetry` administra `BEGIN`/`COMMIT`/`ROLLBACK` internamente. Su devolución de llamada recibe una transacción y debe contener solo operaciones de base de datos, además de ser segura para reintentarlo.

## Ejemplos
<a name="SECTION_program-with-go-pgx-connector-examples"></a>

Para ver ejemplos y casos de uso más completos, consulte los [ejemplos del conector de Aurora DSQL para Go](https://github.com/awslabs/aurora-dsql-connectors/tree/main/go/pgx/example).


| Ejemplo | Descripción | 
| --- | --- | 
|  [example\$1preferred](https://github.com/awslabs/aurora-dsql-connectors/tree/main/go/pgx/example/src/example_preferred.go)  | Recomendado: grupo de conexiones con consultas simultáneas | 
|  [transacción](https://github.com/awslabs/aurora-dsql-connectors/tree/main/go/pgx/example/src/transaction)  | Gestión de transacciones con BEGIN/COMMIT/ROLLBACK | 
|  [occ\$1retry](https://github.com/awslabs/aurora-dsql-connectors/tree/main/go/pgx/example/src/occ_retry)  | Cómo gestionar los conflictos de OCC con un retroceso exponencial | 
|  [connection\$1string](https://github.com/awslabs/aurora-dsql-connectors/tree/main/go/pgx/example/src/connection_string)  | Uso de cadenas de conexión para la configuración |