Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.
# Konektor untuk Aurora DSQL
Aurora DSQL menyediakan konektor khusus yang memperluas driver database yang ada untuk memungkinkan otentikasi dan integrasi IAM yang mulus dengan layanan. AWS Konektor ini dirancang untuk bekerja dengan bahasa dan kerangka kerja pemrograman populer sambil mempertahankan kompatibilitas dengan alur kerja PostgreSQL yang ada.
Konektor tambahan direncanakan untuk rilis masa depan. Untuk informasi terbaru tentang ketersediaan konektor, lihat repositori sampel [Aurora DSQL](https://github.com/aws-samples/aurora-dsql-samples).
# Menghubungkan ke cluster Aurora DSQL dengan konektor JDBC
[Konektor Aurora DSQL untuk JDBC dirancang sebagai plugin otentikasi yang memperluas fungsionalitas driver PostgreSQL](https://github.com/awslabs/aurora-dsql-connectors/tree/main/java/jdbc) JDBC untuk memungkinkan aplikasi mengautentikasi dengan Aurora DSQL menggunakan kredensil IAM. Konektor tidak terhubung langsung ke database, tetapi menyediakan otentikasi IAM yang mulus di atas driver PostgreSQL JDBC yang mendasarinya.
Konektor Aurora DSQL untuk JDBC dibangun untuk bekerja dengan Driver PostgreSQL JDBC dan menyediakan integrasi tanpa batas dengan persyaratan otentikasi [IAM Aurora DSQL](https://github.com/pgjdbc/pgjdbc).
Dalam hubungannya dengan PostgreSQL JDBC Driver, Aurora DSQL Connector untuk JDBC memungkinkan otentikasi berbasis IAM untuk Aurora DSQL. Ini memperkenalkan integrasi mendalam dengan layanan AWS otentikasi seperti [AWS Identity and Access Management](https://aws.amazon.com/iam/)(IAM).
## Tentang konektor
Aurora DSQL adalah layanan database SQL terdistribusi yang menyediakan ketersediaan dan skalabilitas tinggi untuk aplikasi yang kompatibel dengan PostgreSQL. Aurora DSQL memerlukan otentikasi berbasis IAM dengan token terbatas waktu yang tidak didukung oleh driver JDBC yang ada secara native.
Ide utama di balik Konektor Aurora DSQL untuk JDBC adalah menambahkan lapisan otentikasi di atas driver PostgreSQL JDBC yang menangani pembuatan token IAM, memungkinkan pengguna untuk terhubung ke Aurora DSQL tanpa mengubah alur kerja JDBC yang ada.
### Apa itu Autentikasi Aurora DSQL?
**Dalam Aurora DSQL, otentikasi melibatkan:**
+ **Otentikasi IAM**: Semua koneksi menggunakan otentikasi berbasis IAM dengan token terbatas waktu
+ **Pembuatan Token**: Token otentikasi dihasilkan menggunakan AWS kredensil dan memiliki masa pakai yang dapat dikonfigurasi
Konektor Aurora DSQL untuk JDBC dirancang untuk memahami persyaratan ini dan secara otomatis menghasilkan token otentikasi IAM saat membuat koneksi.
### Manfaat Konektor Aurora DSQL untuk JDBC
Meskipun Aurora DSQL menyediakan antarmuka yang kompatibel dengan PostgreSQL, driver PostgreSQL yang ada saat ini tidak mendukung persyaratan otentikasi IAM Aurora DSQL. Konektor Aurora DSQL untuk JDBC memungkinkan pelanggan untuk terus menggunakan alur kerja PostgreSQL yang ada sambil mengaktifkan otentikasi IAM melalui:
+ **Pembuatan Token Otomatis**: Token IAM dihasilkan secara otomatis menggunakan kredensil AWS
+ **Integrasi Seamless**: Bekerja dengan pola koneksi JDBC yang ada
+ **AWS Credentials Support**: Mendukung berbagai penyedia AWS kredensi (default, berbasis profil, dll.)
### Menggunakan Konektor Aurora DSQL untuk JDBC dengan penyatuan koneksi
Konektor Aurora DSQL untuk JDBC bekerja dengan pustaka penyatuan koneksi seperti HiKaricp. Konektor menangani pembuatan token IAM selama pembentukan koneksi, memungkinkan kumpulan koneksi beroperasi secara normal.
## Fitur utama
Pembuatan Token Otomatis
Token IAM dihasilkan secara otomatis menggunakan AWS kredensil.
Integrasi yang mulus
Bekerja dengan pola koneksi JDBC yang ada tanpa memerlukan perubahan alur kerja.
AWS Credentials Support
Mendukung berbagai penyedia AWS kredensi (default, berbasis profil, dll.).
Kompatibilitas Pengumpulan Koneksi
Bekerja mulus dengan pustaka penyatuan koneksi seperti HikariCP.
## Prasyarat
Sebelum Anda mulai, pastikan Anda telah menyelesaikan prasyarat berikut:
+ [Membuat cluster di Aurora DSQL](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/getting-started.html).
+ Menginstal Java Development Kit (JDK). Pastikan Anda memiliki versi 17 atau lebih tinggi.
+ Siapkan izin IAM yang sesuai untuk memungkinkan aplikasi Anda terhubung ke Aurora DSQL.
+ AWS kredensil dikonfigurasi (via AWS CLI, variabel lingkungan, atau peran IAM).
## Menggunakan Konektor Aurora DSQL untuk JDBC
Untuk menggunakan Konektor Aurora DSQL untuk JDBC di aplikasi Java Anda, ikuti langkah-langkah berikut:
1. Tambahkan dependensi berikut ke proyek Maven Anda:
```
software.amazon.dsql
aurora-dsql-jdbc-connector
1.0.0
```
Untuk proyek Gradle, tambahkan dependensi ini:
```
implementation("software.amazon.dsql:aurora-dsql-jdbc-connector:1.0.0")
```
1. Buat koneksi dasar ke cluster Aurora DSQL Anda menggunakan format konektor DSQL AWS PostgreSQL:
```
import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.ResultSet;
import java.sql.SQLException;
import java.sql.Statement;
public class DsqlJdbcConnectorExample {
public static void main(String[] args) {
// Using AWS DSQL PostgreSQL Connector prefix
String jdbcUrl = "jdbc:aws-dsql:postgresql://your-cluster.dsql.us-east-1.on.aws/postgres?user=admin";
try (Connection connection = DriverManager.getConnection(jdbcUrl)) {
// Use the connection
try (Statement statement = connection.createStatement()) {
// Create a table
statement.execute("CREATE TABLE IF NOT EXISTS test_table (id UUID PRIMARY KEY DEFAULT gen_random_uuid(), name VARCHAR(100))");
// Insert data
statement.execute("INSERT INTO test_table (name) VALUES ('Test Name')");
// Query data
try (ResultSet resultSet = statement.executeQuery("SELECT * FROM test_table")) {
while (resultSet.next()) {
System.out.println("ID: " + resultSet.getInt("id") + ", Name: " + resultSet.getString("name"));
}
}
}
} catch (SQLException e) {
e.printStackTrace();
}
}
}
```
### Properti konfigurasi
Konektor Aurora DSQL untuk JDBC mendukung properti koneksi berikut:
user
Menentukan pengguna untuk koneksi dan metode pembuatan token yang digunakan. Contoh: `admin`
token-duration-secs
Durasi dalam hitungan detik untuk validitas token. Untuk informasi selengkapnya tentang batas token, lihat [Membuat token otentikasi di Amazon Aurora](SECTION_authentication-token.md) DSQL.
profile
Digunakan untuk membuat instance ProfileCredentialsProvider untuk pembuatan token dengan nama profil yang disediakan.
region
AWS wilayah untuk koneksi Aurora DSQL. Ini opsional. Ketika disediakan, itu akan mengganti wilayah yang diekstrak dari URL.
basis data
Nama database untuk terhubung ke. Default-nya adalah `postgres`.
### Pencatatan log
Aktifkan pencatatan untuk memecahkan masalah apa pun yang mungkin Anda alami saat menggunakan konektor Aurora DSQL JDBC.
Konektor menggunakan sistem logging bawaan (java.util.logging) dari Java. Anda dapat mengonfigurasi level logging dengan membuat `logging.properties` file:
```
# Set root logger level to INFO for clean output
.level = INFO
# Show Aurora DSQL Connector for JDBC FINE logs for detailed debugging
software.amazon.dsql.level = FINE
# Console handler configuration
handlers = java.util.logging.ConsoleHandler
java.util.logging.ConsoleHandler.level = FINE
java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter
# Detailed formatter pattern with timestamp and logger name
java.util.logging.SimpleFormatter.format = %1$tH:%1$tM:%1$tS.%1$tL [%4$s] %3$s - %5$s%n
```
### Contoh
Untuk contoh dan kasus penggunaan yang lebih komprehensif, lihat Konektor [Aurora DSQL untuk repositori JDBC](https://github.com/awslabs/aurora-dsql-connectors/tree/main/java/jdbc/examples)
# Konektor Aurora DSQL untuk Python
[Konektor Aurora DSQL untuk Python mengintegrasikan Autentikasi IAM untuk menghubungkan aplikasi Python](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector) ke cluster Amazon Aurora DSQL. [Secara internal, ia menggunakan pustaka klien [psycopg, [psycopg2](https://github.com/psycopg/psycopg2)](https://github.com/psycopg/psycopg), dan asyncpg.](https://github.com/MagicStack/asyncpg)
Konektor Aurora DSQL untuk Python dirancang sebagai plugin otentikasi yang memperluas fungsionalitas pustaka klien psycopg, psycopg2, dan asyncpg untuk memungkinkan aplikasi mengautentikasi dengan Amazon Aurora DSQL menggunakan kredenal IAM. Konektor tidak terhubung langsung ke database tetapi menyediakan otentikasi IAM yang mulus di atas pustaka klien yang mendasarinya.
## Tentang Konektor
Amazon Aurora DSQL adalah layanan database SQL terdistribusi yang menyediakan ketersediaan dan skalabilitas tinggi untuk aplikasi yang kompatibel dengan PostgreSQL. Aurora DSQL memerlukan otentikasi berbasis IAM dengan token terbatas waktu yang tidak didukung oleh pustaka Python yang ada secara asli.
Ide di balik Konektor Aurora DSQL untuk Python adalah menambahkan lapisan otentikasi di atas pustaka klien psycopg, psycopg2, dan asyncpg yang menangani pembuatan token IAM, memungkinkan pengguna untuk terhubung ke Aurora DSQL tanpa mengubah alur kerja yang ada.
### Apa itu Autentikasi Aurora DSQL?
Dalam Aurora DSQL, otentikasi melibatkan:
+ **Otentikasi IAM:** Semua koneksi menggunakan otentikasi berbasis IAM dengan token terbatas waktu
+ **Pembuatan Token:** Token otentikasi dibuat menggunakan kredensi AWS dan memiliki masa pakai yang dapat dikonfigurasi
Konektor Aurora DSQL untuk Python dirancang untuk memahami persyaratan ini dan secara otomatis menghasilkan token otentikasi IAM saat membuat koneksi.
### Fitur
+ **Otentikasi IAM Otomatis** - Token IAM dihasilkan secara otomatis menggunakan kredensi AWS
+ **Dibangun di atas psycopg, psycopg2, dan asyncpg - Memanfaatkan pustaka klien psycopg, psycopg2, dan asyncpg**
+ **Integrasi Seamless** - Bekerja dengan pola koneksi psycopg, psycopg2, dan asyncpg yang ada tanpa memerlukan perubahan alur kerja
+ **Region Auto-Discovery** - Mengekstrak wilayah AWS dari nama host cluster DSQL
+ **AWS Credentials Support** - Mendukung berbagai penyedia kredensi AWS (default, berbasis profil, kustom)
+ **Kompatibilitas Pengumpulan Koneksi - Bekerja dengan pengumpulan koneksi** bawaan psycopg, psycopg2, dan asyncpg
## Panduan memulai cepat
### Persyaratan
+ Python 3.10 atau lebih tinggi
+ [Akses ke cluster Aurora DSQL](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/getting-started.html)
+ Siapkan izin IAM yang sesuai untuk memungkinkan aplikasi Anda terhubung ke Aurora DSQL.
+ Kredensi AWS dikonfigurasi (melalui AWS CLI, variabel lingkungan, atau peran IAM)
### Penginstalan
```
pip install aurora-dsql-python-connector
```
#### Instal psycopg atau psycopg2 atau asyncpg secara terpisah
Konektor Aurora DSQL untuk penginstal Python tidak menginstal pustaka yang mendasarinya. Mereka perlu diinstal secara terpisah, misalnya:
```
# Install psycopg and psycopg pool
pip install "psycopg[binary,pool]"
```
```
# Install psycopg2
pip install psycopg2-binary
```
```
# Install asyncpg
pip install asyncpg
```
**Catatan:**
Hanya perpustakaan yang dibutuhkan yang harus diinstal. Oleh karena itu, jika klien akan menggunakan psycopg, maka hanya psycopg yang perlu diinstal. Jika klien akan menggunakan psycopg2, maka hanya psycopg2 yang perlu diinstal. Jika klien akan menggunakan asyncpg, maka hanya asyncpg yang perlu diinstal.
Jika klien membutuhkan lebih dari satu, maka semua perpustakaan yang dibutuhkan perlu diinstal.
### Penggunaan Dasar
#### psycopg
```
import aurora_dsql_psycopg as dsql
config = {
'host': "your-cluster.dsql.us-east-1.on.aws",
'region': "us-east-1",
'user': "admin",
}
conn = dsql.connect(**config)
with conn.cursor() as cur:
cur.execute("SELECT 1")
result = cur.fetchone()
print(result)
```
#### psycopg2
```
import aurora_dsql_psycopg2 as dsql
config = {
'host': "your-cluster.dsql.us-east-1.on.aws",
'region': "us-east-1",
'user': "admin",
}
conn = dsql.connect(**config)
with conn.cursor() as cur:
cur.execute("SELECT 1")
result = cur.fetchone()
print(result)
```
#### asyncpg
```
import asyncio
import aurora_dsql_asyncpg as dsql
config = {
'host': "your-cluster.dsql.us-east-1.on.aws",
'region': "us-east-1",
'user': "admin",
}
conn = await dsql.connect(**config)
result = await conn.fetchrow("SELECT 1")
await conn.close()
print(result)
```
#### Hanya menggunakan host
##### psycopg
```
import aurora_dsql_psycopg as dsql
conn = dsql.connect("your-cluster.dsql.us-east-1.on.aws")
```
##### psycopg2
```
import aurora_dsql_psycopg2 as dsql
conn = dsql.connect("your-cluster.dsql.us-east-1.on.aws")
```
##### asyncpg
```
import asyncio
import aurora_dsql_asyncpg as dsql
conn = await dsql.connect("your-cluster.dsql.us-east-1.on.aws")
```
#### Hanya menggunakan ID cluster
##### psycopg
```
import aurora_dsql_psycopg as dsql
conn = dsql.connect("your-cluster")
```
##### psycopg2
```
import aurora_dsql_psycopg2 as dsql
conn = dsql.connect("your-cluster")
```
##### asyncpg
```
import asyncio
import aurora_dsql_asyncpg as dsql
conn = await dsql.connect("your-cluster")
```
**Catatan:**
Dalam skenario “hanya menggunakan ID cluster”, wilayah yang telah ditetapkan sebelumnya pada mesin digunakan, misalnya:
```
aws configure set region us-east-1
```
Jika wilayah belum disetel, atau ID cluster yang diberikan berada di wilayah yang berbeda, koneksi akan gagal. Untuk membuatnya berfungsi, berikan wilayah sebagai parameter seperti pada contoh di bawah ini:
##### psycopg
```
import aurora_dsql_psycopg as dsql
config = {
"region": "us-east-1",
}
conn = dsql.connect("your-cluster", **config)
```
##### psycopg2
```
import aurora_dsql_psycopg2 as dsql
config = {
"region": "us-east-1",
}
conn = dsql.connect("your-cluster", **config)
```
##### asyncpg
```
import asyncio
import aurora_dsql_asyncpg as dsql
config = {
"region": "us-east-1",
}
conn = await dsql.connect("your-cluster", **config)
```
### String Koneksi
#### psycopg
```
import aurora_dsql_psycopg as dsql
conn = dsql.connect("postgresql://your-cluster.dsql.us-east-1.on.aws/postgres?user=admin&token_duration_secs=15")
```
#### psycopg2
```
import aurora_dsql_psycopg2 as dsql
conn = dsql.connect("postgresql://your-cluster.dsql.us-east-1.on.aws/postgres?user=admin&token_duration_secs=15")
```
#### asyncpg
```
import asyncio
import aurora_dsql_asyncpg as dsql
conn = await dsql.connect("postgresql://your-cluster.dsql.us-east-1.on.aws/postgres?user=admin&token_duration_secs=15")
```
### Konfigurasi Lanjutan
#### psycopg
```
import aurora_dsql_psycopg as dsql
config = {
'host': "your-cluster.dsql.us-east-1.on.aws",
'region': "us-east-1",
'user': "admin",
"profile": "default",
"token_duration_secs": "15",
}
conn = dsql.connect(**config)
with conn.cursor() as cur:
cur.execute("SELECT 1")
result = cur.fetchone()
print(result)
```
#### psycopg2
```
import aurora_dsql_psycopg2 as dsql
config = {
'host': "your-cluster.dsql.us-east-1.on.aws",
'region': "us-east-1",
'user': "admin",
"profile": "default",
"token_duration_secs": "15",
}
conn = dsql.connect(**config)
with conn.cursor() as cur:
cur.execute("SELECT 1")
result = cur.fetchone()
print(result)
```
#### asyncpg
```
import asyncio
import aurora_dsql_asyncpg as dsql
config = {
'host': "your-cluster.dsql.us-east-1.on.aws",
'region': "us-east-1",
'user': "admin",
"profile": "default",
"token_duration_secs": "15",
}
conn = await dsql.connect(**config)
result = await conn.fetchrow("SELECT 1")
await conn.close()
print(result)
```
### Opsi konfigurasi
| Opsi | Tipe | Diperlukan | Deskripsi |
| --- | --- | --- | --- |
| host | string | Ya | Nama host cluster DSQL atau ID cluster |
| user | string | Tidak | Nama pengguna DSQL. Default: admin |
| dbname | string | Tidak | Nama basis data. Default: postgres |
| region | string | Tidak | Wilayah AWS (terdeteksi otomatis dari nama host jika tidak disediakan) |
| port | int | Tidak | Default ke 5432 |
| custom\$1credentials\$1provider | CredentialProvider | Tidak | Penyedia kredensi AWS khusus |
| profile | string | Tidak | Nama profil IAM. Default: default. |
| token\$1duration\$1secs | int | Tidak | Waktu kedaluwarsa token dalam hitungan detik |
****Semua opsi koneksi standar dari pustaka psycopg, psycopg2, dan asyncpg yang mendasarinya juga didukung, dengan pengecualian parameter asyncpg krbsrvname dan gsslib yang tidak didukung oleh DSQL.****
### Menggunakan konektor Aurora DSQL untuk Python dengan penyatuan koneksi
Konektor Aurora DSQL untuk Python bekerja dengan psycopg, psycopg2, dan asyncpg built-in connection pooling. Konektor menangani pembuatan token IAM selama pembentukan koneksi, memungkinkan kumpulan koneksi beroperasi secara normal.
#### psycopg
Untuk psycopg, konektor mengimplementasikan kelas koneksi bernama DSQLConnection yang dapat diteruskan langsung ke psycopg\$1pool. ConnectionPool konstruktor. Untuk operasi asinkron, ada juga versi async dari kelas bernama Connection. DSQLAsync
```
from psycopg_pool import ConnectionPool as PsycopgPool
...
pool = PsycopgPool(
"",
connection_class=dsql.DSQLConnection,
kwargs=conn_params,
min_size=2,
max_size=8,
max_lifetime=3300
)
```
**Catatan: Konfigurasi koneksi max\$1lifetime**
Parameter max\$1lifetime harus diatur ke kurang dari 3600 detik (satu jam), karena ini adalah durasi koneksi maksimum yang diizinkan oleh database Aurora DSQL. Menyetel max\$1lifetime yang lebih rendah memungkinkan kumpulan koneksi untuk secara proaktif mengelola daur ulang koneksi, yang lebih efisien daripada menangani kesalahan batas waktu koneksi dari database.
#### psycopg2
Untuk psycopg2, konektor menyediakan kelas bernama Aurora DSQLThreaded ConnectionPool yang mewarisi dari psycopg2.pool. ThreadedConnectionPool. DSQLThreadedConnectionPool Kelas Aurora hanya mengganti metode \$1connect internal. Sisa implementasi disediakan oleh psycopg2.pool. ThreadedConnectionPool tidak berubah.
```
import aurora_dsql_psycopg2 as dsql
pool = dsql.AuroraDSQLThreadedConnectionPool(
minconn=2,
maxconn=8,
**conn_params,
)
```
#### asyncpg
Untuk asyncpg, konektor menyediakan fungsi create\$1pool yang mengembalikan instance Asyncpg.pool.
```
import asyncio
import os
import aurora_dsql_asyncpg as dsql
pool_params = {
'host': "your-cluster.dsql.us-east-1.on.aws",
'user': "admin",
"min_size": 2,
"max_size": 5,
}
pool = await dsql.create_pool(**pool_params)
```
## Autentikasi
Konektor secara otomatis menangani otentikasi DSQL dengan menghasilkan token menggunakan generator token klien DSQL. Jika wilayah AWS tidak disediakan, wilayah AWS akan diurai secara otomatis dari nama host yang disediakan.
[Untuk informasi selengkapnya tentang otentikasi di Aurora DSQL, lihat panduan pengguna.](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/authentication-authorization.html)
### Admin vs Pengguna Reguler
+ Pengguna bernama `"admin"` secara otomatis menggunakan token otentikasi admin
+ Semua pengguna lain menggunakan token otentikasi non-admin
+ Token dihasilkan secara dinamis untuk setiap koneksi
## Contoh
Untuk kode contoh lengkap, lihat contoh seperti yang ditunjukkan pada bagian di bawah ini. Untuk petunjuk cara menjalankan contoh, silakan lihat contoh file READMDE.
### psycopg
[Contoh README](https://github.com/awslabs/aurora-dsql-connectors/blob/main/python/connector/examples/psycopg/README.md)
| Deskripsi | Contoh |
| --- | --- |
| Menggunakan Konektor Aurora DSQL untuk Python untuk koneksi dasar | [Contoh Koneksi Dasar](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/psycopg/src/example_preferred.py) |
| Menggunakan Konektor Aurora DSQL untuk Python untuk koneksi asinkron dasar | [Contoh Koneksi Asinkron Dasar](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/psycopg/src/alternatives/no_connection_pool/example_async_with_no_connection_pool.py) |
| Menggunakan Konektor Aurora DSQL untuk Python dengan kumpulan koneksi | [Contoh Koneksi Dasar Dengan Connection Pool](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/psycopg/src/alternatives/pool/example_with_nonconcurrent_connection_pool.py) |
| | [Contoh Koneksi Serentak Dengan Connection Pool](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/psycopg/src/example_preferred.py) |
| Menggunakan Konektor Aurora DSQL untuk Python dengan kumpulan koneksi asinkron | [Contoh Koneksi Dasar Dengan Kolam Koneksi Asinkron](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/psycopg/src/alternatives/pool/example_with_async_connection_pool.py) |
### psycopg2
[Contoh README](https://github.com/awslabs/aurora-dsql-connectors/blob/main/python/connector/examples/psycopg2/README.md)
| Deskripsi | Contoh |
| --- | --- |
| Menggunakan Konektor Aurora DSQL untuk Python untuk koneksi dasar | [Contoh Koneksi Dasar](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/psycopg2/src/example_preferred.py) |
| Menggunakan Konektor Aurora DSQL untuk Python dengan kumpulan koneksi | [Contoh Koneksi Dasar Dengan Connection Pool](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/psycopg2/src/alternatives/pool/example_with_nonconcurrent_connection_pool.py) |
| | [Contoh Koneksi Serentak Dengan Connection Pool](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/psycopg2/src/example_preferred.py) |
### asyncpg
[Contoh README](https://github.com/awslabs/aurora-dsql-connectors/blob/main/python/connector/examples/asyncpg/README.md)
| Deskripsi | Contoh |
| --- | --- |
| Menggunakan Konektor Aurora DSQL untuk Python untuk koneksi dasar | [Contoh Koneksi Dasar](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/asyncpg/src/example_preferred.py) |
| Menggunakan Konektor Aurora DSQL untuk Python dengan kumpulan koneksi | [Contoh Koneksi Dasar Dengan Connection Pool](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/asyncpg/src/alternatives/pool/example_with_nonconcurrent_connection_pool.py) |
| | [Contoh Koneksi Serentak Dengan Connection Pool](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/asyncpg/src/example_preferred.py) |
# Menghubungkan ke cluster Aurora DSQL dengan konektor Go
[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
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?
**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
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
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
+ 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
Instal konektor menggunakan modul Go:
```
go get github.com/awslabs/aurora-dsql-connectors/go/pgx/dsql
```
## Quick start
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
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
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
### Konfigurasi host
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
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
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
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
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
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 |
# Konektor Aurora DSQL untuk Node.js
Konektor Aurora DSQL untuk node-postgres dan Konektor Aurora DSQL untuk Postgres.js adalah plugin otentikasi yang memperluas fungsionalitas klien node-postgres dan Postgres.js untuk memungkinkan aplikasi mengautentikasi dengan Aurora DSQL menggunakan kredensil IAM.
# Konektor Aurora DSQL untuk node-postgres
Konektor [Aurora DSQL untuk node-postgres adalah konektor Node.js yang dibangun di atas [node-postgres](https://node-postgres.com/)](https://github.com/awslabs/aurora-dsql-connectors/tree/main/node/node-postgres) yang mengintegrasikan Autentikasi IAM untuk menghubungkan aplikasi ke cluster DSQL Amazon Aurora. JavaScript/TypeScript
Konektor Aurora DSQL dirancang sebagai plugin otentikasi yang memperluas fungsionalitas Klien dan Pool node-postgres untuk memungkinkan aplikasi mengautentikasi dengan Amazon Aurora DSQL menggunakan kredensil IAM.
## Tentang Konektor
Amazon Aurora DSQL adalah database terdistribusi cloud-native dengan kompatibilitas PostgreSQL. Meskipun memerlukan otentikasi IAM dan token terikat waktu, driver database Node.js tradisional tidak memiliki dukungan bawaan ini.
Konektor Aurora DSQL untuk node-postgres menjembatani kesenjangan ini dengan menerapkan middleware otentikasi yang bekerja mulus dengan node-postgres. Pendekatan ini memungkinkan pengembang untuk mempertahankan kode node-postgres mereka yang ada sambil mendapatkan akses berbasis IAM yang aman ke cluster Aurora DSQL melalui manajemen token otomatis.
### Apa itu Autentikasi Aurora DSQL?
Dalam Aurora DSQL, otentikasi melibatkan:
+ **Otentikasi IAM:** Semua koneksi menggunakan otentikasi berbasis IAM dengan token terbatas waktu
+ **Pembuatan Token:** Token otentikasi dibuat menggunakan kredensi AWS dan memiliki masa pakai yang dapat dikonfigurasi
Konektor Aurora DSQL untuk node-postgres dirancang untuk memahami persyaratan ini dan secara otomatis menghasilkan token otentikasi IAM saat membuat koneksi.
### Fitur
+ **Otentikasi IAM Otomatis** - Menangani pembuatan dan penyegaran token DSQL
+ **Dibangun di atas node-postgres** - Memanfaatkan klien PostgreSQL populer untuk Node.js
+ **Integrasi Seamless** - Bekerja dengan pola koneksi node-postgres yang ada
+ **Region Auto-Discovery** - Mengekstrak wilayah AWS dari nama host cluster DSQL
+ **Full TypeScript Support** - Menyediakan keamanan tipe penuh
+ **AWS Credentials Support** - Mendukung berbagai penyedia kredensi AWS (default, berbasis profil, kustom)
+ **Kompatibilitas Pengumpulan Koneksi** - Bekerja dengan mulus dengan penyatuan koneksi bawaan
## Contoh Aplikasi
Ada contoh aplikasi yang disertakan dalam [contoh](https://github.com/awslabs/aurora-dsql-connectors/tree/main/node/node-postgres/example) yang menunjukkan cara menggunakan Aurora DSQL Connector untuk node-postgres. Untuk menjalankan contoh yang disertakan, silakan lihat contoh [README](https://github.com/awslabs/aurora-dsql-connectors/blob/main/node/node-postgres/example/README.md).
## Panduan memulai cepat
### Persyaratan
+ Node.js 20\$1
+ [Akses ke cluster Aurora DSQL](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/getting-started.html)
+ Siapkan izin IAM yang sesuai untuk memungkinkan aplikasi Anda terhubung ke Aurora DSQL.
+ Kredensi AWS dikonfigurasi (melalui AWS CLI, variabel lingkungan, atau peran IAM)
## Penginstalan
```
npm install @aws/aurora-dsql-node-postgres-connector
```
## Dependensi Sebaya
```
npm install @aws-sdk/credential-providers @aws-sdk/dsql-signer pg tsx
npm install --save-dev @types/pg
```
## Penggunaan
### Koneksi Klien
```
import { AuroraDSQLClient } from "@aws/aurora-dsql-node-postgres-connector";
const client = new AuroraDSQLClient({
host: "",
user: "admin",
});
await client.connect();
const result = await client.query("SELECT NOW()");
await client.end();
```
### Koneksi Kolam
```
import { AuroraDSQLPool } from "@aws/aurora-dsql-node-postgres-connector";
const pool = new AuroraDSQLPool({
host: "",
user: "admin",
max: 3,
idleTimeoutMillis: 60000,
});
const result = await pool.query("SELECT NOW()");
```
### Penggunaan Lanjutan
```
import { fromNodeProviderChain } from "@aws-sdk/credential-providers";
import { AuroraDSQLClient } from "@aws/aurora-dsql-node-postgres-connector";
const client = new AuroraDSQLClient({
host: "example.dsql.us-east-1.on.aws",
user: "admin",
customCredentialsProvider: fromNodeProviderChain(), // Optionally provide custom credentials provider
});
await client.connect();
const result = await client.query("SELECT NOW()");
await client.end();
```
## Opsi konfigurasi
| Opsi | Tipe | Diperlukan | Deskripsi |
| --- | --- | --- | --- |
| host | string | Ya | Nama host kluster DSQL |
| username | string | Ya | Nama pengguna DSQL |
| database | string | Tidak | Nama basis data |
| region | string | Tidak | Wilayah AWS (terdeteksi secara otomatis dari nama host jika tidak disediakan) |
| port | number | Tidak | Default ke 5432 |
| customCredentialsProvider | AwsCredentialIdentity / AwsCredentialIdentityProvider | Tidak | Penyedia kredensi AWS kustom |
| profile | string | Tidak | Nama profil IAM. Default ke “default” |
| tokenDurationSecs | number | Tidak | Waktu kedaluwarsa token dalam hitungan detik |
Semua parameter lain dari [https://node-postgres.com/apis/client](https://node-postgres.com/apis/client) didukung.
## Autentikasi
Konektor secara otomatis menangani otentikasi DSQL dengan menghasilkan token menggunakan generator token klien DSQL. Jika wilayah AWS tidak disediakan, wilayah AWS akan diurai secara otomatis dari nama host yang disediakan.
[Untuk informasi selengkapnya tentang otentikasi di Aurora DSQL, lihat panduan pengguna.](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/authentication-authorization.html)
### Admin vs Pengguna Reguler
+ Pengguna bernama “admin” secara otomatis menggunakan token otentikasi admin
+ Semua pengguna lain menggunakan token otentikasi reguler
+ Token dihasilkan secara dinamis untuk setiap koneksi
# Konektor Aurora DSQL untuk Postgres.js
Konektor [Aurora DSQL untuk Postgres.js adalah konektor](https://github.com/awslabs/aurora-dsql-connectors/tree/main/node/postgres-js) Node.js yang dibangun di atas [Postgres.js](https://github.com/porsager/postgres) yang mengintegrasikan Autentikasi IAM untuk menghubungkan aplikasi ke JavaScript cluster Amazon Aurora DSQL.
Konektor Aurora DSQL untuk Postgres.js dirancang sebagai plugin otentikasi yang memperluas fungsionalitas klien Postgres.js untuk memungkinkan aplikasi mengautentikasi dengan Amazon Aurora DSQL menggunakan kredensil IAM. Konektor tidak terhubung langsung ke database, tetapi menyediakan otentikasi IAM yang mulus di atas driver Postgres.js yang mendasarinya.
## Tentang Konektor
Amazon Aurora DSQL adalah layanan database SQL terdistribusi yang menyediakan ketersediaan dan skalabilitas tinggi untuk aplikasi yang kompatibel dengan PostgreSQL. Aurora DSQL memerlukan otentikasi berbasis IAM dengan token terbatas waktu yang tidak didukung oleh driver Node.js yang ada secara native.
Ide di balik Konektor Aurora DSQL untuk Postgres.js adalah menambahkan lapisan otentikasi di atas klien Postgres.js yang menangani pembuatan token IAM, memungkinkan pengguna untuk terhubung ke Aurora DSQL tanpa mengubah alur kerja Postgres.js yang ada.
Konektor Aurora DSQL untuk Postgres.js bekerja dengan sebagian besar versi Postgres.js. Pengguna menyediakan versi mereka sendiri dengan menginstal Postgres.js secara langsung.
### Apa itu Autentikasi Aurora DSQL?
Dalam Aurora DSQL, otentikasi melibatkan:
+ **Otentikasi IAM:** Semua koneksi menggunakan otentikasi berbasis IAM dengan token terbatas waktu
+ **Pembuatan Token:** Token otentikasi dibuat menggunakan kredensi AWS dan memiliki masa pakai yang dapat dikonfigurasi
Konektor Aurora DSQL untuk Postgres.js dirancang untuk memahami persyaratan ini dan secara otomatis menghasilkan token otentikasi IAM saat membuat koneksi.
### Fitur
+ **Otentikasi IAM Otomatis** - Menangani pembuatan dan penyegaran token DSQL
+ **Dibangun di Postgres.js** - Memanfaatkan klien PostgreSQL cepat untuk Node.js
+ **Integrasi Seamless** - Bekerja dengan pola koneksi Postgres.js yang ada
+ **Region Auto-Discovery** - Mengekstrak wilayah AWS dari nama host cluster DSQL
+ **Full TypeScript Support** - Menyediakan keamanan tipe penuh
+ **AWS Credentials Support** - Mendukung berbagai penyedia kredensi AWS (default, berbasis profil, kustom)
+ **Kompatibilitas Pengumpulan Koneksi** - Bekerja dengan mulus dengan penyatuan koneksi bawaan Postgres.js
## Panduan memulai cepat
### Persyaratan
+ Node.js 20\$1
+ [Akses ke cluster Aurora DSQL](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/getting-started.html)
+ Siapkan izin IAM yang sesuai untuk memungkinkan aplikasi Anda terhubung ke Aurora DSQL.
+ Kredensi AWS dikonfigurasi (melalui AWS CLI, variabel lingkungan, atau peran IAM)
### Penginstalan
```
npm install @aws/aurora-dsql-postgresjs-connector
# Postgres.js is a peer-dependency, so users must install it themselves
npm install postgres
```
### Penggunaan Dasar
```
import { auroraDSQLPostgres } from '@aws/aurora-dsql-postgresjs-connector';
const sql = auroraDSQLPostgres({
host: 'your-cluster.dsql.us-east-1.on.aws',
username: 'admin',
});
// Execute queries
const result = await sql`SELECT current_timestamp`;
console.log(result);
// Clean up
await sql.end();
```
#### Menggunakan ID cluster alih-alih host
```
const sql = auroraDSQLPostgres({
host: 'your-cluster-id',
region: 'us-east-1',
username: 'admin',
});
```
### String Koneksi
```
const sql = AuroraDSQLPostgres(
'postgres://admin@your-cluster.dsql.us-east-1.on.aws'
);
const result = await sql`SELECT current_timestamp`;
```
### Konfigurasi Lanjutan
```
import { fromNodeProviderChain } from '@aws-sdk/credential-providers';
const sql = AuroraDSQLPostgres({
host: 'your-cluster.dsql.us-east-1.on.aws',
database: 'postgres',
username: 'admin',
customCredentialsProvider: fromNodeProviderChain(), // Optionally provide custom credentials provider
tokenDurationSecs: 3600, // Token expiration (seconds)
// Standard Postgres.js options
max: 20, // Connection pool size
ssl: { rejectUnauthorized: false } // SSL configuration
});
```
## Opsi konfigurasi
| Opsi | Tipe | Diperlukan | Deskripsi |
| --- | --- | --- | --- |
| host | string | Ya | Nama host cluster DSQL atau ID cluster |
| database | string? | Tidak | Nama basis data |
| username | string? | Tidak | Nama pengguna database (menggunakan admin jika tidak disediakan) |
| region | string? | Tidak | Wilayah AWS (terdeteksi secara otomatis dari nama host jika tidak disediakan) |
| customCredentialsProvider | AwsCredentialIdentityProvider? | Tidak | Penyedia kredensi AWS kustom |
| tokenDurationSecs | number? | Tidak | Waktu kedaluwarsa token dalam hitungan detik |
Semua [opsi Postgres.js](https://github.com/porsager/postgres?tab=readme-ov-file#connection-details) standar juga didukung.
## Autentikasi
Konektor secara otomatis menangani otentikasi DSQL dengan menghasilkan token menggunakan generator token klien DSQL. Jika wilayah AWS tidak disediakan, wilayah AWS akan diurai secara otomatis dari nama host yang disediakan.
[Untuk informasi selengkapnya tentang otentikasi di Aurora DSQL, lihat panduan pengguna.](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/authentication-authorization.html)
### Admin vs Pengguna Reguler
+ Pengguna bernama “admin” secara otomatis menggunakan token otentikasi admin
+ Semua pengguna lain menggunakan token otentikasi reguler
+ Token dihasilkan secara dinamis untuk setiap koneksi
## Penggunaan sampel
JavaScript contoh menggunakan Aurora DSQL Connector untuk Postgres.js tersedia di. GitHub Untuk petunjuk tentang cara menjalankan contoh, lihat [direktori examples](https://github.com/awslabs/aurora-dsql-connectors/tree/main/node/postgres-js/example).
| Deskripsi | Contoh |
| --- | --- |
| Penggabungan koneksi dengan kueri bersamaan, termasuk pembuatan tabel, penyisipan, dan pembacaan di beberapa pekerja | [Contoh kolam koneksi (lebih disukai)](https://github.com/awslabs/aurora-dsql-connectors/blob/main/node/postgres-js/example/src/example_preferred.js) |
| Operasi CRUD (buat tabel, sisipkan, pilih, hapus) tanpa penyatuan koneksi | [Contoh tanpa kolam koneksi](https://github.com/awslabs/aurora-dsql-connectors/blob/main/node/postgres-js/example/src/alternatives/no_connection_pool/example_with_no_connection_pool.js) |
# Menghubungkan ke cluster Aurora DSQL dengan konektor Ruby
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 konektor
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?
**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
+ **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
Untuk contoh lengkap, lihat [contoh aplikasi](https://github.com/awslabs/aurora-dsql-connectors/tree/main/ruby/pg/example) di GitHub.
## Panduan memulai cepat
### Persyaratan
+ 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
Tambahkan ke Gemfile Anda:
```
gem "aurora-dsql-ruby-pg"
```
Atau instal langsung:
```
gem install aurora-dsql-ruby-pg
```
## Penggunaan
### Koneksi kolam renang
```
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
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
**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
| Bidang | Tipe | Default | Deskripsi |
| --- | --- | --- | --- |
| host | String | (wajib) | Titik akhir cluster atau ID cluster |
| region | String | (terdeteksi 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 khusus |
| 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
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
+ Pengguna bernama “admin” secara otomatis menggunakan token otentikasi admin
+ Semua pengguna lain menggunakan token otentikasi reguler
+ Konektor menghasilkan token secara dinamis untuk setiap koneksi
# Menghubungkan ke cluster Aurora DSQL dengan konektor.NET
Konektor [DSQL Amazon Aurora untuk .NET adalah konektor.NET](https://github.com/awslabs/aurora-dsql-connectors/tree/main/dotnet/npgsql) yang dibangun di atas [Npgsql yang mengintegrasikan otentikasi IAM untuk menghubungkan aplikasi.NET ke cluster Amazon Aurora DSQL](https://www.npgsql.org/).
Konektor menangani pembuatan token, konfigurasi SSL, dan penyatuan koneksi sehingga Anda dapat fokus pada logika aplikasi Anda.
## Tentang konektornya
Amazon Aurora DSQL memerlukan otentikasi IAM dengan token terbatas waktu yang tidak didukung oleh driver.NET PostgreSQL yang ada. Konektor Aurora DSQL untuk.NET menambahkan lapisan otentikasi di atas Npgsql yang menangani pembuatan token IAM, memungkinkan Anda untuk terhubung ke Aurora DSQL tanpa mengubah alur kerja Npgsql yang ada.
### Apa itu otentikasi Aurora DSQL?
**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.NET memahami persyaratan ini dan secara otomatis menghasilkan token otentikasi IAM saat membuat koneksi.
### Fitur
+ **Otentikasi IAM otomatis** - Menangani pembuatan dan penyegaran token Aurora DSQL
+ **Dibangun di Npgsql - Membungkus driver PostgreSQL** populer untuk.NET
+ **Integrasi mulus** - Bekerja dengan alur kerja Npgsql yang ada
+ **Penggabungan koneksi** - Dukungan bawaan melalui `NpgsqlDataSource` dengan penegakan seumur hidup maksimal
+ **Deteksi otomatis wilayah** - Ekstrak AWS wilayah dari nama host cluster Aurora DSQL
+ AWS dukungan **kredensyal - Mendukung** AWS profil dan penyedia kredensyal khusus
+ Coba lagi **OCC - Coba lagi kontrol** konkurensi optimis dengan backoff eksponensial
+ **Penegakan SSL** - Selalu menggunakan SSL dengan `verify-full` mode dan negosiasi TLS langsung
## Contoh aplikasi
Untuk contoh lengkap, lihat [contoh aplikasi](https://github.com/awslabs/aurora-dsql-connectors/tree/main/dotnet/npgsql/example) di GitHub.
## Panduan memulai cepat
### Persyaratan
+ .NET 8.0 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
Tambahkan paket ke proyek Anda:
```
dotnet add package Amazon.AuroraDsql.Npgsql
```
## Penggunaan
### Koneksi kolam
```
using Amazon.AuroraDsql.Npgsql;
// Create a connection pool
await using var ds = await AuroraDsql.CreateDataSourceAsync(new DsqlConfig
{
Host = "your-cluster.dsql.us-east-1.on.aws",
OccMaxRetries = 3
});
// Read
await using (var conn = await ds.OpenConnectionAsync())
{
await using var cmd = conn.CreateCommand();
cmd.CommandText = "SELECT 'Hello, DSQL!'";
var greeting = await cmd.ExecuteScalarAsync();
Console.WriteLine(greeting);
}
// Transactional write with OCC retry
await ds.WithTransactionRetryAsync(async conn =>
{
await using var cmd = conn.CreateCommand();
cmd.CommandText = "INSERT INTO users (id, name) VALUES (gen_random_uuid(), @name)";
cmd.Parameters.AddWithValue("name", "Alice");
await cmd.ExecuteNonQueryAsync();
});
```
### Koneksi tunggal
Untuk skrip sederhana atau saat Anda tidak memerlukan penyatuan koneksi:
```
await using var conn = await AuroraDsql.ConnectAsync(new DsqlConfig
{
Host = "your-cluster.dsql.us-east-1.on.aws"
});
await using var cmd = conn.CreateCommand("SELECT 1");
await cmd.ExecuteScalarAsync();
```
### 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 `OccMaxRetries` dalam konfigurasi untuk mengaktifkan percobaan ulang otomatis dengan backoff eksponensial dan jitter. Gunakan `WithTransactionRetryAsync` untuk penulisan transaksional:
```
await ds.WithTransactionRetryAsync(async conn =>
{
await using var cmd = conn.CreateCommand();
cmd.CommandText = "UPDATE accounts SET balance = balance - 100 WHERE id = @from";
cmd.Parameters.AddWithValue("from", fromId);
await cmd.ExecuteNonQueryAsync();
cmd.CommandText = "UPDATE accounts SET balance = balance + 100 WHERE id = @to";
cmd.Parameters.Clear();
cmd.Parameters.AddWithValue("to", toId);
await cmd.ExecuteNonQueryAsync();
});
```
Untuk pernyataan DDL atau tunggal, gunakan`ExecWithRetryAsync`:
```
await ds.ExecWithRetryAsync("CREATE TABLE IF NOT EXISTS users (id UUID PRIMARY KEY, name TEXT)");
```
**penting**
`WithTransactionRetryAsync`mengelola`BEGIN`/`COMMIT`/`ROLLBACK`secara internal dan membuka koneksi baru untuk setiap upaya. Callback Anda seharusnya hanya berisi operasi database dan aman untuk dicoba lagi.
## Opsi konfigurasi
Konektor juga menerima `postgres://` dan `postgresql://` menghubungkan string dengan `region` dan `profile` parameter kueri.
| Bidang | Tipe | Default | Deskripsi |
| --- | --- | --- | --- |
| Host | string | (wajib) | Titik akhir cluster atau ID cluster 26-char |
| Region | string? | (terdeteksi secara otomatis) | AWS wilayah; diperlukan jika Host adalah ID cluster |
| User | string | "admin" | Pengguna basis data |
| Database | string | "postgres" | Nama basis data |
| Port | int | 5432 | Port basis data |
| Profile | string? | null | AWS nama profil untuk kredensyal |
| CustomCredentialsProvider | AWSCredentials? | null | Penyedia AWS kredensyal kustom |
| TokenDurationSecs | int? | null(SDK default, 900-an) | Durasi validitas token dalam hitungan detik |
| OccMaxRetries | int? | null(dinonaktifkan) | Percobaan ulang OCC maks default untuk metode coba lagi pada sumber data |
| OrmPrefix | string? | null | Awalan ORM diawali application\$1name |
| LoggerFactory | ILoggerFactory? | null | Pabrik logger untuk peringatan dan diagnostik coba lagi |
| ConfigureConnectionString | Action? | null | Callback untuk mengganti pengaturan pool atau mengatur properti string koneksi Npgsql tambahan. SSL dan Enlist merupakan invarian keamanan dan tidak dapat diganti. |
## Autentikasi
Konektor secara otomatis menangani otentikasi Aurora DSQL dengan menghasilkan token menggunakan kredensyal. 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
+ Pengguna bernama “admin” secara otomatis menggunakan token otentikasi admin
+ Semua pengguna lain menggunakan token otentikasi reguler
+ Konektor menghasilkan token secara dinamis untuk setiap koneksi