Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

# Connecteur SQL Aurora pour Python
<a name="SECTION_program-with-dsql-connector-for-python"></a>

 Le [connecteur SQL Aurora pour Python](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector) intègre l'authentification IAM pour connecter les applications Python aux clusters Amazon Aurora DSQL. [En interne, il utilise les bibliothèques clientes [psycopg](https://github.com/psycopg/psycopg), [psycopg2](https://github.com/psycopg/psycopg2) et asyncpg.](https://github.com/MagicStack/asyncpg) 

 Le connecteur SQL Aurora pour Python est conçu comme un plug-in d'authentification qui étend les fonctionnalités des bibliothèques clientes psycopg, psycopg2 et asyncpg afin de permettre aux applications de s'authentifier auprès d'Amazon Aurora DSQL à l'aide des informations d'identification IAM. Le connecteur ne se connecte pas directement à la base de données mais fournit une authentification IAM fluide en plus des bibliothèques clientes sous-jacentes. 

## À propos du connecteur
<a name="about-the-connector"></a>

 Amazon Aurora DSQL est un service de base de données SQL distribué qui fournit une disponibilité et une évolutivité élevées aux applications compatibles avec PostgreSQL. Aurora DSQL nécessite une authentification basée sur IAM avec des jetons limités dans le temps que les bibliothèques Python existantes ne prennent pas en charge de manière native. 

 L'idée du connecteur Aurora DSQL pour Python est d'ajouter une couche d'authentification au-dessus des bibliothèques clientes psycopg, psycopg2 et asyncpg qui gère la génération de jetons IAM, permettant aux utilisateurs de se connecter à Aurora DSQL sans modifier leurs flux de travail existants. 

### Qu’est-ce que l’authentification Aurora DSQL ?
<a name="what-is-aurora-dsql-authentication"></a>

 Dans Aurora DSQL, l’authentification implique : 
+  **Authentification IAM** : toutes les connexions utilisent l’authentification basée sur IAM avec des jetons à durée limitée 
+  **Génération de jetons :** les jetons d'authentification sont générés à l'aide des informations d'identification AWS et ont une durée de vie configurable 

 Le connecteur Aurora DSQL pour Python est conçu pour comprendre ces exigences et générer automatiquement des jetons d'authentification IAM lors de l'établissement de connexions. 

### Caractéristiques
<a name="features"></a>
+  **Authentification IAM automatique** : les jetons IAM sont générés automatiquement à l'aide des informations d'identification AWS 
+  **Construit sur psycopg, psycopg2 et asyncpg : exploite les bibliothèques clientes psycopg, psycopg2 et asyncpg** 
+  **Intégration fluide** : fonctionne avec les modèles de connexion psycopg, psycopg2 et asyncpg existants sans modification du flux de travail 
+  **Découverte automatique des régions** : extrait la région AWS du nom d'hôte du cluster DSQL 
+  **Support des informations d'identification AWS** : prend en charge différents fournisseurs d'informations d'identification AWS (par défaut, basé sur le profil, personnalisé) 
+  **Compatibilité avec le regroupement de connexions** : fonctionne avec le regroupement de connexions intégré à psycopg, psycopg2 et asyncpg 

## Guide de démarrage rapide
<a name="quick-start-guide"></a>

### Exigences
<a name="requirements"></a>
+  Python 3.10 ou supérieur 
+  [Accès à un cluster SQL Aurora](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/getting-started.html) 
+  Configuration des autorisations IAM appropriées pour permettre à votre application de se connecter à Aurora DSQL. 
+  Informations d'identification AWS configurées (via l'interface de ligne de commande AWS, les variables d'environnement ou les rôles IAM) 

### Installation
<a name="installation"></a>

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

#### Installez psycopg ou psycopg2 ou asyncpg séparément
<a name="install-psycopg-or-psycopg2-or-asyncpg-separately"></a>

 Le programme d'installation d'Aurora DSQL Connector pour Python n'installe pas les bibliothèques sous-jacentes. Ils doivent être installés séparément, par exemple : 

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

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

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

 **Remarque :** 

 Seule la bibliothèque nécessaire doit être installée. Par conséquent, si le client doit utiliser psycopg, seul psycopg doit être installé. Si le client doit utiliser psycopg2, seul psycopg2 doit être installé. Si le client doit utiliser asyncpg, seul asyncpg doit être installé. 

 Si le client en a besoin de plusieurs, toutes les bibliothèques nécessaires doivent être installées. 

### Utilisation de base
<a name="basic-usage"></a>

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

#### En utilisant uniquement l'hôte
<a name="using-just-host"></a>

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

#### En utilisant uniquement l'ID du cluster
<a name="using-just-cluster-id"></a>

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

 **Remarque :** 

 Dans le scénario « en utilisant uniquement l'identifiant du cluster », la région précédemment définie sur la machine est utilisée, par exemple : 

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

 Si la région n'a pas été définie ou si l'ID de cluster indiqué se trouve dans une autre région, la connexion échouera. Pour que cela fonctionne, indiquez la région en tant que paramètre, comme dans l'exemple ci-dessous : 

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

### Chaîne de connexion
<a name="connection-string"></a>

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

### Configuration avancée
<a name="advanced-configuration"></a>

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

### Options de configuration
<a name="configuration-options"></a>


