Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

# Connettore Aurora DSQL per Go pgx
<a name="SECTION_program-with-go-pgx-connector"></a>

L'[Aurora DSQL Connector for Go](https://github.com/awslabs/aurora-dsql-connectors/tree/main/go/pgx) avvolge [pgx](https://github.com/jackc/pgx) con l'autenticazione IAM automatica. Il connettore gestisce la generazione di token, la configurazione SSL e la gestione delle connessioni in modo che tu possa concentrarti sulla logica dell'applicazione.

## Informazioni sul connettore
<a name="SECTION_program-with-go-pgx-connector-about"></a>

Aurora DSQL richiede l'autenticazione basata su IAM con token a tempo limitato che i driver Go PostgreSQL esistenti non supportano nativamente. L'Aurora DSQL Connector for Go aggiunge un livello di autenticazione al driver pgx che gestisce la generazione di token IAM, consentendoti di connetterti ad Aurora DSQL senza modificare i flussi di lavoro pgx esistenti.

### Che cos’è l’autenticazione di Aurora DSQL?
<a name="SECTION_program-with-go-pgx-connector-authentication"></a>

In Aurora DSQL, l’**autenticazione** prevede:
+ **Autenticazione IAM:** tutte le connessioni utilizzano l’autenticazione basata su IAM con token a tempo limitato
+ **Generazione di token**: il connettore genera token di autenticazione utilizzando credenziali e questi token hanno una durata configurabile AWS 

Aurora DSQL Connector for Go è progettato per comprendere questi requisiti e generare automaticamente token di autenticazione IAM quando si stabiliscono connessioni.

### Vantaggi del connettore Aurora DSQL per Go
<a name="SECTION_program-with-go-pgx-connector-benefits"></a>

L'Aurora DSQL Connector for Go ti consente di continuare a utilizzare i flussi di lavoro pgx esistenti abilitando al contempo l'autenticazione IAM tramite:
+ **Generazione automatica di token**: il connettore genera automaticamente token IAM per ogni connessione
+ **Connessione in pool**: supporto integrato per la generazione automatica `pgxpool` di token per connessione
+ **Configurazione flessibile**: Supporto per endpoint o cluster completi IDs con rilevamento automatico della regione
+ **AWS Supporto credenziali**: supporta AWS profili e fornitori di credenziali personalizzate

## Funzionalità principali
<a name="SECTION_program-with-go-pgx-connector-features"></a>

Gestione automatica dei token  
Il connettore genera automaticamente token IAM per ogni nuova connessione utilizzando credenziali prerisolte.

Pooling di connessioni  
Connessione condivisa tramite generazione automatica `pgxpool` di token per connessione.

Configurazione host flessibile  
Supporta sia gli endpoint completi del cluster che il cluster IDs con rilevamento automatico della regione.

Sicurezza SSL  
SSL è sempre abilitato con la modalità verify-full e la negoziazione TLS diretta.

## Prerequisiti
<a name="SECTION_program-with-go-pgx-connector-prerequisites"></a>
+ Vai alla versione 1.24 o successiva
+ AWS credenziali configurate
+ Un cluster Aurora DSQL

