本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 適用於 Python 的 Aurora DSQL 連接器
<a name="SECTION_program-with-dsql-connector-for-python"></a>

 [Aurora DSQL Connector for Python](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector) 整合 IAM 身分驗證，以將 Python 應用程式連線至 Amazon Aurora DSQL 叢集。在內部，它會利用 [psycopg](https://github.com/psycopg/psycopg)、[psycopg2](https://github.com/psycopg/psycopg2) 和非[同步用戶端](https://github.com/MagicStack/asyncpg)程式庫。

 Aurora DSQL Connector for Python 設計為身分驗證外掛程式，可延伸 psycopg、psycopg2 和非同步cpg 用戶端程式庫的功能，讓應用程式能夠使用 IAM 憑證向 Amazon Aurora DSQL 進行身分驗證。連接器不會直接連線至資料庫，而是在基礎用戶端程式庫之上提供無縫的 IAM 身分驗證。

## 關於 連接器
<a name="about-the-connector"></a>

 Amazon Aurora DSQL 是一種分散式 SQL 資料庫服務，可為 PostgreSQL 相容應用程式提供高可用性和可擴展性。Aurora DSQL 需要使用現有 Python 程式庫原生不支援的時間限制字符進行 IAM 型身分驗證。

 Aurora DSQL Connector for Python 背後的概念是在處理 IAM 字符產生的 psycopg、psycopg2 和非yncpg 用戶端程式庫上新增身分驗證層，讓使用者在不變更現有工作流程的情況下連線到 Aurora DSQL。

### 什麼是 Aurora DSQL 身分驗證？
<a name="what-is-aurora-dsql-authentication"></a>

 在 Aurora DSQL 中，身分驗證涉及：
+  **IAM 身分驗證**：所有連線都使用具有時間限制權杖的 IAM 型身分驗證 
+  **權杖產生：**使用 AWS 登入資料產生身分驗證權杖，並具有可設定的生命週期 

 Aurora DSQL Connector for Python 旨在了解這些要求，並在建立連線時自動產生 IAM 身分驗證字符。

### 功能
<a name="features"></a>
+  **自動 IAM 身分驗證** - 使用 AWS 登入資料自動產生 IAM 字符 
+  **以 psycopg、psycopg2 和 asyncpg** 為基礎 - 利用 psycopg、psycopg2 和非yncpg 用戶端程式庫 
+  **無縫整合** - 使用現有的 psycopg、psycopg2 和非同步連線模式，而不需要工作流程變更 
+  **Region Auto-Discovery** - 從 DSQL 叢集主機名稱擷取 AWS 區域 
+  **AWS 登入資料支援** - 支援各種 AWS 登入資料提供者 （預設、設定檔型、自訂） 
+  **連線集區相容性** - 適用於 psycopg、psycopg2 和非yncpg 內建連線集區 

## 快速入門指南
<a name="quick-start-guide"></a>

### 要求
<a name="requirements"></a>
+  Python 3.10 或更新版本 
+  [存取 Aurora DSQL 叢集](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/getting-started.html) 
+  設定適當的 IAM 權限，以允許應用程式連線到 Aurora DSQL。
+  已設定的 AWS 登入資料 （透過 AWS CLI、環境變數或 IAM 角色） 

### 安裝
<a name="installation"></a>

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

#### 分別安裝 psycopg 或 psycopg2 或非同步
<a name="install-psycopg-or-psycopg2-or-asyncpg-separately"></a>

 Aurora DSQL Connector for Python 安裝程式不會安裝基礎程式庫。它們需要單獨安裝，例如：

```
# Install psycopg and psycopg pool
pip install "psycopg[binary,pool]"
```

```
# Install psycopg2
pip install psycopg2-binary
```

```
# Install asyncpg
pip install asyncpg
```

 **請注意：**

 只需要安裝所需的程式庫。因此，如果用戶端要使用 psycopg，則只需要安裝 psycopg。如果用戶端將使用 psycopg2，則只需要安裝 psycopg2。如果用戶端將使用 asyncpg，則只需要安裝 asyncpg。

 如果用戶端需要多個程式庫，則需要安裝所有必要的程式庫。

### 基本使用
<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)
```

#### 僅使用主機
<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")
```

#### 僅使用叢集 ID
<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")
```

 **請注意：**

 在「僅使用叢集 ID」案例中，會使用先前在機器上設定的區域，例如：

```
aws configure set region us-east-1
```

 如果尚未設定區域，或指定的叢集 ID 位於不同的區域，連線將會失敗。若要讓它正常運作，請提供區域做為參數，如以下範例所示：

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

### 連線字串
<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")
```

