Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

# Konektor Aurora DSQL untuk Ruby pg
<a name="SECTION_program-with-dsql-connector-for-ruby-pg"></a>

Konektor [Aurora DSQL untuk Ruby adalah konektor Ruby](https://github.com/awslabs/aurora-dsql-connectors/tree/main/ruby/pg) yang dibangun di atas [pg](https://github.com/ged/ruby-pg) yang mengintegrasikan otentikasi IAM untuk menghubungkan aplikasi Ruby ke cluster Amazon Aurora DSQL.

Konektor menangani pembuatan token, konfigurasi SSL, dan penyatuan koneksi sehingga Anda dapat fokus pada logika aplikasi Anda.

## Tentang konektornya
<a name="SECTION_program-with-dsql-connector-for-ruby-pg-about"></a>

Amazon Aurora DSQL memerlukan otentikasi IAM dengan token terbatas waktu yang tidak didukung oleh driver Ruby PostgreSQL yang ada. Konektor Aurora DSQL untuk Ruby menambahkan lapisan otentikasi di atas permata pg yang menangani pembuatan token IAM, memungkinkan Anda untuk terhubung ke Aurora DSQL tanpa mengubah alur kerja pg yang ada.

### Apa itu otentikasi Aurora DSQL?
<a name="SECTION_program-with-dsql-connector-for-ruby-pg-authentication"></a>

**Dalam Aurora DSQL, otentikasi melibatkan:**
+ **Otentikasi IAM**: Semua koneksi menggunakan otentikasi berbasis IAM dengan token terbatas waktu
+ **Generasi Token**: Konektor menghasilkan token otentikasi menggunakan AWS kredensil, dan token ini memiliki masa pakai yang dapat dikonfigurasi

Konektor Aurora DSQL untuk Ruby memahami persyaratan ini dan secara otomatis menghasilkan token otentikasi IAM saat membuat koneksi.

### Fitur
<a name="SECTION_program-with-dsql-connector-for-ruby-pg-features"></a>
+ **Otentikasi IAM otomatis** - Menangani pembuatan dan penyegaran token Aurora DSQL
+ **Dibangun di pg** - Membungkus permata PostgreSQL populer untuk Ruby
+ **Integrasi mulus** - Bekerja dengan alur kerja pg gem yang ada
+ **Penggabungan koneksi - Dukungan bawaan melalui `connection_pool` permata dengan penegakan** max\$1lifetime
+ **Deteksi otomatis wilayah** - Ekstrak AWS wilayah dari nama host cluster Aurora DSQL
+ AWS dukungan **kredensil - Mendukung** AWS profil dan penyedia kredensil khusus
+ Coba lagi **OCC - Coba lagi kontrol** konkurensi optimis dengan backoff eksponensial

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

Untuk contoh lengkap, lihat [contoh aplikasi](https://github.com/awslabs/aurora-dsql-connectors/tree/main/ruby/pg/example) di GitHub.

## Panduan memulai cepat
<a name="SECTION_program-with-dsql-connector-for-ruby-pg-quick-start"></a>

### Persyaratan
<a name="SECTION_program-with-dsql-connector-for-ruby-pg-requirements"></a>
+ Ruby 3.1 atau yang lebih baru
+ [Akses ke cluster Aurora DSQL](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/getting-started.html)
+ AWS kredensyal yang dikonfigurasi (melalui AWS CLI, variabel lingkungan, atau peran IAM)

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

Tambahkan ke Gemfile Anda:

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

Atau instal langsung:

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

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

### Koneksi kolam
<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
```

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

Untuk skrip sederhana atau saat penyatuan koneksi tidak diperlukan:

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

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

**Konfigurasi host**

Konektor mendukung titik akhir cluster penuh (wilayah terdeteksi secara otomatis) dan cluster IDs (wilayah diperlukan):

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

Tentukan AWS profil untuk kredensyal:

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

**Format string koneksi**

Konektor mendukung format string koneksi PostgreSQL:

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

Parameter kueri yang didukung:`region`,`profile`,`tokenDurationSecs`.

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

**Coba lagi OCC**

Aurora DSQL menggunakan kontrol konkurensi optimis (OCC). Ketika dua transaksi memodifikasi data yang sama, yang pertama melakukan kemenangan dan yang kedua menerima kesalahan OCC.

Coba lagi OCC adalah opt-in. Setel `occ_max_retries` saat membuat kumpulan untuk mengaktifkan percobaan ulang otomatis dengan backoff eksponensial dan jitter pada: `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
```

**Awas**  
`pool.with`TIDAK secara otomatis membungkus blok Anda dalam transaksi. Anda harus menelepon `conn.transaction` diri Anda sendiri untuk operasi menulis. Pada konflik OCC konektor mengeksekusi ulang seluruh blok, sehingga seharusnya hanya berisi operasi database dan aman untuk dicoba lagi.

Untuk melewati percobaan ulang pada panggilan individual, teruskan`retry_occ: false`:

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

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


| Bidang | Tipe | Default | Deskripsi | 
| --- | --- | --- | --- | 
| host | String | (wajib) | Titik akhir klaster atau ID klaster | 
| region | String | (terdeteksi secara otomatis) | AWS wilayah; diperlukan jika host adalah ID cluster | 
| user | String | “admin” | Pengguna basis data | 
| basis data | String | “postgres” | Nama basis data | 
| port | Bilangan Bulat | 5432 | Port basis data | 
| profile | String | kosong | AWS nama profil untuk kredensyal | 
| token\$1duration | Bilangan Bulat | 900 (15 menit) | Durasi validitas token dalam hitungan detik (maks diperbolehkan: 1 minggu, default: 15 menit) | 
| credentials\$1provider | Aws: :Kredensyal | kosong | Penyedia kredensyal kustom | 
| max\$1seumur hidup | Bilangan Bulat | 3300 (55 menit) | Masa pakai koneksi maksimum dalam hitungan detik | 
| application\$1name | String | kosong | Awalan ORM untuk application\$1name | 
| logger | Pencatat | kosong | Logger untuk peringatan coba lagi OCC | 
| occ\$1max\$1mencoba lagi | Bilangan Bulat | nil (dinonaktifkan) | Max OCC mencoba ulangpool.with; memungkinkan coba lagi saat disetel | 

`create_pool`juga menerima `pool:` kata kunci dengan hash opsi yang Anda berikan langsung ke. `ConnectionPool.new` Jika Anda menghilangkan`pool:`, konektor default ke. `{size: 5, timeout: 5}` Kunci yang Anda berikan hanya mengganti default tertentu tersebut.

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

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

Konektor secara otomatis menangani otentikasi Aurora DSQL dengan menghasilkan token menggunakan kredensil. AWS Jika Anda tidak menyediakan AWS wilayah, konektor menguraikannya dari nama host.

Untuk informasi lebih lanjut tentang otentikasi di Aurora DSQL, lihat. [Otentikasi dan otorisasi untuk Aurora DSQL](authentication-authorization.md)

### Admin vs pengguna biasa
<a name="SECTION_program-with-dsql-connector-for-ruby-pg-admin-vs-regular"></a>
+ Pengguna bernama “admin” secara otomatis menggunakan token otentikasi admin
+ Semua pengguna lain menggunakan token otentikasi reguler
+ Konektor menghasilkan token secara dinamis untuk setiap koneksi