Conector de Aurora DSQL para Python

El conector de Aurora DSQL para Python 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, psycopg2 y 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

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?

En Aurora DSQL, la autenticación implica:

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

Guía de inicio rápido

Requisitos

Instalación

pip install aurora-dsql-python-connector

Instalación de psycopg o psycopg2 o asyncpg de forma independiente

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

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)

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

Uso solo del ID del clúster

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

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

    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)

Cadena de conexión

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

Configuración avanzada

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)

Opciones de configuración

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

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

En el caso de psycopg, el conector implementa una clase de conexión denominada DSQLConnection que se puede pasar directamente al constructor psycopg_pool.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_lifetime

El parámetro max_lifetime 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_lifetime 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

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

Para asyncpg, el conector proporciona una función create_pool 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

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.

Administrador frente a usuarios habituales

Ejemplos

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

Ejemplos README

psycopg2

Ejemplos README

asyncpg

Ejemplos README