### 進階組態
<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)
```

### 組態選項
<a name="configuration-options"></a>


|  選項  |  Type  |  必要  |  描述  | 
| --- | --- | --- | --- | 
|  host  |  string  |  是  |  DSQL 叢集主機名稱或叢集 ID  | 
|  user  |  string  |  否  |  DSQL 使用者名稱。預設：admin  | 
|  dbname  |  string  |  否  |  資料庫名稱。預設：Postgres  | 
|  region  |  string  |  否  |  AWS 區域 （若未提供，則從主機名稱自動偵測）  | 
|  port  |  int  |  否  |  預設為 5432  | 
|  custom\_credentials\_provider  |  CredentialProvider  |  否  |  自訂 AWS 登入資料提供者  | 
|  profile  |  string  |  否  |  IAM 設定檔名稱。預設：預設。 | 
|  token\_duration\_secs  |  int  |  否  |  字符過期時間，以秒為單位  | 

 也支援基礎 psycopg、psycopg2 和 asyncpg 程式庫的所有標準連線選項，但 DSQL 不支援的 asyncpg 參數 **krbsrvname** 和 **gsslib** 除外。

### 使用適用於 Python 的 Aurora DSQL 連接器搭配連線集區
<a name="using-the-aurora-dsql-connector-for-python-with-connection-pooling"></a>

 Aurora DSQL Connector for Python 適用於 psycopg、psycopg2 和非同步內建連線集區。連接器會在連線建立期間，處理 IAM 權杖的產生，讓連線集區能正常運作。

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

 對於 psycopg，連接器會實作名為 DSQLConnection 的連線類別，可直接傳遞至 psycopg\_pool.ConnectionPool 建構函數。對於非同步操作，也有名為 DSQLAsyncConnection 之類別的非同步版本。

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

 **注意：連線 max\_lifetime 組態** 

 max\_lifetime 參數應設定為小於 3600 秒 （一小時），因為這是 Aurora DSQL 資料庫允許的最長連線持續時間。設定較低的 max\_lifetime 可讓連線集區主動管理連線回收，這比處理資料庫的連線逾時錯誤更有效率。

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

 對於 psycopg2，連接器提供名為 AuroraDSQLThreadedConnectionPool 的類別，繼承自 psycopg2.pool.ThreadedConnectionPool。AuroraDSQLThreadedConnectionPool 類別只會覆寫內部 \_connect 方法。其餘實作由 psycopg2.pool.ThreadedConnectionPool 提供，保持不變。

```
    import aurora_dsql_psycopg2 as dsql

    pool = dsql.AuroraDSQLThreadedConnectionPool(
            minconn=2,
            maxconn=8,
            **conn_params,
    )
```

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

 對於 asyncpg，連接器提供 create\_pool 函數，其會傳回 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)
```

## 身分驗證
<a name="authentication"></a>

 連接器會自動處理 DSQL 身分驗證，方法是使用 DSQL 用戶端字符產生器產生字符。如果未提供 AWS 區域，則會自動從提供的主機名稱剖析。

 如需 Aurora DSQL 中身分驗證的詳細資訊，請參閱 [使用者指南](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/authentication-authorization.html)。

### 管理員與一般使用者
<a name="admin-vs-regular-users"></a>
+  名為 的使用者`"admin"`會自動使用管理員身分驗證字符 
+  所有其他使用者都使用非管理員身分驗證字符 
+  權杖會為每個連線動態產生 

## 範例
<a name="examples"></a>

 如需完整的範例程式碼，請參閱以下各節中所示的範例。如需如何執行範例的說明，請參閱範例 READMDE 檔案。

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

 [範例 README](https://github.com/awslabs/aurora-dsql-connectors/blob/main/python/connector/examples/psycopg/README.md) 


|  Description  |  範例  | 
| --- | --- | 
|  使用適用於 Python 的 Aurora DSQL 連接器進行基本連線  |  [基本連線範例](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/psycopg/src/example_preferred.py)  | 
|  使用適用於 Python 的 Aurora DSQL 連接器進行基本非同步連線  |  [基本非同步連線範例](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)  | 
|  搭配連線集區使用適用於 Python 的 Aurora DSQL 連接器  |  [使用連線集區的基本連線範例](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/psycopg/src/alternatives/pool/example_with_nonconcurrent_connection_pool.py)  | 
|   |  [與連線集區的並行連線範例](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/psycopg/src/example_preferred.py)  | 
|  將適用於 Python 的 Aurora DSQL 連接器與非同步連線集區搭配使用  |  [使用非同步連線集區的基本連線範例](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>

 [範例 README](https://github.com/awslabs/aurora-dsql-connectors/blob/main/python/connector/examples/psycopg2/README.md) 


|  Description  |  範例  | 
| --- | --- | 
|  使用適用於 Python 的 Aurora DSQL 連接器進行基本連線  |  [基本連線範例](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/psycopg2/src/example_preferred.py)  | 
|  搭配連線集區使用適用於 Python 的 Aurora DSQL 連接器  |  [使用連線集區的基本連線範例](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/psycopg2/src/alternatives/pool/example_with_nonconcurrent_connection_pool.py)  | 
|   |  [與連線集區的並行連線範例](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/psycopg2/src/example_preferred.py)  | 

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

 [範例 README](https://github.com/awslabs/aurora-dsql-connectors/blob/main/python/connector/examples/asyncpg/README.md) 


|  Description  |  範例  | 
| --- | --- | 
|  使用適用於 Python 的 Aurora DSQL 連接器進行基本連線  |  [基本連線範例](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/asyncpg/src/example_preferred.py)  | 
|  搭配連線集區使用適用於 Python 的 Aurora DSQL 連接器  |  [使用連線集區的基本連線範例](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/asyncpg/src/alternatives/pool/example_with_nonconcurrent_connection_pool.py)  | 
|   |  [與連線集區的並行連線範例](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/asyncpg/src/example_preferred.py)  |