|  Option  |  Type  |  Obligatoire  |  Description  | 
| --- | --- | --- | --- | 
|  host  |  string  |  Oui  |  Nom d'hôte ou ID de cluster DSQL  | 
|  user  |  string  |  Non  |  Nom d'utilisateur DSQL. Par défaut : admin  | 
|  dbname  |  string  |  Non  |  Nom de la base de données. Par défaut : postgres  | 
|  region  |  string  |  Non  |  Région AWS (détectée automatiquement à partir du nom d'hôte s'il n'est pas fourni)  | 
|  port  |  int  |  Non  |  Par défaut : 5432  | 
|  custom\_credentials\_provider  |  CredentialProvider  |  Non  |  Fournisseur d'informations d'identification AWS personnalisées  | 
|  profile  |  string  |  Non  |  Le nom du profil IAM. Par défaut : par défaut.  | 
|  token\_duration\_secs  |  int  |  Non  |  Délai d'expiration du jeton en secondes  | 

 **Toutes les options de connexion standard des bibliothèques psycopg, psycopg2 et asyncpg sous-jacentes sont également prises en charge, à l'exception des paramètres asyncpg **krbsrvname** et gsslib qui ne sont pas pris en charge par DSQL.** 

### Utilisation du connecteur SQL Aurora pour Python avec regroupement de connexions
<a name="using-the-aurora-dsql-connector-for-python-with-connection-pooling"></a>

 Le connecteur SQL Aurora pour Python fonctionne avec le regroupement de connexions intégré psycopg, psycopg2 et asyncpg. Le connecteur gère la génération de jetons IAM lors de l’établissement de la connexion, ce qui permet aux groupes de connexions de fonctionner normalement. 

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

 Pour psycopg, le connecteur implémente une classe de connexion nommée DSQLConnection qui peut être transmise directement au psycopg\_pool. ConnectionPool constructeur. Pour les opérations asynchrones, il existe également une version asynchrone de la classe nommée 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
    )
```

 **Remarque : Configuration max\_lifetime de la connexion** 

 Le paramètre max\_lifetime doit être défini sur moins de 3 600 secondes (une heure), car il s'agit de la durée de connexion maximale autorisée par la base de données Aurora DSQL. La définition d'une valeur max\_lifetime inférieure permet au pool de connexions de gérer de manière proactive le recyclage des connexions, ce qui est plus efficace que la gestion des erreurs de délai de connexion provenant de la base de données. 

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

 Pour psycopg2, le connecteur fournit une classe nommée Aurora DSQLThreaded ConnectionPool qui hérite de psycopg2.pool. ThreadedConnectionPool. La DSQLThreaded ConnectionPool classe Aurora remplace uniquement la méthode interne \_connect. Le reste de l'implémentation est fourni par psycopg2.pool. ThreadedConnectionPool inchangé. 

```
    import aurora_dsql_psycopg2 as dsql

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

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

 Pour asyncpg, le connecteur fournit une fonction create\_pool qui renvoie une instance de 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)
```

## Authentification
<a name="authentication"></a>

 Le connecteur gère automatiquement l'authentification DSQL en générant des jetons à l'aide du générateur de jetons du client DSQL. Si la région AWS n'est pas fournie, elle sera automatiquement analysée à partir du nom d'hôte fourni. 

 Pour plus d'informations sur l'authentification dans Aurora DSQL, consultez le [guide de l'utilisateur](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/authentication-authorization.html). 

### Administrateur et utilisateurs réguliers
<a name="admin-vs-regular-users"></a>
+  Les utilisateurs nommés utilisent `"admin"` automatiquement des jetons d'authentification d'administrateur 
+  Tous les autres utilisateurs utilisent des jetons d'authentification non administrateurs 
+  Les jetons sont générés dynamiquement pour chaque connexion 

## Exemples
<a name="examples"></a>

 Pour un exemple de code complet, reportez-vous aux exemples indiqués dans les sections ci-dessous. Pour savoir comment exécuter les exemples, reportez-vous aux exemples de fichiers READMDE. 

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

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


|  Description  |  Exemples  | 
| --- | --- | 
|  Utilisation du connecteur Aurora DSQL pour Python pour les connexions de base  |  [Exemple de connexion de base](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/psycopg/src/example_preferred.py)  | 
|  Utilisation du connecteur Aurora DSQL pour Python pour les connexions asynchrones de base  |  [Exemple de connexion asynchrone de base](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)  | 
|  Utilisation du connecteur Aurora DSQL pour Python avec un pool de connexions  |  [Exemple de connexion de base avec un pool de connexions](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/psycopg/src/alternatives/pool/example_with_nonconcurrent_connection_pool.py)  | 
|   |  [Exemple de connexions simultanées avec pool de connexions](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/psycopg/src/example_preferred.py)  | 
|  Utilisation du connecteur SQL Aurora pour Python avec un pool de connexions asynchrones  |  [Exemple de connexion de base avec un pool de connexions asynchrones](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>

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


|  Description  |  Exemples  | 
| --- | --- | 
|  Utilisation du connecteur Aurora DSQL pour Python pour les connexions de base  |  [Exemple de connexion de base](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/psycopg2/src/example_preferred.py)  | 
|  Utilisation du connecteur Aurora DSQL pour Python avec un pool de connexions  |  [Exemple de connexion de base avec un pool de connexions](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/psycopg2/src/alternatives/pool/example_with_nonconcurrent_connection_pool.py)  | 
|   |  [Exemple de connexions simultanées avec pool de connexions](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/psycopg2/src/example_preferred.py)  | 

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

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


|  Description  |  Exemples  | 
| --- | --- | 
|  Utilisation du connecteur Aurora DSQL pour Python pour les connexions de base  |  [Exemple de connexion de base](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/asyncpg/src/example_preferred.py)  | 
|  Utilisation du connecteur Aurora DSQL pour Python avec un pool de connexions  |  [Exemple de connexion de base avec un pool de connexions](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/asyncpg/src/alternatives/pool/example_with_nonconcurrent_connection_pool.py)  | 
|   |  [Exemple de connexions simultanées avec pool de connexions](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/asyncpg/src/example_preferred.py)  |