Python 用 Aurora DSQL コネクタ

Python 用 Aurora DSQL コネクタは、Python アプリケーションを Amazon Aurora DSQL クラスターに接続するための IAM 認証を統合します。内部的には、psycopg、psycopg2、および asyncpg クライアントライブラリを使用します。

Python 用 Aurora DSQL コネクタは psycopg、psycopg2、および asyncpg のクライアントライブラリ機能を拡張して、アプリケーションが IAM 認証情報を使用して Amazon Aurora DSQL で認証できるようにする認証プラグインとして設計されています。コネクタはデータベースに直接接続しませんが、基盤となるクライアントライブラリ上にシームレスな IAM 認証を提供します。

コネクタについて

Amazon Aurora DSQL は、PostgreSQL 互換アプリケーションに高可用性とスケーラビリティを提供する分散 SQL データベースサービスです。Aurora DSQL には、既存の Python ライブラリがネイティブにサポートしていない時間制限付きトークンを使用した IAM ベースの認証が必要です。

Python 用 Aurora DSQL コネクタの考え方は、IAM トークン生成を処理する psycopg、psycopg2、および asyncpg のクライアントライブラリの上に認証レイヤーを追加することです。これにより、ユーザーは既存のワークフローを変更せずに Aurora DSQL に接続できます。

Aurora DSQL 認証とは

Aurora DSQL では、認証に以下が含まれます。

Python 用 Aurora DSQL コネクタは、これらの要件を理解し、接続の確立時に IAM 認証トークンを自動的に生成するように設計されています。

機能

クイックスタートガイド

要件

インストール

pip install aurora-dsql-python-connector

psycopg、psycopg2 または asyncpg を個別にインストールする

Python 用 Aurora DSQL コネクタインストーラは、基盤となるライブラリをインストールしません。これらは、個別にインストールする必要があります。次に例を示します。

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

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

クラスター 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 コネクタの使用

Python 用 Aurora DSQL コネクタは、psycopg、psycopg2、および asyncpg の組み込み接続プーリングで動作します。コネクタは、接続の確立中に IAM トークンの生成を処理し、接続プールが正常に動作できるようにします。

psycopg

psycopg の場合、コネクタは psycopg_pool.ConnectionPool コンストラクタに直接渡すことができる DSQLConnection という名前の接続クラスを実装します。非同期オペレーションの場合、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
    )

注: Connection max_lifetime 設定

max_lifetime パラメータは、Aurora DSQL データベースで許可される最大接続時間であるため、3,600 秒 (1 時間) 未満に設定する必要があります。max_lifetime を低く設定すると、接続プールは接続リサイクルをプロアクティブに管理できます。これは、データベースからの接続タイムアウトエラーを処理するよりも効率的です。

psycopg2

psycopg2 の場合、コネクタは psycopg2.pool.ThreadedConnectionPool から継承する AuroraDSQLThreadedConnectionPool という名前のクラスを提供します。AuroraDSQLThreadedConnectionPool クラスは、内部 _connect メソッドのみを上書きします。残りの実装は、psycopg2.pool.ThreadedConnectionPool によって変更されずに提供されます。

    import aurora_dsql_psycopg2 as dsql

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

asyncpg

asyncpg の場合、コネクタは asyncpg.Pool のインスタンスを返す create_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 の例