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

# Konektor Aurora DSQL untuk Python
<a name="SECTION_program-with-dsql-connector-for-python"></a>

 [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
<a name="about-the-connector"></a>

 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?
<a name="what-is-aurora-dsql-authentication"></a>

 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
<a name="features"></a>
+  **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
<a name="quick-start-guide"></a>

### Persyaratan
<a name="requirements"></a>
+  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
<a name="installation"></a>

```
pip install aurora-dsql-python-connector
```

#### Instal psycopg atau psycopg2 atau asyncpg secara terpisah
<a name="install-psycopg-or-psycopg2-or-asyncpg-separately"></a>

 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
<a name="basic-usage"></a>

#### psycopg
<a name="psycopg"></a>

```
    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
<a name="psycopg2"></a>

```
    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
<a name="asyncpg"></a>

```
    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
<a name="using-just-host"></a>

##### psycopg
<a name="psycopg-1"></a>

```
    import aurora_dsql_psycopg as dsql

    conn = dsql.connect("your-cluster.dsql.us-east-1.on.aws")
```

##### psycopg2
<a name="psycopg2-1"></a>

```
    import aurora_dsql_psycopg2 as dsql

    conn = dsql.connect("your-cluster.dsql.us-east-1.on.aws")
```

##### asyncpg
<a name="asyncpg-1"></a>

```
    import asyncio 
    import aurora_dsql_asyncpg as dsql 

    conn = await dsql.connect("your-cluster.dsql.us-east-1.on.aws")
```

#### Hanya menggunakan ID cluster
<a name="using-just-cluster-id"></a>

##### psycopg
<a name="psycopg-2"></a>

```
    import aurora_dsql_psycopg as dsql

    conn = dsql.connect("your-cluster")
```

##### psycopg2
<a name="psycopg2-2"></a>

```
    import aurora_dsql_psycopg2 as dsql

    conn = dsql.connect("your-cluster")
```

##### asyncpg
<a name="asyncpg-2"></a>

```
    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
<a name="psycopg-3"></a>

```
    import aurora_dsql_psycopg as dsql

    config = {
            "region": "us-east-1",
    }

    conn = dsql.connect("your-cluster", **config)
```

##### psycopg2
<a name="psycopg2-3"></a>

```
    import aurora_dsql_psycopg2 as dsql

    config = {
            "region": "us-east-1",
    }

    conn = dsql.connect("your-cluster", **config)
```

##### asyncpg
<a name="asyncpg-3"></a>

```
    import asyncio 
    import aurora_dsql_asyncpg as dsql 

    config = {
            "region": "us-east-1",
    }

    conn = await dsql.connect("your-cluster", **config)
```

### String Koneksi
<a name="connection-string"></a>

#### psycopg
<a name="psycopg-4"></a>

```
    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
<a name="psycopg2-4"></a>

```
    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
<a name="asyncpg-4"></a>

```
    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
<a name="advanced-configuration"></a>

#### psycopg
<a name="psycopg-5"></a>

```
    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
<a name="psycopg2-5"></a>

```
    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
<a name="asyncpg-5"></a>

```
    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
<a name="configuration-options"></a>


|  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\_credentials\_provider  |  CredentialProvider  |  Tidak  |  Penyedia kredensi AWS khusus  | 
|  profile  |  string  |  Tidak  |  Nama profil IAM. Default: default.  | 
|  token\_duration\_secs  |  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
<a name="using-the-aurora-dsql-connector-for-python-with-connection-pooling"></a>

 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
<a name="psycopg-6"></a>

 Untuk psycopg, konektor mengimplementasikan kelas koneksi bernama DSQLConnection yang dapat diteruskan langsung ke psycopg\_pool. 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\_lifetime** 

 Parameter max\_lifetime harus diatur ke kurang dari 3600 detik (satu jam), karena ini adalah durasi koneksi maksimum yang diizinkan oleh database Aurora DSQL. Menyetel max\_lifetime 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
<a name="psycopg2-6"></a>

 Untuk psycopg2, konektor menyediakan kelas bernama Aurora DSQLThreaded ConnectionPool yang mewarisi dari psycopg2.pool. ThreadedConnectionPool. DSQLThreadedConnectionPool Kelas Aurora hanya mengganti metode \_connect 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
<a name="asyncpg-6"></a>

 Untuk asyncpg, konektor menyediakan fungsi create\_pool 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
<a name="authentication"></a>

 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
<a name="admin-vs-regular-users"></a>
+  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
<a name="examples"></a>

 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
<a name="psycopg-7"></a>

 [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
<a name="psycopg2-7"></a>

 [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
<a name="asyncpg-7"></a>

 [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)  |