Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

# Connexion aux clusters SQL Aurora à l'aide d'un connecteur Go
<a name="SECTION_program-with-go-pgx-connector"></a>

Le [connecteur SQL Aurora pour Go intègre l'authentification](https://github.com/awslabs/aurora-dsql-connectors/tree/main/go/pgx) IAM automatique à [pgx](https://github.com/jackc/pgx). Le connecteur gère la génération de jetons, la configuration SSL et la gestion des connexions afin que vous puissiez vous concentrer sur la logique de votre application.

## À propos du connecteur
<a name="SECTION_program-with-go-pgx-connector-about"></a>

Aurora DSQL nécessite une authentification basée sur IAM avec des jetons limités dans le temps que les pilotes Go PostgreSQL existants ne prennent pas en charge de manière native. Le connecteur Aurora DSQL pour Go ajoute une couche d'authentification au-dessus du pilote pgx qui gère la génération de jetons IAM, ce qui vous permet de vous connecter à Aurora DSQL sans modifier vos flux de travail pgx existants.

### Qu’est-ce que l’authentification Aurora DSQL ?
<a name="SECTION_program-with-go-pgx-connector-authentication"></a>

Dans Aurora DSQL, **l’authentification** implique :
+ **Authentification IAM** : toutes les connexions utilisent l’authentification basée sur IAM avec des jetons à durée limitée
+ **Génération de jetons** : le connecteur génère des jetons d'authentification à l'aide AWS d'informations d'identification, et ces jetons ont une durée de vie configurable

Le connecteur Aurora DSQL pour Go est conçu pour comprendre ces exigences et générer automatiquement des jetons d'authentification IAM lors de l'établissement de connexions.

### Avantages du connecteur Aurora DSQL pour Go
<a name="SECTION_program-with-go-pgx-connector-benefits"></a>

Le connecteur SQL Aurora pour Go vous permet de continuer à utiliser vos flux de travail pgx existants tout en activant l'authentification IAM via :
+ **Génération automatique de jetons** : le connecteur génère des jetons IAM automatiquement pour chaque connexion
+ **Regroupement de connexions** : prise en charge intégrée `pgxpool` de la génération automatique de jetons par connexion
+ **Configuration flexible** : Support pour des terminaux complets ou des clusters IDs avec détection automatique des régions
+ **AWS Support des identifiants** : prend en charge les AWS profils et les fournisseurs d'identifiants personnalisés

## Fonctions principales
<a name="SECTION_program-with-go-pgx-connector-features"></a>

Gestion automatique des jetons  
Le connecteur génère automatiquement des jetons IAM pour chaque nouvelle connexion à l'aide d'informations d'identification prérésolues.

Regroupement de connexions  
Regroupement des connexions via `pgxpool` génération automatique de jetons par connexion.

Configuration flexible de l'hôte  
Prend en charge à la fois les points de terminaison complets du cluster et le cluster IDs avec détection automatique des régions.

Sécurité SSL  
Le protocole SSL est toujours activé avec le mode de vérification complète et la négociation directe du protocole TLS.

## Conditions préalables
<a name="SECTION_program-with-go-pgx-connector-prerequisites"></a>
+ Go 1.24 ou version ultérieure
+ AWS informations d'identification configurées
+ Un cluster SQL Aurora

Le connecteur utilise la chaîne d'informations d'[identification par défaut du AWS SDK for Go v2](https://docs.aws.amazon.com/sdk-for-go/v2/developer-guide/configure-gosdk.html#specifying-credentials), qui résout les informations d'identification dans l'ordre suivant :

1. Variables d'environnement (AWS\$1ACCESS\$1KEY\$1ID, \$1ACCESS\$1KEY) AWS\$1SECRET

1. Fichier d'informations d'identification partagé (\$1/.aws/credentials)

1. Fichier de configuration partagé (\$1/.aws/config)

1. Rôle IAM pour Amazon EC2/ECS/Lambda

## Installation
<a name="SECTION_program-with-go-pgx-connector-installation"></a>

Installez le connecteur à l'aide des modules Go :

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

## Démarrage rapide
<a name="SECTION_program-with-go-pgx-connector-quick-start"></a>

L'exemple suivant montre comment créer un pool de connexions et exécuter une requête :

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

## Options de configuration
<a name="SECTION_program-with-go-pgx-connector-configuration"></a>

Le connecteur prend en charge les options de configuration suivantes :


| Champ | Type | Par défaut | Description | 
| --- | --- | --- | --- | 
| Host (Hôte) | chaîne | (obligatoire) | Point de terminaison ou ID de cluster | 
| Région | chaîne | (détecté automatiquement) | AWS région ; obligatoire si l'hôte est un identifiant de cluster | 
| Utilisateur | chaîne | « administrateur » | Utilisateur de la base de donnée | 
| Base de données | chaîne | « postgres » | Nom de la base de données | 
|  Port | int | 5432 | Port de la base de données | 
| Profil | chaîne | "" | AWS nom de profil pour les informations d'identification | 
| TokenDurationSecs | int | 900 (15 minutes) | Durée de validité du jeton en secondes (maximum autorisé : 1 semaine, par défaut : 15 min) | 
| MaxConns | int32 | 0 | Nombre maximum de connexions au pool (0 = pgxpool par défaut) | 
| MinConns | int32 | 0 | Nombre minimal de connexions au pool (0 = pgxpool par défaut) | 
| MaxConnLifetime | Heure. Durée | 55 minutes | Durée de vie maximale de la connexion | 

## Format de chaîne de connexion
<a name="SECTION_program-with-go-pgx-connector-connection-string"></a>

Le connecteur prend en charge les formats de chaîne de connexion PostgreSQL et DSQL :

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

Paramètres de requête pris en charge :
+ `region`- AWS région
+ `profile`- nom du AWS profil
+ `tokenDurationSecs`- Durée de validité du jeton en secondes

Exemples :

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

## Utilisation avancée
<a name="SECTION_program-with-go-pgx-connector-advanced"></a>

### Configuration de l’hôte
<a name="SECTION_program-with-go-pgx-connector-host-config"></a>

Le connecteur prend en charge deux formats d'hôte :

**Point de terminaison complet** (région détectée automatiquement) :

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

**ID du cluster** (région requise) :

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

### Réglage de la configuration du pool
<a name="SECTION_program-with-go-pgx-connector-pool-tuning"></a>

Configurez le pool de connexions pour votre charge de travail :

```
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,
})
```

### Utilisation d'une connexion unique
<a name="SECTION_program-with-go-pgx-connector-single-connection"></a>

Pour les scripts simples ou lorsque le regroupement de connexions n'est pas nécessaire :

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

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

Spécifiez un AWS profil pour les informations d'identification :

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

## Réessayer OCC
<a name="SECTION_program-with-go-pgx-connector-occ-retry"></a>

Aurora DSQL utilise un contrôle de simultanéité optimiste (OCC). Lorsque deux transactions modifient les mêmes données, la première à valider gagne et la seconde reçoit une erreur OCC.

Le `occretry` package fournit des aides pour une nouvelle tentative automatique avec un recul et une instabilité exponentiels. Installez-le avec :

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

Utilisation `WithRetry` pour les écritures transactionnelles :

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

Pour les instructions DDL ou uniques, utilisez `ExecWithRetry` :

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

**Important**  
`WithRetry`gère`BEGIN`/`COMMIT`/`ROLLBACK`en interne. Votre rappel reçoit une transaction et ne doit contenir que des opérations de base de données et vous pouvez réessayer en toute sécurité.

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

Pour des exemples et des cas d'utilisation plus complets, reportez-vous aux [exemples d'Aurora DSQL Connector for Go](https://github.com/awslabs/aurora-dsql-connectors/tree/main/go/pgx/example).


| Exemple | Description | 
| --- | --- | 
|  [exemple\$1préféré](https://github.com/awslabs/aurora-dsql-connectors/tree/main/go/pgx/example/src/example_preferred.go)  | Recommandé : pool de connexions avec requêtes simultanées | 
|  [transaction](https://github.com/awslabs/aurora-dsql-connectors/tree/main/go/pgx/example/src/transaction)  | Gestion des transactions avec BEGIN/COMMIT/ROLLBACK | 
|  [occ\$1réessayer](https://github.com/awslabs/aurora-dsql-connectors/tree/main/go/pgx/example/src/occ_retry)  | Gérer les conflits OCC avec un recul exponentiel | 
|  [chaîne\$1connexion](https://github.com/awslabs/aurora-dsql-connectors/tree/main/go/pgx/example/src/connection_string)  | Utilisation de chaînes de connexion pour la configuration |