# Conector de Aurora DSQL para Python
<a name="SECTION_program-with-dsql-connector-for-python"></a>

 El [conector de Aurora DSQL para Python](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector) integra la autenticación de IAM para conectar aplicaciones Python a los clústeres de Amazon Aurora DSQL. Internamente, utiliza las bibliotecas de cliente [psycopg](https://github.com/psycopg/psycopg), [psycopg2](https://github.com/psycopg/psycopg2) y [asyncpg](https://github.com/MagicStack/asyncpg). 

 El conector de Aurora DSQL para Python está diseñado como un complemento de autenticación que amplía la funcionalidad de las bibliotecas de clientes psycopg, psycopg2 y asyncpg para permitir que las aplicaciones se autentiquen con Amazon Aurora DSQL mediante credenciales de IAM. El conector no se conecta directamente a la base de datos, pero proporciona una autenticación de IAM perfecta además de las bibliotecas de clientes subyacentes. 

## Acerca del conector
<a name="about-the-connector"></a>

 Amazon Aurora DSQL es un servicio de base de datos SQL distribuido que proporciona alta disponibilidad y escalabilidad para aplicaciones compatibles con PostgreSQL. Aurora DSQL requiere una autenticación basada en IAM con tókenes de tiempo limitado que las bibliotecas de Python existentes no admiten de forma nativa. 

 La idea detrás del conector de Aurora DSQL para Python es agregar una capa de autenticación sobre las bibliotecas de clientes de psycopg, psycopg2 y asyncpg que gestiona la generación de los tókenes de IAM, lo que permite a los usuarios conectarse a Aurora DSQL sin cambiar sus flujos de trabajo existentes. 

### ¿Qué es la autenticación de Aurora DSQL?
<a name="what-is-aurora-dsql-authentication"></a>

 En Aurora DSQL, la autenticación implica: 
+  **Autenticación de IAM**: todas las conexiones utilizan la autenticación basada en IAM con tokens de tiempo limitado 
+  **Generación de tókenes**: los tókenes de autenticación se generan mediante credenciales de AWS y tienen una vida útil configurable 

 El conector de Aurora DSQL para Python está diseñado para comprender estos requisitos y generar automáticamente los tókenes de autenticación de IAM al establecer las conexiones. 

### Características
<a name="features"></a>
+  **Autenticación automática de IAM**: los tókenes de IAM se generan automáticamente mediante credenciales de AWS 
+  **Basado en psycopg, psycopg2 y asyncpg**: aprovecha las bibliotecas de clientes de psycopg, psycopg2 y asyncpg 
+  **Integración perfecta**: funciona con los patrones de conexión de psycopg, psycopg2 y asyncpg existentes sin necesidad de cambiar el flujo de trabajo 
+  **Detección automática de regiones**: extrae la región de AWS del nombre de host del clúster de DSQL 
+  **Compatibilidad de credenciales de AWS**: admite varios proveedores de credenciales de AWS (predeterminados, basados en perfiles, personalizados) 
+  **Compatibilidad con la agrupación de conexiones**: funciona con la agrupación de conexiones integrada de psycopg, psycopg2 y asyncpg 

## Guía de inicio rápido
<a name="quick-start-guide"></a>

### Requisitos
<a name="requirements"></a>
+  Python 3.10 o superior 
+  [Acceso a un clúster de Aurora DSQL](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/getting-started.html) 
+  Configure los permisos de IAM adecuados para permitir que la aplicación se conecte a Aurora DSQL. 
+  Credenciales de AWS configuradas (mediante CLI de AWS, variables de entorno o roles de IAM) 

### Instalación
<a name="installation"></a>

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

#### Instalación de psycopg o psycopg2 o asyncpg de forma independiente
<a name="install-psycopg-or-psycopg2-or-asyncpg-separately"></a>

 El instalador del conector de Aurora DSQL para Python no instala las bibliotecas subyacentes. Se deben instalar de forma independiente, por ejemplo: 

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

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

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

 **Nota:** 

 Solo se debe instalar la biblioteca necesaria. Por lo tanto, si el cliente va a utilizar psycopg, solo es necesario instalar psycopg. Si el cliente va a utilizar psycopg2, solo es necesario instalar psycopg2. Si el cliente va a utilizar asyncpg, solo es necesario instalar asyncpg. 

 Si el cliente necesita más de una, es necesario instalar todas las bibliotecas necesarias. 

### Uso básico
<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)
```

#### Uso solo del 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")
```

#### Uso solo del ID del clúster
<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")
```

 **Nota:** 

 En el escenario “solo se usa el ID de clúster”, se usa la región que se configuró previamente en la máquina, por ejemplo: 

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

 Si no se ha establecido la región o el ID de clúster indicado se encuentra en una región diferente, la conexión producirá un error. Para que funcione, proporcione la región como parámetro, como se muestra en el siguiente ejemplo: 

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

### Cadena de conexión
<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")
```

