# Python 用 Aurora DSQL コネクタ
<a name="SECTION_program-with-dsql-connector-for-python"></a>

 [Python 用 Aurora DSQL コネクタ](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector)は、Python アプリケーションを Amazon Aurora DSQL クラスターに接続するための IAM 認証を統合します。内部的には、[psycopg](https://github.com/psycopg/psycopg)、[psycopg2](https://github.com/psycopg/psycopg2)、および [asyncpg](https://github.com/MagicStack/asyncpg) クライアントライブラリを使用します。

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

## コネクタについて
<a name="about-the-connector"></a>

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

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

### Aurora DSQL 認証とは
<a name="what-is-aurora-dsql-authentication"></a>

 Aurora DSQL では、認証に以下が含まれます。
+  **IAM 認証**: すべての接続で、時間制限付きトークンによる IAM ベースの認証が使用されます 
+  **トークン生成:** 認証トークンは AWS 認証情報を使用して生成され、設定可能な有効期間があります 

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

### 機能
<a name="features"></a>
+  **自動 IAM 認証** - AWS 認証情報を使用して IAM トークンを自動的に生成 
+  **psycopg、psycopg2、および asyncpg 上に構築** - psycopg、psycopg2、および asyncpg クライアントライブラリを活用 
+  **シームレスな統合** - ワークフローの変更を必要とせずに、既存の psycopg、psycopg2、および asyncpg 接続パターンと連携 
+  **リージョンの自動検出** - DSQL クラスターホスト名から AWS リージョンを抽出 
+  **AWS 認証情報のサポート**: さまざまな認証情報プロバイダー (デフォルト、プロファイルベース、カスタム) をサポート 
+  **接続プーリングの互換性** - psycopg、psycopg2、および asyncpg の組み込み接続プーリングで動作 

## クイックスタートガイド
<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) 
+  アプリケーションが Aurora DSQL に接続できるように、適切な IAM アクセス許可を設定します。
+  AWS 認証情報の設定 (AWS CLI、環境変数、または IAM ロール経由) 

### インストール
<a name="installation"></a>

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

#### psycopg、psycopg2 または asyncpg を個別にインストールする
<a name="install-psycopg-or-psycopg2-or-asyncpg-separately"></a>

 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 のみをインストールする必要があります。

 クライアントに複数のライブラリが必要な場合は、必要なライブラリをすべてインストールする必要があります。

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

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

#### クラスター 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>


|  オプション  |  タイプ  |  必須  |  説明  | 
| --- | --- | --- | --- | 
|  host  |  string  |  はい  |  DSQL クラスターホスト名またはクラスター ID  | 
|  user  |  string  |  いいえ  |  DSQL ユーザー名。デフォルト: admin  | 
|  dbname  |  string  |  いいえ  |  データベース名。デフォルト: postgres  | 
|  region  |  string  |  いいえ  |  AWS リージョン (指定されていない場合はホスト名から自動検出)  | 
|  port  |  int  |  いいえ  |  デフォルトは 5432  | 
|  custom\$1credentials\$1provider  |  CredentialProvider  |  いいえ  |  カスタム AWS 認証情報プロバイダー  | 
|  profile  |  string  |  いいえ  |  IAM プロファイル名。デフォルト: default。 | 
|  token\$1duration\$1secs  |  int  |  いいえ  |  トークンの有効期限の秒数  | 

 基盤となる psycopg、psycopg2、および asyncpg ライブラリのすべての標準接続オプションもサポートされます。ただし、DSQL でサポートされていない asyncpg パラメータ **krbsrvname** と **gsslib** は除きます。

### 接続プーリングでの Python 用 Aurora DSQL コネクタの使用
<a name="using-the-aurora-dsql-connector-for-python-with-connection-pooling"></a>

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

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

 psycopg の場合、コネクタは psycopg\$1pool.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\$1lifetime 設定** 

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

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

 psycopg2 の場合、コネクタは psycopg2.pool.ThreadedConnectionPool から継承する AuroraDSQLThreadedConnectionPool という名前のクラスを提供します。AuroraDSQLThreadedConnectionPool クラスは、内部 \$1connect メソッドのみを上書きします。残りの実装は、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 の場合、コネクタは asyncpg.Pool のインスタンスを返す create\$1pool 関数を提供します。

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


|  説明  |  例  | 
| --- | --- | 
|  基本的な接続での 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) 


|  説明  |  例  | 
| --- | --- | 
|  基本的な接続での 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) 


|  説明  |  例  | 
| --- | --- | 
|  基本的な接続での 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)  |