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

L'[Aurora DSQL Connector for Ruby è un connettore Ruby](https://github.com/awslabs/aurora-dsql-connectors/tree/main/ruby/pg) basato su [pg](https://github.com/ged/ruby-pg) che integra l'autenticazione IAM per connettere le applicazioni Ruby ai cluster DSQL di Amazon Aurora.

Il connettore gestisce la generazione di token, la configurazione SSL e il pool di connessioni in modo che tu possa concentrarti sulla logica dell'applicazione.

## Informazioni sul connettore
<a name="SECTION_program-with-dsql-connector-for-ruby-pg-about"></a>

Amazon Aurora DSQL richiede l'autenticazione IAM con token a tempo limitato che i driver Ruby PostgreSQL esistenti non supportano nativamente. L'Aurora DSQL Connector per Ruby aggiunge un livello di autenticazione alla gemma pg che gestisce la generazione di token IAM, consentendoti di connetterti ad Aurora DSQL senza modificare i flussi di lavoro pg esistenti.

### Cos'è l'autenticazione Aurora DSQL?
<a name="SECTION_program-with-dsql-connector-for-ruby-pg-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 AWS credenziali e questi token hanno una durata configurabile

L'Aurora DSQL Connector per Ruby comprende questi requisiti e genera automaticamente token di autenticazione IAM quando stabilisce le connessioni.

### Funzionalità
<a name="SECTION_program-with-dsql-connector-for-ruby-pg-features"></a>
+ **Autenticazione IAM automatica**: gestisce la generazione e l'aggiornamento dei token Aurora DSQL
+ **Costruito su pg**: racchiude la famosa gemma PostgreSQL per Ruby
+ **Integrazione perfetta**: funziona con i flussi di lavoro pg gem esistenti
+ **Connessione condivisa** - Supporto integrato tramite gem con max\$1lifetime enforcement `connection_pool`
+ **Rilevamento automatico della regione**: estrae la AWS regione dal nome host del cluster Aurora DSQL
+ AWS supporto per **le credenziali: supporta profili** e fornitori di credenziali personalizzate AWS 
+ **Riprova OCC: attiva un nuovo tentativo** ottimistico di controllo della concorrenza con backoff esponenziale

## Esempio di applicazione
<a name="SECTION_program-with-dsql-connector-for-ruby-pg-example-application"></a>

Per un esempio completo, vedi l'[applicazione di esempio](https://github.com/awslabs/aurora-dsql-connectors/tree/main/ruby/pg/example) su GitHub.

## Guida rapida di avvio
<a name="SECTION_program-with-dsql-connector-for-ruby-pg-quick-start"></a>

### Requisiti
<a name="SECTION_program-with-dsql-connector-for-ruby-pg-requirements"></a>
+ Ruby 3.1 o versione successiva
+ [Accesso a un cluster Aurora DSQL](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/getting-started.html)
+ AWS credenziali configurate (tramite AWS CLI, variabili di ambiente o ruoli IAM)

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

Aggiungi al tuo Gemfile:

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

Oppure installa direttamente:

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

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

### Connessione alla piscina
<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
```

### Connessione singola
<a name="SECTION_program-with-dsql-connector-for-ruby-pg-single-connection"></a>

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

```
conn = AuroraDsql::Pg.connect(host: "your-cluster.dsql.us-east-1.on.aws")
conn.exec("SELECT 1")
conn.close
```

### Utilizzo avanzato
<a name="SECTION_program-with-dsql-connector-for-ruby-pg-advanced"></a>

**Configurazione dell'host**

Il connettore supporta sia gli endpoint completi del cluster (regione rilevata automaticamente) che il cluster IDs (regione richiesta):

```
# 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 profili**

Specificare un AWS profilo per le credenziali:

```
pool = AuroraDsql::Pg.create_pool(
  host: "your-cluster.dsql.us-east-1.on.aws",
  profile: "production"
)
```

**Formato della stringa di connessione**

Il connettore supporta i formati di stringhe di connessione PostgreSQL:

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

Parametri di interrogazione supportati:`region`,,. `profile` `tokenDurationSecs`

```
# Full endpoint with profile
pool = AuroraDsql::Pg.create_pool(
  "postgres://admin@cluster.dsql.us-east-1.on.aws/postgres?profile=dev"
)
```

**Riprova OCC**

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 nuovo tentativo OCC è facoltativo. Imposta al `occ_max_retries` momento della creazione del pool per abilitare i nuovi tentativi automatici con backoff e jitter esponenziali attivi: `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
```

**avvertimento**  
`pool.with`NON inserisce automaticamente il blocco in una transazione. È necessario chiamare se `conn.transaction` stessi per le operazioni di scrittura. In caso di conflitto OCC, il connettore riesegue l'intero blocco, quindi dovrebbe contenere solo le operazioni del database ed essere sicuro di riprovare.

Per evitare di ripetere le singole chiamate, inserisci: `retry_occ: false`

```
pool.with(retry_occ: false) do |conn|
  conn.exec("SELECT 1")
end
```

## Opzioni di configurazione
<a name="SECTION_program-with-dsql-connector-for-ruby-pg-configuration"></a>


| Campo | Tipo | Predefinita | Description | 
| --- | --- | --- | --- | 
| host | Stringa | (richiesto) | Endpoint o ID del cluster | 
| region | Stringa | (rilevato automaticamente) | AWS regione; richiesto se l'host è un ID del cluster | 
| user | Stringa | «amministratore» | Utente del database | 
| database | Stringa | «postgres» | Nome del database | 
| port | Numero intero | 5432 | Database port (Porta del database) | 
| profile | Stringa | zero | AWS nome del profilo per le credenziali | 
| token\$1duration | Numero intero | 900 (15 min) | Durata della validità del token in secondi (massimo consentito: 1 settimana, impostazione predefinita: 15 min) | 
| credentials\$1provider | Aws: :Credentials | zero | Provider di credenziali personalizzate | 
| max\$1lifetime | Numero intero | 3300 (55 min) | Durata massima della connessione in secondi | 
| application\$1name | Stringa | zero | Prefisso ORM per application\$1name | 
| boscaiolo | Logger | zero | Logger per avvisi di nuovi tentativi OCC | 
| occ\$1max\$1retries | Numero intero | nil (disabilitato) | Numero massimo di tentativi OCC attivipool.with; abilita i nuovi tentativi quando impostato | 

`create_pool`accetta anche una `pool:` parola chiave con un hash di opzioni a cui passi direttamente. `ConnectionPool.new` Se si omette`pool:`, per impostazione predefinita il connettore è. `{size: 5, timeout: 5}` Le chiavi fornite sostituiscono solo quelle impostazioni predefinite specifiche.

```
pool = AuroraDsql::Pg.create_pool(
  host: "your-cluster.dsql.us-east-1.on.aws",
  pool: { size: 10, timeout: 10 }
)
```

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

Il connettore gestisce automaticamente l'autenticazione Aurora DSQL generando token utilizzando credenziali. AWS Se non fornite la AWS regione, il connettore la analizza a partire dal nome host.

Per ulteriori informazioni sull'autenticazione in Aurora DSQL, vedere. [Autenticazione e autorizzazione per Aurora DSQL](authentication-authorization.md)

### Amministratore e utenti normali
<a name="SECTION_program-with-dsql-connector-for-ruby-pg-admin-vs-regular"></a>
+ Gli utenti denominati «admin» utilizzano automaticamente i token di autenticazione dell'amministratore
+ Tutti gli altri utenti utilizzano token di autenticazione regolari
+ Il connettore genera i token in modo dinamico per ogni connessione