### Configuración avanzada
<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)
```

### Opciones de configuración
<a name="configuration-options"></a>


|  Opción  |  Tipo  |  Obligatorio  |  Descripción  | 
| --- | --- | --- | --- | 
|  host  |  string  |  Sí  |  Nombre de host o ID de clúster del clúster de DSQL  | 
|  user  |  string  |  No  |  Nombre de usuario de DSQL. Predeterminado: admin  | 
|  dbname  |  string  |  No  |  Nombre de la base de datos. Predeterminado: postgres  | 
|  region  |  string  |  No  |  Región de AWS (se detecta automáticamente desde el nombre de host si no se proporciona)  | 
|  port  |  int  |  No  |  El valor predeterminado es 5432  | 
|  custom\$1credentials\$1provider  |  CredentialProvider  |  No  |  Proveedor de credenciales de AWS personalizadas  | 
|  profile  |  string  |  No  |  El nombre del perfil de IAM. Valor predeterminado: predeterminado.  | 
|  token\$1duration\$1secs  |  int  |  No  |  Tiempo de caducidad del token en segundos  | 

 También se admiten todas las opciones de conexión estándar de las bibliotecas psycopg, psycopg2 y asyncpg subyacentes, con la excepción de los parámetros **krbsrvname** y **gsslib** que no admite DSQL. 

### Uso del conector de Aurora DSQL para Python con agrupación de conexiones
<a name="using-the-aurora-dsql-connector-for-python-with-connection-pooling"></a>

 El conector de Aurora DSQL para Python funciona con la agrupación de conexiones integrada de psycopg, psycopg2 y asyncpg. El conector gestiona la generación del token de IAM durante el establecimiento de la conexión, lo que permite que los grupos de conexiones funcionen con normalidad. 

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

 En el caso de psycopg, el conector implementa una clase de conexión denominada DSQLConnection que se puede pasar directamente al constructor psycopg\$1pool.ConnectionPool. Para las operaciones asíncronas, también hay una versión asíncrona de la clase denominada 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
    )
```

 **Nota: Configuración de configuración max\$1lifetime** 

 El parámetro max\$1lifetime se debe establecer en menos de 3600 segundos (una hora), ya que es la duración máxima de conexión permitida por la base de datos de Aurora DSQL. Si se establece max\$1lifetime más bajo, el grupo de conexiones puede administrar de forma proactiva el reciclaje de conexiones, lo que resulta más eficaz que gestionar los errores de tiempo de espera de conexión de la base de datos. 

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

 Para psycopg2, el conector proporciona una clase denominada AuroraDSQLThreadedConnectionPool que hereda de psycopg2.pool.ThreadedConnectionPool. La clase AuroraDSQLThreadedConnectionPool solo invalida el método de conexión interna. El resto de la implementación lo proporciona psycopg2.pool.ThreadedConnectionPool sin cambios. 

```
    import aurora_dsql_psycopg2 as dsql

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

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

 Para asyncpg, el conector proporciona una función create\$1pool que devuelve una instancia 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)
```

## Autenticación
<a name="authentication"></a>

 El conector gestiona automáticamente la autenticación de DSQL mediante la generación de tókenes a través del generador de tókenes del cliente de DSQL. Si no se proporciona la región de AWS, se analizará automáticamente a partir del nombre de host proporcionado. 

 Para obtener más información sobre la autenticación en Aurora DSQL, consulte la [guía del usuario](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/authentication-authorization.html). 

### Administrador frente a usuarios habituales
<a name="admin-vs-regular-users"></a>
+  Los usuarios denominados `"admin"` utilizan automáticamente los tókenes de autenticación de administrador 
+  Todos los demás usuarios utilizan tókenes de autenticación que no son de administrador 
+  Los tókenes se generan de forma dinámica para cada conexión 

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

 Para ver el código de ejemplo completo, consulte los ejemplos que se indican en las secciones siguientes. Para obtener instrucciones sobre cómo ejecutar los ejemplos, consulte los archivos READMDE de ejemplos. 

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

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


|  Descripción  |  Ejemplos  | 
| --- | --- | 
|  Uso del conector de Aurora DSQL para Python para conexiones básicas  |  [Ejemplo de conexión básica](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/psycopg/src/example_preferred.py)  | 
|  Uso del conector de Aurora DSQL para Python para conexiones asíncronas básicas  |  [Ejemplo de conexión asíncrona básica](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)  | 
|  Uso del conector de Aurora DSQL para Python con grupo de conexiones  |  [Ejemplo de conexión básica con grupo de conexiones](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/psycopg/src/alternatives/pool/example_with_nonconcurrent_connection_pool.py)  | 
|   |  [Ejemplo de conexiones simultáneas con grupo de conexiones](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/psycopg/src/example_preferred.py)  | 
|  Uso del conector de Aurora DSQL para Python con grupo de conexiones asíncronas  |  [Ejemplo de conexión básica con grupo de conexiones asíncronas](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>

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


|  Descripción  |  Ejemplos  | 
| --- | --- | 
|  Uso del conector de Aurora DSQL para Python para conexiones básicas  |  [Ejemplo de conexión básica](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/psycopg2/src/example_preferred.py)  | 
|  Uso del conector de Aurora DSQL para Python con grupo de conexiones  |  [Ejemplo de conexión básica con grupo de conexiones](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/psycopg2/src/alternatives/pool/example_with_nonconcurrent_connection_pool.py)  | 
|   |  [Ejemplo de conexiones simultáneas con grupo de conexiones](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/psycopg2/src/example_preferred.py)  | 

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

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


|  Descripción  |  Ejemplos  | 
| --- | --- | 
|  Uso del conector de Aurora DSQL para Python para conexiones básicas  |  [Ejemplo de conexión básica](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/asyncpg/src/example_preferred.py)  | 
|  Uso del conector de Aurora DSQL para Python con grupo de conexiones  |  [Ejemplo de conexión básica con grupo de conexiones](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/asyncpg/src/alternatives/pool/example_with_nonconcurrent_connection_pool.py)  | 
|   |  [Ejemplo de conexiones simultáneas con grupo de conexiones](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/asyncpg/src/example_preferred.py)  |