Conector do Aurora DSQL para Python

O conector do Aurora DSQL para Python integra a autenticação do IAM para conectar aplicações Python aos clusters do Amazon Aurora DSQL. Internamente, ele utiliza bibliotecas de cliente psycopg, psycopg2 e asyncpg.

O conector do Aurora DSQL para Python foi projetado como um plug-in de autenticação que estende a funcionalidade das bibliotecas de cliente psycopg, psycopg2 e asyncpg para permitir que as aplicações se autentiquem com o Amazon Aurora DSQL usando credenciais do IAM. O conector não se conecta diretamente ao banco de dados, mas oferece uma autenticação perfeita do IAM nas bibliotecas de cliente subjacentes.

Sobre o conector

O Amazon Aurora DSQL é um serviço de banco de dados SQL distribuído que oferece alta disponibilidade e escalabilidade para aplicações compatíveis com o PostgreSQL. O Aurora DSQL exige autenticação baseada no IAM com tokens de tempo limitado para os quais as bibliotecas do Python existentes não oferecem suporte nativo.

A ideia por trás do conector do Aurora DSQL para Python é adicionar uma camada de autenticação sobre as bibliotecas de cliente psycopg, psycopg2 e asyncpg que lide com a geração de tokens do IAM, permitindo que os usuários se conectem ao Aurora DSQL sem alterar os respectivos fluxos de trabalho existentes.

O que é a autenticação do Aurora DSQL?

Na autenticação do Aurora DSQL, a autenticação envolve:

O conector do Aurora DSQL para Python foi projetado para entender esses requisitos e gerar tokens de autenticação do IAM automaticamente ao estabelecer conexões.

Recursos

Guia de início rápido

Requisitos

Instalação

pip install aurora-dsql-python-connector

Instale a psycopg, a psycopg2 ou a asyncpg separadamente.

O instalador do conector do Aurora DSQL para Python não instala as bibliotecas subjacentes. É necessário instalá-las separadamente, por exemplo:

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

# Install psycopg2
pip install psycopg2-binary

# Install asyncpg
pip install asyncpg

Observação:

Somente a biblioteca necessária deve ser instalada. Portanto, se o cliente for usar a psycopg, somente ela precisará ser instalada. Se o cliente for usar a psycopg2, somente ela precisará ser instalada. Se o cliente for usar a asyncpg, somente ela precisará ser instalada.

Se o cliente precisar de mais de uma, todas as bibliotecas necessárias precisarão ser instaladas.

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)

Usar apenas o 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")

Usar apenas o ID do cluster

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

Observação:

No cenário “usar apenas o ID do cluster”, a região que foi definida anteriormente na máquina é usada, por exemplo:

aws configure set region us-east-1

Se a região não tiver sido definida ou o ID do cluster fornecido estiver em uma região diferente, a conexão falhará. Para que funcione, forneça a região como parâmetro, como no exemplo abaixo:

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)

String de conexão

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

Configuração avançada

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)

Opções de configuração

Todas as opções de conexão padrão das bibliotecas psycopg, psycopg2 e asyncpg subjacentes também são aceitas, com exceção dos parâmetros asyncpg krbsrvname e gsslib, que não são aceitos pelo DSQL.

Usar o conector do Aurora DSQL para Python com um grupo de conexões

O conector do Aurora DSQL para Python funciona com o grupo de conexões integrado psycopg, psycopg2 e asyncpg. O conector gerencia a geração de tokens do IAM durante o estabelecimento da conexão, permitindo que os grupos de conexões operem normalmente.

psycopg

Em relação à psycopg, o conector implementa uma classe de conexão chamada DSQLConnection que pode ser transmitida diretamente ao construtor psycopg_pool.ConnectionPool. Para operações assíncronas, também há uma versão assíncrona da classe chamada 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
    )

Observação: configuração da conexão max_lifetime

O parâmetro max_lifetime deve ser definido como menos de 3.600 segundos (uma hora), pois essa é a duração máxima da conexão permitida pelo banco de dados Aurora DSQL. Definir um max_lifetime inferior permite que o grupo de conexões gerencie de modo proativo a reciclagem de conexões, o que é mais eficiente do que lidar com erros de tempo limite de conexão do banco de dados.

psycopg2

Para psycopg2, o conector fornece uma classe chamada AuroraDSQLThreadedConnectionPool que herda de psycopg2.pool.ThreadedConnectionPool. A classe AuroraDSQLThreadedConnectionPool só substitui o método interno _connect. O restante da implementação é fornecido pelo psycopg2.pool.ThreadedConnectionPool inalterado.

    import aurora_dsql_psycopg2 as dsql

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

asyncpg

Para asyncpg, o conector fornece uma função create_pool que exibe uma instância 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)

Autenticação

O conector processa automaticamente a autenticação do DSQL gerando tokens com o uso do gerador de tokens do cliente do DSQL. Se a região da AWS não for fornecida, ela será automaticamente analisada por meio do nome do host fornecido.

Para acessar mais informações sobre autenticação no Aurora DSQL, consulte o guia do usuário.

Admin versus usuários regulares

Exemplos

Para ver o código de exemplo completo, consulte os exemplos conforme indicado nas seções abaixo. Para receber instruções sobre como executar os exemplos, consulte os arquivos LEIAME dos exemplos.

psycopg

LEIAME dos exemplos

psycopg2

LEIAME dos exemplos

asyncpg

LEIAME dos exemplos