Il connettore utilizza la catena di [credenziali predefinita AWS SDK for Go v2, che risolve le credenziali](https://docs.aws.amazon.com/sdk-for-go/v2/developer-guide/configure-gosdk.html#specifying-credentials) nel seguente ordine:

1. Variabili di ambiente (\_KEY\_ID, \_ACCESS\_KEY) AWS\_ACCESS AWS\_SECRET

1. File di credenziali condiviso (\~/.aws/credentials)

1. File di configurazione condiviso (\~/.aws/config)

1. Ruolo IAM per Amazon EC2/ECS/Lambda

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

Installa il connettore utilizzando i moduli Go:

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

## Avvio rapido
<a name="SECTION_program-with-go-pgx-connector-quick-start"></a>

L'esempio seguente mostra come creare un pool di connessioni ed eseguire una query:

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

## Opzioni di configurazione
<a name="SECTION_program-with-go-pgx-connector-configuration"></a>

Il connettore supporta le seguenti opzioni di configurazione:


| Campo | Tipo | Predefinita | Description | 
| --- | --- | --- | --- | 
| Host | stringa | (richiesto) | Endpoint o ID del cluster | 
| Region | stringa | (rilevato automaticamente) | AWS regione; richiesto se Host è un ID del cluster | 
| Utente | stringa | «amministratore» | Utente del database | 
| Database | stringa | «postgres» | Nome del database | 
| Porta | int | 5432 | Database port (Porta del database) | 
| Profilo | stringa | "" | AWS nome del profilo per le credenziali | 
| TokenDurationSecs | int | 900 (15 min) | Durata della validità del token in secondi (massimo consentito: 1 settimana, impostazione predefinita: 15 min) | 
| MaxConns | int32 | 0 | Numero massimo di connessioni al pool (0 = pgxpool predefinito) | 
| MinConns | int32 | 0 | Connessioni minime al pool (0 = pgxpool default) | 
| MaxConnLifetime | Tempo.duration | 55 minuti | Durata massima della connessione | 

## Formato della stringa di connessione
<a name="SECTION_program-with-go-pgx-connector-connection-string"></a>

Il connettore supporta i formati di stringhe di connessione PostgreSQL e DSQL:

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

Parametri di interrogazione supportati:
+ `region`- AWS regione
+ `profile`- nome AWS del profilo
+ `tokenDurationSecs`- Durata della validità del token in secondi

Esempi:

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

## Utilizzo avanzato
<a name="SECTION_program-with-go-pgx-connector-advanced"></a>

### Configurazione host
<a name="SECTION_program-with-go-pgx-connector-host-config"></a>

Il connettore supporta due formati host:

**Endpoint completo** (regione rilevata automaticamente):

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

**ID cluster** (regione richiesta):

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

### Ottimizzazione della configurazione del pool
<a name="SECTION_program-with-go-pgx-connector-pool-tuning"></a>

Configura il pool di connessioni per il tuo carico di lavoro:

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

### Utilizzo di una singola connessione
<a name="SECTION_program-with-go-pgx-connector-single-connection"></a>

Per script semplici o quando non è necessario il pool di connessioni:

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

### Utilizzo dei profili AWS
<a name="SECTION_program-with-go-pgx-connector-aws-profiles"></a>

Specificare un AWS profilo per le credenziali:

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

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

Aurora DSQL utilizza il controllo ottimistico della concorrenza (OCC). Quando due transazioni modificano gli stessi dati, la prima che esegue il commit vince e la seconda riceve un errore OCC.

Il `occretry` pacchetto fornisce strumenti per riprovare automaticamente con backoff e jitter esponenziali. Installalo con:

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

Uso `WithRetry` per le scritture transazionali:

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

Per le istruzioni DDL o singole, usa: `ExecWithRetry`

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

**Importante**  
`WithRetry`gestisce`BEGIN`/`COMMIT`/`ROLLBACK`internamente. Il callback riceve una transazione e dovrebbe contenere solo le operazioni del database ed essere sicuro di riprovare.

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

Per esempi e casi d'uso più completi, consulta gli esempi di [Aurora DSQL Connector for](https://github.com/awslabs/aurora-dsql-connectors/tree/main/go/pgx/example) Go.


| Esempio | Description | 
| --- | --- | 
|  [example\_preferred](https://github.com/awslabs/aurora-dsql-connectors/tree/main/go/pgx/example/src/example_preferred.go)  | Consigliato: pool di connessioni con query simultanee | 
|  [transazione](https://github.com/awslabs/aurora-dsql-connectors/tree/main/go/pgx/example/src/transaction)  | Gestione delle transazioni con BEGIN/COMMIT/ROLLBACK | 
|  [occ\_retry](https://github.com/awslabs/aurora-dsql-connectors/tree/main/go/pgx/example/src/occ_retry)  | Gestione dei conflitti OCC con backoff esponenziale | 
|  [stringa\_di connessione](https://github.com/awslabs/aurora-dsql-connectors/tree/main/go/pgx/example/src/connection_string)  | Utilizzo di stringhe di connessione per la configurazione |