# Conector do Aurora SQL para node-postgres
O [conector do Aurora DSQL para node-postgres](https://github.com/awslabs/aurora-dsql-connectors/tree/main/node/node-postgres) é um conector Node.js desenvolvido em [node-postgres](https://node-postgres.com/) que integra a autenticação do IAM para conectar aplicações JavaScript/TypeScript aos clusters do Amazon Aurora DSQL.
O conector do Aurora DSQL foi projetado como um plug-in de autenticação que estende a funcionalidade do cliente e do grupo do node-postgres para permitir que as aplicações se autentiquem com o Amazon Aurora DSQL utilizando credenciais do IAM.
## Sobre o conector
O Amazon Aurora DSQL é um banco de dados distribuído nativo da nuvem com compatibilidade com o PostgreSQL. Embora ele exija autenticação do IAM e tokens com limite de tempo, os drivers de banco de dados Node.js tradicionais não têm esse suporte integrado.
O conector do Aurora DSQL para node-postgres preenche essa lacuna implementando um middleware de autenticação que funciona perfeitamente com o node-postgres. Essa abordagem permite que os desenvolvedores mantenham seu código node-postgres existente e, ao mesmo tempo, tenham acesso seguro baseado em IAM aos clusters do Aurora DSQL por meio do gerenciamento automatizado de tokens.
### O que é a autenticação do Aurora DSQL?
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 node-postgres foi projetado para entender esses requisitos e gerar tokens de autenticação do IAM automaticamente ao estabelecer conexões.
### Recursos
+ **Autenticação automática do IAM**: trata da geração e atualização de tokens do DSQL.
+ **Desenvolvido em node-postgres**: utiliza o conhecido cliente PostgreSQL para Node.js.
+ **Integração perfeita**: funciona com padrões existentes de conexão do node-postgres.
+ **Descoberta automática de regiões**: extrai a região da AWS do nome de host do cluster do DSQL.
+ **Suporte completo ao TypeScript**: oferece segurança total de tipos.
+ **Suporte a credenciais da AWS**: aceita vários provedores de credenciais da AWS (padrão, baseado em perfil, personalizado).
+ **Compatibilidade com agrupamento de conexões**: funciona perfeitamente com o agrupamento de conexões integrado.
## Aplicação de exemplo
Há uma aplicação de exemplo incluída em [exemplo](https://github.com/awslabs/aurora-dsql-connectors/tree/main/node/node-postgres/example), que mostra como usar o conector do Aurora DSQL para node-postgres. Para executar o exemplo incluído, consulte o respectivo [LEIAME](https://github.com/awslabs/aurora-dsql-connectors/blob/main/node/node-postgres/example/README.md)
## Guia de início rápido
### Requisitos
+ Node.js 20
+ [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
```
npm install @aws/aurora-dsql-node-postgres-connector
```
## Dependências de pares
```
npm install @aws-sdk/credential-providers @aws-sdk/dsql-signer pg tsx
npm install --save-dev @types/pg
```
## Usage
### Conexão do cliente
```
import { AuroraDSQLClient } from "@aws/aurora-dsql-node-postgres-connector";
const client = new AuroraDSQLClient({
host: "",
user: "admin",
});
await client.connect();
const result = await client.query("SELECT NOW()");
await client.end();
```
### Conexão do grupo
```
import { AuroraDSQLPool } from "@aws/aurora-dsql-node-postgres-connector";
const pool = new AuroraDSQLPool({
host: "",
user: "admin",
max: 3,
idleTimeoutMillis: 60000,
});
const result = await pool.query("SELECT NOW()");
```
### Uso avançado
```
import { fromNodeProviderChain } from "@aws-sdk/credential-providers";
import { AuroraDSQLClient } from "@aws/aurora-dsql-node-postgres-connector";
const client = new AuroraDSQLClient({
host: "example.dsql.us-east-1.on.aws",
user: "admin",
customCredentialsProvider: fromNodeProviderChain(), // Optionally provide custom credentials provider
});
await client.connect();
const result = await client.query("SELECT NOW()");
await client.end();
```
## Opções de configuração
| Opção | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| host | string | Sim | Nome do host do cluster do DSQL |
| username | string | Sim | Nome de usuário do DSQL |
| database | string | Não | Nome do banco de dados |
| region | string | Não | Região da AWS (detectada automaticamente por meio do nome do host, se não for fornecido). |
| port | number | Não | O padrão é 5432. |
| customCredentialsProvider | AwsCredentialIdentity / AwsCredentialIdentityProvider | Não | Provedor de credenciais personalizadas da AWS |
| profile | string | Não | O nome do perfil do IAM. Tem como padrão “padrão”. |
| tokenDurationSecs | number | Não | Tempo de expiração do token em segundos. |
Todos os outros parâmetros de [Cliente](https://node-postgres.com/apis/client)/[Grupo](https://node-postgres.com/apis/pool) são aceitos.
## 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](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/authentication-authorization.html).
### Admin versus usuários regulares
+ Usuários chamados “admin” utilizam automaticamente tokens de autenticação de admin.
+ Todos os outros usuários utilizam tokens de autenticação regulares.
+ Os tokens são gerados dinamicamente para cada conexão.