# Conectores de Aurora DSQL para Node.js
El conector de Aurora DSQL para node-postgres y el conector de Aurora DSQL para Postgres.js son complementos de autenticación que amplían la funcionalidad de los clientes de node-postgres y Postgres.js para permitir que las aplicaciones se autentiquen con Aurora DSQL mediante credenciales de IAM.
# Conector de Aurora DSQL para node-postgres
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
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?
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
+ **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
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
### Requisitos
+ 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
```
npm install @aws/aurora-dsql-node-postgres-connector
```
## Dependencias de los pares
```
npm install @aws-sdk/credential-providers @aws-sdk/dsql-signer pg tsx
npm install --save-dev @types/pg
```
## Uso
### Conexiones de clientes
```
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();
```
### Conexión de 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 avanzado
```
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
| 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
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
+ 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.
# Conector de Aurora DSQL para Postgres.js
El [conector de Aurora DSQL para Postgres.js](https://github.com/awslabs/aurora-dsql-connectors/tree/main/node/postgres-js) es un conector de Node.js creado en [Postgres.js](https://github.com/porsager/postgres) que integra la autenticación de IAM para conectar aplicaciones de JavaScript a los clústeres de Amazon Aurora DSQL.
El conector de Aurora DSQL para Postgres.js está diseñado como un complemento de autenticación que amplía la funcionalidad del cliente de Postgres.js para permitir que las aplicaciones se autentiquen con Amazon Aurora DSQL mediante credenciales de IAM. El conector no se conecta directamente a la base de datos, pero proporciona una autenticación de IAM perfecta además del controlador de Postgres.js subyacente.
## Acerca del conector
Amazon Aurora DSQL es un servicio de base de datos SQL distribuido que proporciona alta disponibilidad y escalabilidad para aplicaciones compatibles con PostgreSQL. Aurora DSQL requiere una autenticación basada en IAM con tókenes de tiempo limitado que los controladores de Node.js existentes no admiten de forma nativa.
La idea detrás del conector de Aurora DSQL para Postgres.js es agregar una capa de autenticación sobre el cliente de Postgres.js que gestiona la generación de los tókenes de IAM, lo que permite a los usuarios conectarse a Aurora DSQL sin cambiar sus flujos de trabajo de Postgres.js existentes.
El conector de Aurora DSQL para Postgres.js funciona con la mayoría de las versiones de Postgres.js. Los usuarios proporcionan su propia versión instalando Postgres.js directamente.
### ¿Qué es la autenticación de Aurora DSQL?
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 Postgres.js 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
+ **Autenticación automática de IAM**: gestiona la generación y la actualización de los tókenes de DSQL
+ **Basado en Postgres.js**: aprovecha el rápido cliente de PostgreSQL para Node.js
+ **Integración perfecta**: funciona con los patrones de conexión de Postgres.js 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 de Postgres.js
## Guía de inicio rápido
### Requisitos
+ 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
```
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
```
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();
```
#### Uso de un ID de clúster en lugar de un host
```
const sql = auroraDSQLPostgres({
host: 'your-cluster-id',
region: 'us-east-1',
username: 'admin',
});
```
### Cadena de conexión
```
const sql = AuroraDSQLPostgres(
'postgres://admin@your-cluster.dsql.us-east-1.on.aws'
);
const result = await sql`SELECT current_timestamp`;
```
### Configuración avanzada
```
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
});
```
## Opciones de configuración
| Opción | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| host | string | Sí | Nombre de host o ID de clúster del clúster de DSQL |
| database | string? | No | Nombre de base de datos |
| username | string? | No | Nombre de usuario de la base de datos (usa admin si no se proporciona) |
| region | string? | No | Región de AWS (se detecta automáticamente desde el nombre de host si no se proporciona) |
| customCredentialsProvider | AwsCredentialIdentityProvider? | No | Proveedor de credenciales de AWS personalizadas |
| tokenDurationSecs | number? | No | Tiempo de caducidad del token en segundos |
También se admiten todas las [opciones estándar de Postgres.js](https://github.com/porsager/postgres?tab=readme-ov-file#connection-details).
## Autenticación
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
+ 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
## Ejemplo de uso
En GitHub hay disponibles ejemplos de JavaScript que utilizan el conector de Aurora DSQL para Postgres.js. Para obtener instrucciones sobre cómo ejecutar los ejemplos, consulte el [directorio de ejemplos](https://github.com/awslabs/aurora-dsql-connectors/tree/main/node/postgres-js/example).
| Descripción | Ejemplo |
| --- | --- |
| Agrupación de conexiones con consultas simultáneas, incluyendo la creación de tablas, inserciones y lecturas en varios trabajadores. | [Ejemplo de grupo de conexiones (preferido)](https://github.com/awslabs/aurora-dsql-connectors/blob/main/node/postgres-js/example/src/example_preferred.js) |
| Operaciones CRUD (crear tabla, insertar, seleccionar, eliminar) sin agrupación de conexiones | [Ejemplo sin grupo de conexiones](https://github.com/awslabs/aurora-dsql-connectors/blob/main/node/postgres-js/example/src/alternatives/no_connection_pool/example_with_no_connection_pool.js) |