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

 O [conector do Aurora DSQL para Python](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector) integra a autenticação do IAM para conectar aplicações Python aos clusters do Amazon Aurora DSQL. Internamente, ele utiliza bibliotecas de cliente [psycopg](https://github.com/psycopg/psycopg), [psycopg2](https://github.com/psycopg/psycopg2) e [asyncpg](https://github.com/MagicStack/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
<a name="about-the-connector"></a>

 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?
<a name="what-is-aurora-dsql-authentication"></a>

 Na autenticação do Aurora DSQL, a autenticação envolve: 
+  **Autenticação do IAM**: todas as conexões usam autenticação baseada no IAM com tokens de tempo limitado. 
+  **Geração de tokens:** os tokens de autenticação são gerados com o uso de credenciais da AWS e têm vida útil configurável. 

 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
<a name="features"></a>
+  **Autenticação automática do IAM**: os tokens do IAM são gerados automaticamente utilizando credenciais da AWS. 
+  **Desenvolvido em psycopg, psycopg2 e asyncpg**: utiliza as bibliotecas de cliente psycopg, psycopg2 e asncpg. 
+  **Integração perfeita**: funciona com os padrões de conexão psycopg, psycopg2 e asyncpg existentes sem exigir alterações no fluxo de trabalho. 
+  **Descoberta automática de regiões**: extrai a região da AWS do nome de host do cluster do DSQL. 
+  **Suporte a credenciais da AWS**: aceita vários provedores de credenciais da AWS (padrão, baseado em perfil, personalizado). 
+  **Compatibilidade do grupo de conexões**: funciona com o grupo de conexões integrado psycopg, psycopg2 e asyncpg. 

## Guia de início rápido
<a name="quick-start-guide"></a>

### Requisitos
<a name="requirements"></a>
+  Python 3.10 ou posterior 
+  [Acesso a um cluster do Aurora DSQL](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/getting-started.html) 
+  Configurar as permissões apropriadas do IAM para permitir que sua aplicação se conecte ao Aurora DSQL. 
+  Credenciais da AWS configuradas (por meio da AWS CLI, de variáveis de ambiente ou perfis do IAM). 

### Instalação
<a name="installation"></a>

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

#### Instale a psycopg, a psycopg2 ou a asyncpg separadamente.
<a name="install-psycopg-or-psycopg2-or-asyncpg-separately"></a>

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

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

#### Usar apenas o ID do cluster
<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")
```

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

### String de conexão
<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")
```

### Configuração avançada
<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)
```

### Opções de configuração
<a name="configuration-options"></a>


|  Opção  |  Tipo  |  Obrigatório  |  Descrição  | 
| --- | --- | --- | --- | 
|  host  |  string  |  Sim  |  Nome do host ou ID do cluster do DSQL  | 
|  user  |  string  |  Não  |  Nome de usuário do DSQL. Padrão: admin  | 
|  dbname  |  string  |  Não  |  Database name. Padrão: postgres  | 
|  region  |  string  |  Não  |  Região da AWS (detectada automaticamente por meio do nome do host, se não for fornecido).  | 
|  port  |  int  |  Não  |  O padrão é 5432.  | 
|  custom\_credentials\_provider  |  CredentialProvider  |  Não  |  Provedor de credenciais personalizadas da AWS  | 
|  profile  |  string  |  Não  |  O nome do perfil do IAM. Padrão: padrão.  | 
|  token\_duration\_secs  |  int  |  Não  |  Tempo de expiração do token em segundos.  | 

 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
<a name="using-the-aurora-dsql-connector-for-python-with-connection-pooling"></a>

 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
<a name="psycopg-6"></a>

 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
<a name="psycopg2-6"></a>

 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
<a name="asyncpg-6"></a>

 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
<a name="authentication"></a>

 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](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/authentication-authorization.html). 

### Admin versus usuários regulares
<a name="admin-vs-regular-users"></a>
+  Usuários chamados `"admin"` utilizam automaticamente tokens de autenticação de admin. 
+  Todos os outros usuários utilizam tokens de autenticação diferentes de admin. 
+  Os tokens são gerados dinamicamente para cada conexão. 

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

 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
<a name="psycopg-7"></a>

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


|  Descrição  |  Exemplos  | 
| --- | --- | 
|  Usar o conector do Aurora DSQL para Python para conexões básicas  |  [Exemplo básico de conexão](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/psycopg/src/example_preferred.py)  | 
|  Usar o conector do Aurora DSQL para Python para conexões assíncronas básicas  |  [Exemplo básico de conexão assíncrona](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)  | 
|  Usar o conector do Aurora DSQL para Python com grupo de conexões  |  [Exemplo básico de conexão com grupo de conexões](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/psycopg/src/alternatives/pool/example_with_nonconcurrent_connection_pool.py)  | 
|   |  [Exemplo de conexões simultâneas com grupo de conexões](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/psycopg/src/example_preferred.py)  | 
|  Usar o conector do Aurora DSQL para Python com grupo de conexões assíncronas  |  [Exemplo básico de conexão com grupo de conexões assí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>

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


|  Descrição  |  Exemplos  | 
| --- | --- | 
|  Usar o conector do Aurora DSQL para Python para conexões básicas  |  [Exemplo básico de conexão](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/psycopg2/src/example_preferred.py)  | 
|  Usar o conector do Aurora DSQL para Python com grupo de conexões  |  [Exemplo básico de conexão com grupo de conexões](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/psycopg2/src/alternatives/pool/example_with_nonconcurrent_connection_pool.py)  | 
|   |  [Exemplo de conexões simultâneas com grupo de conexões](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/psycopg2/src/example_preferred.py)  | 

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

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


|  Descrição  |  Exemplos  | 
| --- | --- | 
|  Usar o conector do Aurora DSQL para Python para conexões básicas  |  [Exemplo básico de conexão](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/asyncpg/src/example_preferred.py)  | 
|  Usar o conector do Aurora DSQL para Python com grupo de conexões  |  [Exemplo básico de conexão com grupo de conexões](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/asyncpg/src/alternatives/pool/example_with_nonconcurrent_connection_pool.py)  | 
|   |  [Exemplo de conexões simultâneas com grupo de conexões](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/asyncpg/src/example_preferred.py)  |