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

適用於 Python 的 Aurora DSQL 連接器

Aurora DSQL Connector for Python 整合 IAM 身分驗證，以將 Python 應用程式連線至 Amazon Aurora DSQL 叢集。在內部，它會利用 psycopg、psycopg2 和非同步用戶端程式庫。

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

關於 連接器

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

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

什麼是 Aurora DSQL 身分驗證？

在 Aurora DSQL 中，身分驗證涉及：

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

功能

快速入門指南

要求

安裝

pip install aurora-dsql-python-connector

分別安裝 psycopg 或 psycopg2 或非同步

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。

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

基本使用

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)

僅使用主機

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

僅使用叢集 ID

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

請注意：

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

aws configure set region us-east-1

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

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)

連線字串

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

進階組態

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)

組態選項

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

使用適用於 Python 的 Aurora DSQL 連接器搭配連線集區

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

psycopg

對於 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

對於 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

對於 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)

身分驗證

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

如需 Aurora DSQL 中身分驗證的詳細資訊，請參閱 使用者指南。

管理員與一般使用者

範例

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

psycopg

範例 README

psycopg2

範例 README

asyncpg

範例 README