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

 El [conector de Aurora DSQL para node-postgres](https://github.com/awslabs/aurora-dsql-connectors/tree/main/node/node-postgres) es un conector de Node.js creado en [node-postgres](https://node-postgres.com/) que integra la autenticación de IAM para conectar aplicaciones de JavaScript/TypeScript a los clústeres de Amazon Aurora DSQL. 

 El conector de Aurora DSQL está diseñado como un complemento de autenticación que amplía la funcionalidad del cliente y grupo de node-postgres para permitir que las aplicaciones se autentiquen con Amazon Aurora DSQL mediante credenciales de IAM. 

## Acerca del conector
<a name="about-the-connector"></a>

 Amazon Aurora DSQL es una base de datos distribuida nativa en la nube compatible con PostgreSQL. Aunque requiere autenticación de IAM y tókenes de duración determinada, los controladores de bases de datos tradicionales de Node.js carecen de este soporte integrado. 

 El conector de Aurora DSQL para node-postgres cierra esta brecha al implementar un middleware de autenticación que funciona a la perfección con node-postgres. Este enfoque permite a los desarrolladores mantener su código de node-postgres existente y, al mismo tiempo, obtener un acceso seguro basado en IAM a los clústeres de Aurora DSQL mediante la administración automatizada de tókenes. 

### ¿Qué es la autenticación de Aurora DSQL?
<a name="what-is-aurora-dsql-authentication"></a>

 En Aurora DSQL, la autenticación implica: 
+  **Autenticación de IAM**: todas las conexiones utilizan la autenticación basada en IAM con tokens de tiempo limitado 
+  **Generación de tókenes**: los tókenes de autenticación se generan mediante credenciales de AWS y tienen una vida útil configurable 

 El conector de Aurora DSQL para node-postgres 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
<a name="features"></a>
+  **Autenticación automática de IAM**: gestiona la generación y la actualización de los tókenes de DSQL. 
+  **Basado en node-postgres**: aprovecha el popular cliente de PostgreSQL para Node.js. 
+  **Integración perfecta**: funciona con los patrones de conexión de node-postgres existentes 
+  **Detección automática de regiones**: extrae la región de AWS del nombre de host del clúster de DSQL. 
+  **Compatibilidad total con TypeScript**: proporciona seguridad total de tipos 
+  **Compatibilidad de credenciales de AWS**: admite varios proveedores de credenciales de AWS (predeterminados, basados en perfiles, personalizados) 
+  **Compatibilidad con la agrupación de conexiones**: funciona a la perfección con la agrupación de conexiones integrada. 

## Aplicación de ejemplo
<a name="example-application"></a>

 En el [ejemplo](https://github.com/awslabs/aurora-dsql-connectors/tree/main/node/node-postgres/example), se incluye una aplicación de ejemplo que muestra cómo utilizar el conector de Aurora DSQL para node-postgres. Para ejecutar el ejemplo incluido, consulte el ejemplo [README](https://github.com/awslabs/aurora-dsql-connectors/blob/main/node/node-postgres/example/README.md). 

## Guía de inicio rápido
<a name="quick-start-guide"></a>

### Requisitos
<a name="requirements"></a>
+  Node.js 20\$1 
+  [Acceso a un clúster de Aurora DSQL](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/getting-started.html) 
+  Configure los permisos de IAM adecuados para permitir que la aplicación se conecte a Aurora DSQL. 
+  Credenciales de AWS configuradas (mediante CLI de AWS, variables de entorno o roles de IAM) 

## Instalación
<a name="installation"></a>

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

## Dependencias de los pares
<a name="peer-dependencies"></a>

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

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

### Conexiones de clientes
<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();
```

### Conexión de 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 avanzado
<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();
```

## Opciones de configuración
<a name="configuration-options"></a>


|  Opción  |  Tipo  |  Obligatorio  |  Descripción  | 
| --- | --- | --- | --- | 
|  host  |  string  |  Sí  |  Nombre de host del clúster de DSQL  | 
|  username  |  string  |  Sí  |  Nombre de usuario de DSQL  | 
|  database  |  string  |  No  |  Nombre de base de datos  | 
|  region  |  string  |  No  |  Región de AWS (se detecta automáticamente desde el nombre de host si no se proporciona)  | 
|  port  |  number  |  No  |  El valor predeterminado es 5432  | 
|  customCredentialsProvider  |  AwsCredentialIdentity / AwsCredentialIdentityProvider  |  No  |  Proveedor de credenciales de AWS personalizadas  | 
|  profile  |  string  |  No  |  El nombre del perfil de IAM (valor predeterminado: “predeterminado”)  | 
|  tokenDurationSecs  |  number  |  No  |  Tiempo de caducidad del token en segundos  | 

 Se admiten todos los demás parámetros del [cliente](https://node-postgres.com/apis/client)/[grupo](https://node-postgres.com/apis/pool). 

## Autenticación
<a name="authentication"></a>

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

### Administrador frente a usuarios habituales
<a name="admin-vs-regular-users"></a>
+  Los usuarios denominados “admin” utilizan automáticamente los tókenes de autenticación de administrador 
+  Todos los demás usuarios utilizan tókenes de autenticación habituales 
+  Los tókenes se generan de forma dinámica para cada conexión.