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

# Menghubungkan ke cluster Aurora DSQL dengan konektor Go
<a name="SECTION_program-with-go-pgx-connector"></a>

[Konektor Aurora DSQL untuk Go](https://github.com/awslabs/aurora-dsql-connectors/tree/main/go/pgx) membungkus [pgx](https://github.com/jackc/pgx) dengan otentikasi IAM otomatis. Konektor menangani pembuatan token, konfigurasi SSL, dan manajemen koneksi sehingga Anda dapat fokus pada logika aplikasi Anda.

## Tentang konektornya
<a name="SECTION_program-with-go-pgx-connector-about"></a>

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

### Apa itu Autentikasi Aurora DSQL?
<a name="SECTION_program-with-go-pgx-connector-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 kredensyal, dan token ini memiliki masa pakai yang dapat dikonfigurasi

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

### Manfaat Konektor Aurora DSQL untuk Go
<a name="SECTION_program-with-go-pgx-connector-benefits"></a>

Konektor Aurora DSQL untuk Go memungkinkan Anda untuk terus menggunakan alur kerja pgx yang ada sambil mengaktifkan otentikasi IAM melalui:
+ **Generasi Token Otomatis**: Konektor menghasilkan token IAM secara otomatis untuk setiap koneksi
+ **Pengumpulan Koneksi**: Dukungan bawaan untuk `pgxpool` pembuatan token otomatis per koneksi
+ **Konfigurasi Fleksibel**: Dukungan untuk titik akhir penuh atau cluster IDs dengan deteksi otomatis wilayah
+ **AWS Credentials Support**: Mendukung AWS profil dan penyedia kredensyal khusus

## Fitur utama
<a name="SECTION_program-with-go-pgx-connector-features"></a>

Manajemen Token Otomatis  
Konektor menghasilkan token IAM secara otomatis untuk setiap koneksi baru menggunakan kredensyal yang telah diselesaikan sebelumnya.

Pengumpulan Koneksi  
Penggabungan koneksi melalui `pgxpool` pembuatan token otomatis per koneksi.

Konfigurasi Host Fleksibel  
Mendukung kedua titik akhir cluster penuh dan cluster IDs dengan deteksi wilayah otomatis.

Keamanan SSL  
SSL selalu diaktifkan dengan mode verify-full dan negosiasi TLS langsung.

## Prasyarat
<a name="SECTION_program-with-go-pgx-connector-prerequisites"></a>
+ Pergi 1.24 atau yang lebih baru
+ AWS kredensyal dikonfigurasi
+ Kluster Aurora DSQL

Konektor menggunakan rantai kredensi [default AWS SDK for Go v2, yang menyelesaikan kredensyal](https://docs.aws.amazon.com/sdk-for-go/v2/developer-guide/configure-gosdk.html#specifying-credentials) dengan urutan berikut:

1. Variabel lingkungan (AWS\$1ACCESS\$1KEY\$1ID, \$1ACCESS\$1KEY) AWS\$1SECRET

1. File kredensyal bersama (\$1/.aws/credentials)

1. File konfigurasi bersama (\$1/.aws/config)

1. Peran IAM untuk Amazon EC2/ECS/Lambda

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

Instal konektor menggunakan modul Go:

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

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

Contoh berikut menunjukkan cara membuat kolam koneksi dan mengeksekusi 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)
}
```

## Opsi konfigurasi
<a name="SECTION_program-with-go-pgx-connector-configuration"></a>

Konektor mendukung opsi konfigurasi berikut:


| 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 | 
| Pengguna | string | “admin” | Pengguna basis data | 
| Basis Data | string | “postgres” | Nama basis data | 
| Port | int | 5432 | Port basis data | 
| Profil | string | "" | AWS nama profil untuk kredensyal | 
| TokenDurationSecs | int | 900 (15 menit) | Durasi validitas token dalam hitungan detik (maks diperbolehkan: 1 minggu, default: 15 menit) | 
| MaxConns | int32 | 0 | Koneksi kolam maksimum (0 = pgxpool default) | 
| MinConns | int32 | 0 | Koneksi kolam minimum (0 = pgxpool default) | 
| MaxConnLifetime | Waktu.durasi | 55 menit | Masa pakai koneksi maksimum | 

## Format string koneksi
<a name="SECTION_program-with-go-pgx-connector-connection-string"></a>

Konektor mendukung format string koneksi PostgreSQL dan DSQL:

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

Parameter kueri yang didukung:
+ `region`- AWS wilayah
+ `profile`- nama AWS profil
+ `tokenDurationSecs`- Durasi validitas Token dalam hitungan detik

Contoh:

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

## Penggunaan lanjutan
<a name="SECTION_program-with-go-pgx-connector-advanced"></a>

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

Konektor mendukung dua format host:

**Titik akhir penuh** (wilayah terdeteksi secara otomatis):

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

**ID Cluster** (diperlukan wilayah):

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

### Penyetelan konfigurasi kolam
<a name="SECTION_program-with-go-pgx-connector-pool-tuning"></a>

Konfigurasikan kumpulan koneksi untuk beban kerja Anda:

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

### Penggunaan koneksi tunggal
<a name="SECTION_program-with-go-pgx-connector-single-connection"></a>

Untuk skrip sederhana atau saat penyatuan koneksi tidak diperlukan:

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

### Menggunakan AWS profil
<a name="SECTION_program-with-go-pgx-connector-aws-profiles"></a>

Tentukan AWS profil untuk kredensyal:

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

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

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

`occretry`Paket ini menyediakan pembantu untuk percobaan ulang otomatis dengan backoff eksponensial dan jitter. Instal dengan:

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

Gunakan `WithRetry` untuk penulisan transaksional:

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

Untuk pernyataan DDL atau tunggal, gunakan`ExecWithRetry`:

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

**penting**  
`WithRetry`mengelola`BEGIN`/`COMMIT`/`ROLLBACK`secara internal. Callback Anda menerima transaksi dan harus hanya berisi operasi database dan aman untuk dicoba lagi.

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

Untuk contoh dan kasus penggunaan yang lebih komprehensif, lihat contoh [Aurora DSQL Connector](https://github.com/awslabs/aurora-dsql-connectors/tree/main/go/pgx/example) for Go.


| Contoh | Deskripsi | 
| --- | --- | 
|  [example\$1preferred](https://github.com/awslabs/aurora-dsql-connectors/tree/main/go/pgx/example/src/example_preferred.go)  | Direkomendasikan: Kolam koneksi dengan kueri bersamaan | 
|  [transaksi](https://github.com/awslabs/aurora-dsql-connectors/tree/main/go/pgx/example/src/transaction)  | Penanganan transaksi dengan BEGIN/COMMIT/ROLLBACK | 
|  [occ\$1coba lagi](https://github.com/awslabs/aurora-dsql-connectors/tree/main/go/pgx/example/src/occ_retry)  | Menangani konflik OCC dengan backoff eksponensial | 
|  [connection\$1string](https://github.com/awslabs/aurora-dsql-connectors/tree/main/go/pgx/example/src/connection_string)  | Menggunakan string koneksi untuk konfigurasi |