# Conectores do Aurora DSQL para Node.js
<a name="SECTION_Node-js-connectors"></a>

O conector do Aurora DSQL para node-postgres e o conector do Aurora DSQL para Postgres.js são plug-ins de autenticação que estendem a funcionalidade dos clientes node-postgres e Postgres.js para permitir que as aplicações se autentiquem com o Aurora DSQL usando credenciais do IAM.

# Conector do Aurora SQL para node-postgres
<a name="SECTION_program-with-dsql-connector-for-node-postgres"></a>

 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
<a name="about-the-connector"></a>

 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?
<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 node-postgres 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**: 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
<a name="example-application"></a>

 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
<a name="quick-start-guide"></a>

### Requisitos
<a name="requirements"></a>
+  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
<a name="installation"></a>

```
npm install @aws/aurora-dsql-node-postgres-connector
```

## Dependências de pares
<a name="peer-dependencies"></a>

```
npm install @aws-sdk/credential-providers @aws-sdk/dsql-signer pg tsx
npm install --save-dev @types/pg
```

## Usage
<a name="usage"></a>

### Conexão do cliente
<a name="client-connection"></a>

```
import { AuroraDSQLClient } from "@aws/aurora-dsql-node-postgres-connector";

const client = new AuroraDSQLClient({
  host: "<CLUSTER_ENDPOINT>",
  user: "admin",
});
await client.connect();
const result = await client.query("SELECT NOW()");
await client.end();
```

### Conexão do grupo
<a name="pool-connection"></a>

```
import { AuroraDSQLPool } from "@aws/aurora-dsql-node-postgres-connector";

const pool = new AuroraDSQLPool({
  host: "<CLUSTER_ENDPOINT>",
  user: "admin",
  max: 3,
  idleTimeoutMillis: 60000,
});

const result = await pool.query("SELECT NOW()");
```

### Uso avançado
<a name="advanced-usage"></a>

```
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
<a name="configuration-options"></a>


|  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
<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 regulares. 
+  Os tokens são gerados dinamicamente para cada conexão. 

# Conector do Aurora SQL para Postgres.js
<a name="SECTION_program-with-dsql-connector-for-postgresjs"></a>

 O [conector do Aurora DSQL para Postgres.js](https://github.com/awslabs/aurora-dsql-connectors/tree/main/node/postgres-js) é um conector Node.js desenvolvido em [Postgres.js](https://github.com/porsager/postgres) que integra a autenticação do IAM para conectar aplicações Javascript aos clusters do Amazon Aurora DSQL. 

 O conector do Aurora DSQL para Postgres.js foi projetado como um plug-in de autenticação que estende a funcionalidade do cliente do Postgres.js para permitir que as aplicações se autentiquem com o Amazon Aurora DSQL utilizando credenciais do IAM. O conector não se conecta diretamente ao banco de dados, mas oferece uma autenticação perfeita do IAM no driver subjacente do Postgres.js. 

## 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 que não são aceitos pelos drivers Node.js. 

 A ideia por trás do conector do Aurora DSQL para Postgres.js é adicionar uma camada de autenticação sobre o cliente do Postgres.js que gerencia a geração de tokens do IAM, permitindo que os usuários se conectem ao Aurora DSQL sem alterar os respectivos fluxos de trabalho do Postgres.js existentes. 

 O conector do Aurora DSQL para Postgres.js funciona com a maioria das versões do Postgres.js. Os usuários fornecem a própria versão instalando o Postgres.js diretamente. 

### 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 Postgres.js 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**: trata da geração e atualização de tokens do DSQL. 
+  **Desenvolvido em Postgres.js**: utiliza o rápido cliente do PostgreSQL para Node.js. 
+  **Integração perfeita**: funciona com padrões existentes de conexão do Postgres.js. 
+  **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 do Postgres.js. 

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

### Requisitos
<a name="requirements"></a>
+  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
<a name="installation"></a>

```
npm install @aws/aurora-dsql-postgresjs-connector
# Postgres.js is a peer-dependency, so users must install it themselves
npm install postgres
```

### Uso básico
<a name="basic-usage"></a>

```
import { auroraDSQLPostgres } from '@aws/aurora-dsql-postgresjs-connector';

const sql = auroraDSQLPostgres({
  host: 'your-cluster.dsql.us-east-1.on.aws',
  username: 'admin',
    
});

// Execute queries
const result = await sql`SELECT current_timestamp`;
console.log(result);

// Clean up
await sql.end();
```

#### Utilizar o ID do cluster em vez do host
<a name="using-cluster-id-instead-of-host"></a>

```
const sql = auroraDSQLPostgres({
  host: 'your-cluster-id',
  region: 'us-east-1',
  username: 'admin',
    
});
```

### String de conexão
<a name="connection-string"></a>

```
const sql = AuroraDSQLPostgres(
  'postgres://admin@your-cluster.dsql.us-east-1.on.aws'
);

const result = await sql`SELECT current_timestamp`;
```

### Configuração avançada
<a name="advanced-configuration"></a>

```
import { fromNodeProviderChain } from '@aws-sdk/credential-providers';

const sql = AuroraDSQLPostgres({
  host: 'your-cluster.dsql.us-east-1.on.aws',
  database: 'postgres',
  username: 'admin',
  customCredentialsProvider: fromNodeProviderChain(), // Optionally provide custom credentials provider
  tokenDurationSecs: 3600,                            // Token expiration (seconds)
  
  // Standard Postgres.js options
  max: 20,                              // Connection pool size
  ssl: { rejectUnauthorized: false }    // SSL configuration
});
```

## 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  | 
|  database  |  string?  |  Não  |  Nome do banco de dados  | 
|  username  |  string?  |  Não  |  Nome de usuário do banco de dados (usará admin se não for fornecido)  | 
|  region  |  string?  |  Não  |  Região da AWS (detectada automaticamente por meio do nome do host, se não for fornecido).  | 
|  customCredentialsProvider  |  AwsCredentialIdentityProvider?  |  Não  |  Provedor de credenciais personalizadas da AWS  | 
|  tokenDurationSecs  |  number?  |  Não  |  Tempo de expiração do token em segundos.  | 

 Todas as [opções padrão do Postgres.js](https://github.com/porsager/postgres?tab=readme-ov-file#connection-details) também são aceitas. 

## 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 regulares. 
+  Os tokens são gerados dinamicamente para cada conexão. 

## Exemplo de uso
<a name="sample-usage"></a>

 Exemplos de JavaScript usando o conector do Aurora DSQL para Postgres.js estão disponíveis no GitHub. Para ver instruções sobre como executar os exemplos, consulte o [diretório de exemplos](https://github.com/awslabs/aurora-dsql-connectors/tree/main/node/postgres-js/example). 


|  Descrição  |  Exemplo  | 
| --- | --- | 
|  Agrupamento de conexões com consultas simultâneas, incluindo criação de tabelas, inserções e leituras em vários operadores  |  [Exemplo de grupo de conexões (preferencial)](https://github.com/awslabs/aurora-dsql-connectors/blob/main/node/postgres-js/example/src/example_preferred.js)  | 
|  Operações CRUD (criar tabela, inserir, selecionar, excluir) sem grupo de conexões  |  [Exemplo sem grupo de conexões](https://github.com/awslabs/aurora-dsql-connectors/blob/main/node/postgres-js/example/src/alternatives/no_connection_pool/example_with_no_connection_pool.js)  |