Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich.

# Aurora DSQL-Konnektor für Ruby pg
<a name="SECTION_program-with-dsql-connector-for-ruby-pg"></a>

Der [Aurora DSQL Connector für Ruby](https://github.com/awslabs/aurora-dsql-connectors/tree/main/ruby/pg) ist ein auf [pg](https://github.com/ged/ruby-pg) basierender Ruby-Connector, der die IAM-Authentifizierung für die Verbindung von Ruby-Anwendungen mit Amazon Aurora DSQL-Clustern integriert.

Der Connector kümmert sich um die Token-Generierung, die SSL-Konfiguration und das Verbindungspooling, sodass Sie sich auf Ihre Anwendungslogik konzentrieren können.

## Über den Konnektor
<a name="SECTION_program-with-dsql-connector-for-ruby-pg-about"></a>

Amazon Aurora DSQL erfordert eine IAM-Authentifizierung mit zeitlich begrenzten Token, die von vorhandenen Ruby PostgreSQL-Treibern nicht nativ unterstützt werden. Der Aurora DSQL Connector für Ruby fügt dem PG-Gem eine Authentifizierungsebene hinzu, die die IAM-Token-Generierung übernimmt, sodass Sie eine Verbindung zu Aurora DSQL herstellen können, ohne Ihre bestehenden pg-Workflows zu ändern.

### Was ist Aurora DSQL-Authentifizierung?
<a name="SECTION_program-with-dsql-connector-for-ruby-pg-authentication"></a>

In Aurora DSQL umfasst die **Authentifizierung**:
+ **IAM-Authentifizierung**: alle Verbindungen verwenden eine IAM-basierte Authentifizierung mit zeitlich begrenzten Token
+ **Token-Generierung**: Der Connector generiert Authentifizierungstoken mithilfe von AWS Anmeldeinformationen, und diese Token haben eine konfigurierbare Lebensdauer

Der Aurora DSQL Connector for Ruby versteht diese Anforderungen und generiert beim Verbindungsaufbau automatisch IAM-Authentifizierungstoken.

### Features
<a name="SECTION_program-with-dsql-connector-for-ruby-pg-features"></a>
+ **Automatische IAM-Authentifizierung** — Übernimmt die Generierung und Aktualisierung von Aurora DSQL-Tokens
+ **Built on pg** — Umschließt das beliebte PostgreSQL-Gem für Ruby
+ **Nahtlose Integration** — Funktioniert mit bestehenden PG-Gem-Workflows
+ **Verbindungspooling** — Integrierte Unterstützung über das `connection_pool` Gem mit max\_lifetime-Durchsetzung
+ **Automatische Erkennung von Regionen** — Extrahiert die AWS Region aus dem Hostnamen des Aurora DSQL-Clusters
+ **AWS Unterstützung für Anmeldeinformationen** — Unterstützt AWS Profile und Anbieter von benutzerdefinierten Anmeldeinformationen
+ **OCC-Wiederholung** — Opt-In für optimistische Parallelitätssteuerung mit exponentiellem Backoff

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

[Ein vollständiges Beispiel finden Sie in der Beispielanwendung unter.](https://github.com/awslabs/aurora-dsql-connectors/tree/main/ruby/pg/example) GitHub

## Schnellstart-Anleitung
<a name="SECTION_program-with-dsql-connector-for-ruby-pg-quick-start"></a>

### Voraussetzungen
<a name="SECTION_program-with-dsql-connector-for-ruby-pg-requirements"></a>
+ Ruby 3.1 oder höher
+ [Zugriff auf einen Aurora DSQL-Cluster](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/getting-started.html)
+ AWS konfigurierte Anmeldeinformationen (über AWS CLI, Umgebungsvariablen oder IAM-Rollen)

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

Fügen Sie zu Ihrem Gemfile hinzu:

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

Oder direkt installieren:

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

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

### Verbindung zum Pool
<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
```

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

Für einfache Skripte oder wenn kein Verbindungspooling benötigt wird:

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

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

**Host-Konfiguration**

Der Connector unterstützt sowohl vollständige Cluster-Endpunkte (Region automatisch erkannt) als auch Cluster IDs (Region erforderlich):

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

Geben Sie ein AWS Profil für Anmeldeinformationen an:

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

**Format der Verbindungszeichenfolge**

Der Konnektor unterstützt PostgreSQL-Verbindungszeichenfolgenformate:

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

Unterstützte Abfrageparameter:`region`,,`profile`. `tokenDurationSecs`

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

**OCC-Wiederholung**

Aurora DSQL verwendet Optimistic Concurrency Control (OCC). Wenn zwei Transaktionen dieselben Daten ändern, gewinnt die erste Transaktion, die einen Commit durchführt, und die zweite erhält einen OCC-Fehler.

Die OCC-Wiederholung ist optional. `occ_max_retries`Wird bei der Erstellung des Pools so eingestellt, dass automatische Wiederholungen mit exponentiellem Backoff und aktiviertem Jitter aktiviert sind: `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
```

**Warnung**  
`pool.with`wickelt Ihren Block NICHT automatisch in eine Transaktion ein. Für Schreiboperationen müssen Sie `conn.transaction` sich selbst anrufen. Bei einem OCC-Konflikt führt der Konnektor den gesamten Block erneut aus, sodass er nur Datenbankoperationen enthalten sollte und ein erneuter Versuch sicher sein sollte.

Um den Wiederholungsversuch bei einzelnen Aufrufen zu überspringen, übergeben Sie: `retry_occ: false`

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

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


| Feld | Typ | Standard | Description | 
| --- | --- | --- | --- | 
| Host | Zeichenfolge | (erforderlich) | Cluster-Endpunkt oder Cluster-ID | 
| Region | Zeichenfolge | (automatisch erkannt) | AWS Region; erforderlich, wenn es sich bei dem Host um eine Cluster-ID handelt | 
| user | Zeichenfolge | „Administrator“ | Datenbankbenutzer | 
| Datenbank | Zeichenfolge | „Postgres“ | Datenbankname | 
| port | Ganzzahl | 5432 | Datenbankport | 
| Profil | Zeichenfolge | Null | AWS Profilname für Anmeldeinformationen | 
| token\_duration | Ganzzahl | 900 (15 Minuten) | Gültigkeitsdauer des Tokens in Sekunden (maximal zulässig: 1 Woche, Standard: 15 Minuten) | 
| credentials\_provider | Aws:: Anmeldeinformationen | Null | Anbieter für benutzerdefinierte Anmeldeinformationen | 
| max\_lifetime | Ganzzahl | 3300 (55 Minuten) | Maximale Verbindungslebensdauer in Sekunden | 
| application\_name | Zeichenfolge | Null | ORM-Präfix für application\_name | 
| Logger | Logger | Null | Logger für OCC-Wiederholungswarnungen | 
| occ\_max\_retries | Ganzzahl | nil (deaktiviert) | Max. OCC-Wiederholungsversuche aktiviertpool.with; aktiviert Wiederholungsversuche, wenn diese Einstellung gesetzt ist | 

`create_pool`akzeptiert auch ein `pool:` Schlüsselwort mit einem Hash von Optionen, an die Sie direkt übergeben werden. `ConnectionPool.new` Wenn Sie es weglassen`pool:`, ist der Connector standardmäßig auf. `{size: 5, timeout: 5}` Schlüssel, die Sie angeben, haben nur Vorrang vor diesen spezifischen Standardwerten.

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

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

Der Connector verarbeitet automatisch die Aurora-DSQL-Authentifizierung, indem er mithilfe von AWS Anmeldeinformationen Token generiert. Wenn Sie die AWS Region nicht angeben, analysiert der Connector sie anhand des Hostnamens.

Weitere Informationen zur Authentifizierung in Aurora DSQL finden Sie unter[Authentifizierung und Autorisierung für Aurora DSQL](authentication-authorization.md).

### Admin im Vergleich zu normalen Benutzern
<a name="SECTION_program-with-dsql-connector-for-ruby-pg-admin-vs-regular"></a>
+ Benutzer mit dem Namen „admin“ verwenden automatisch Admin-Authentifizierungstoken
+ Alle anderen Benutzer verwenden reguläre Authentifizierungstoken
+ Der Connector generiert dynamisch Token für jede Verbindung