# Conectores para Aurora DSQL
Aurora DSQL proporciona conectores especializados que amplían los controladores de bases de datos existentes para permitir una autenticación e integración de IAM sin problemas con los servicios de AWS. Estos conectores están diseñados para funcionar con los marcos de trabajo y lenguajes de programación populares y, al mismo tiempo, mantener la compatibilidad con los flujos de trabajo de PostgreSQL existentes.
Conectores adicionales están previstos para futuras versiones. Para obtener la información más reciente sobre la disponibilidad de los conectores, consulte el [repositorio de ejemplos de Aurora DSQL](https://github.com/aws-samples/aurora-dsql-samples).
# Conexión a clústeres de Aurora DSQL con un conector de JDBC
El [conector de Aurora DSQL para JDBC](https://github.com/awslabs/aurora-dsql-connectors/tree/main/java/jdbc) está diseñado como un complemento de autenticación que amplía la funcionalidad del controlador JDBC de PostgreSQL para permitir que las aplicaciones se autentiquen con 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 JDBC de PostgreSQL subyacente.
El conector de Aurora DSQL para JDBC está diseñado para funcionar con el [controlador JDBC de PostgreSQL](https://github.com/pgjdbc/pgjdbc) y proporciona una integración perfecta con los requisitos de autenticación de IAM de Aurora DSQL.
Junto con el controlador JDBC de PostgreSQL, el conector de Aurora DSQL para JDBC permite la autenticación basada en IAM para Aurora DSQL. Ingresa una profunda integración con servicios de autenticación de AWS como [AWS Identity and Access Management](https://aws.amazon.com/iam/) (IAM).
## Acerca del conector
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 tokens de tiempo limitado que los controladores JDBC existentes no admiten de forma nativa.
La idea principal del conector de Aurora DSQL para JDBC es agregar una capa de autenticación sobre el controlador JDBC de PostgreSQL que gestione 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 JDBC existentes.
### ¿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 tokens**: los tokens de autenticación se generan mediante credenciales de AWS y tienen una vida útil configurable
El conector de Aurora DSQL para JDBC está diseñado para comprender estos requisitos y generar automáticamente los tókenes de autenticación de IAM al establecer las conexiones.
### Beneficios del conector de Aurora DSQL para JDBC
Aunque Aurora DSQL proporciona una interfaz compatible con PostgreSQL, los controladores de PostgreSQL existentes actualmente no admiten los requisitos de autenticación de IAM de Aurora DSQL. El conector de Aurora DSQL para JDBC permite a los clientes seguir utilizando los flujos de trabajo de PostgreSQL existentes y, al mismo tiempo, habilitar la autenticación de IAM mediante:
+ **Generación automática de tokens**: los tokens de IAM se generan automáticamente mediante credenciales de AWS
+ **Integración perfecta**: funciona con los patrones de conexión JDBC existentes
+ **Soporte de credenciales de AWS**: admite varios proveedores de credenciales de AWS (predeterminados, basados en perfiles, etc.)
### Uso del conector de Aurora DSQL para JDBC con agrupación de conexiones
El conector de Aurora DSQL para JDBC funciona con bibliotecas de agrupamiento de conexiones como HikariCP. El conector gestiona la generación del token de IAM durante el establecimiento de la conexión, lo que permite que los grupos de conexiones funcionen con normalidad.
## Características principales de
Generación automática de token
Los tokens de IAM se generan automáticamente mediante credenciales de AWS.
Integración sin problemas
Funciona con los patrones de conexión de JDBC existentes sin requerir cambios en el flujo de trabajo.
Soporte de credenciales de AWS
Admite varios proveedores de credenciales de AWS (predeterminados, basados en perfiles, etc.).
Compatibilidad de grupo de conexiones
Funciona a la perfección con bibliotecas de agrupación de conexiones como HikariCP.
## Requisitos previos
Antes de comenzar, asegúrese de que cumple los siguientes requisitos previos:
+ [Se ha creado un clúster en Aurora DSQL](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/getting-started.html).
+ Se ha instalado el kit de desarrollo de Java (JDK). Asegúrese de tener la versión 17 o superior.
+ Configure los permisos de IAM adecuados para permitir que la aplicación se conecte a Aurora DSQL.
+ Credenciales de AWS configuradas (mediante AWS CLI, variables de entorno o roles de IAM).
## Uso del conector de Aurora DSQL para JDBC
Para usar el conector de Aurora DSQL para JDBC en la aplicación de Java, siga estos pasos:
1. Agregue las siguientes dependencias al proyecto de Maven:
```
software.amazon.dsql
aurora-dsql-jdbc-connector
1.0.0
```
Para los proyectos de Gradle, agregue esta dependencia:
```
implementation("software.amazon.dsql:aurora-dsql-jdbc-connector:1.0.0")
```
1. Cree una conexión básica al clúster de Aurora DSQL mediante el formato de conector de AWS DSQL PostgreSQL:
```
import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.ResultSet;
import java.sql.SQLException;
import java.sql.Statement;
public class DsqlJdbcConnectorExample {
public static void main(String[] args) {
// Using AWS DSQL PostgreSQL Connector prefix
String jdbcUrl = "jdbc:aws-dsql:postgresql://your-cluster.dsql.us-east-1.on.aws/postgres?user=admin";
try (Connection connection = DriverManager.getConnection(jdbcUrl)) {
// Use the connection
try (Statement statement = connection.createStatement()) {
// Create a table
statement.execute("CREATE TABLE IF NOT EXISTS test_table (id UUID PRIMARY KEY DEFAULT gen_random_uuid(), name VARCHAR(100))");
// Insert data
statement.execute("INSERT INTO test_table (name) VALUES ('Test Name')");
// Query data
try (ResultSet resultSet = statement.executeQuery("SELECT * FROM test_table")) {
while (resultSet.next()) {
System.out.println("ID: " + resultSet.getInt("id") + ", Name: " + resultSet.getString("name"));
}
}
}
} catch (SQLException e) {
e.printStackTrace();
}
}
}
```
### Propiedades de configuración
El conector de Aurora DSQL para JDBC admite las siguientes propiedades de conexión:
usuario
Determina el usuario de la conexión y el método de generación del token utilizado. Ejemplo:: `admin`
token-duration-secs
Duración en segundos de la validez del token. Para obtener más información sobre los límites de los tokens, consulte [Generación de un token de autenticación en Amazon Aurora DSQL](SECTION_authentication-token.md).
profile
Se utiliza para crear una instancia de ProfileCredentialsProvider para la generación de un token con el nombre de perfil proporcionado.
region
Región de AWS para conexiones de Aurora DSQL. Es opcional. Cuando se proporcione, invalidará la región extraída de la URL.
database
El nombre de la base de datos a la que se va a conectar. El valor predeterminado es `postgres`.
### Registro
Habilite el registro para solucionar cualquier problema que pueda surgir al utilizar el conector JDBC de Aurora DSQL.
El conector utiliza el sistema de registro integrado (java.util.logging) de Java. Puede configurar los niveles de registro creando un archivo de `logging.properties`:
```
# Set root logger level to INFO for clean output
.level = INFO
# Show Aurora DSQL Connector for JDBC FINE logs for detailed debugging
software.amazon.dsql.level = FINE
# Console handler configuration
handlers = java.util.logging.ConsoleHandler
java.util.logging.ConsoleHandler.level = FINE
java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter
# Detailed formatter pattern with timestamp and logger name
java.util.logging.SimpleFormatter.format = %1$tH:%1$tM:%1$tS.%1$tL [%4$s] %3$s - %5$s%n
```
### Ejemplos
Para ver ejemplos y casos de uso más completos, consulte el [repositorio del conector de Aurora DSQL para JDBC](https://github.com/awslabs/aurora-dsql-connectors/tree/main/java/jdbc/examples)
# Conector de Aurora DSQL para Python
El [conector de Aurora DSQL para Python](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector) integra la autenticación de IAM para conectar aplicaciones Python a los clústeres de Amazon Aurora DSQL. Internamente, utiliza las bibliotecas de cliente [psycopg](https://github.com/psycopg/psycopg), [psycopg2](https://github.com/psycopg/psycopg2) y [asyncpg](https://github.com/MagicStack/asyncpg).
El conector de Aurora DSQL para Python está diseñado como un complemento de autenticación que amplía la funcionalidad de las bibliotecas de clientes psycopg, psycopg2 y asyncpg 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 de las bibliotecas de clientes subyacentes.
## 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 las bibliotecas de Python existentes no admiten de forma nativa.
La idea detrás del conector de Aurora DSQL para Python es agregar una capa de autenticación sobre las bibliotecas de clientes de psycopg, psycopg2 y asyncpg 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 existentes.
### ¿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 Python 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**: los tókenes de IAM se generan automáticamente mediante credenciales de AWS
+ **Basado en psycopg, psycopg2 y asyncpg**: aprovecha las bibliotecas de clientes de psycopg, psycopg2 y asyncpg
+ **Integración perfecta**: funciona con los patrones de conexión de psycopg, psycopg2 y asyncpg existentes sin necesidad de cambiar el flujo de trabajo
+ **Detección automática de regiones**: extrae la región de AWS del nombre de host del clúster de DSQL
+ **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 con la agrupación de conexiones integrada de psycopg, psycopg2 y asyncpg
## Guía de inicio rápido
### Requisitos
+ Python 3.10 o superior
+ [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
```
pip install aurora-dsql-python-connector
```
#### Instalación de psycopg o psycopg2 o asyncpg de forma independiente
El instalador del conector de Aurora DSQL para Python no instala las bibliotecas subyacentes. Se deben instalar de forma independiente, por ejemplo:
```
# Install psycopg and psycopg pool
pip install "psycopg[binary,pool]"
```
```
# Install psycopg2
pip install psycopg2-binary
```
```
# Install asyncpg
pip install asyncpg
```
**Nota:**
Solo se debe instalar la biblioteca necesaria. Por lo tanto, si el cliente va a utilizar psycopg, solo es necesario instalar psycopg. Si el cliente va a utilizar psycopg2, solo es necesario instalar psycopg2. Si el cliente va a utilizar asyncpg, solo es necesario instalar asyncpg.
Si el cliente necesita más de una, es necesario instalar todas las bibliotecas necesarias.
### Uso básico
#### psycopg
```
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
```
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
```
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)
```
#### Uso solo del host
##### psycopg
```
import aurora_dsql_psycopg as dsql
conn = dsql.connect("your-cluster.dsql.us-east-1.on.aws")
```
##### psycopg2
```
import aurora_dsql_psycopg2 as dsql
conn = dsql.connect("your-cluster.dsql.us-east-1.on.aws")
```
##### asyncpg
```
import asyncio
import aurora_dsql_asyncpg as dsql
conn = await dsql.connect("your-cluster.dsql.us-east-1.on.aws")
```
#### Uso solo del ID del clúster
##### psycopg
```
import aurora_dsql_psycopg as dsql
conn = dsql.connect("your-cluster")
```
##### psycopg2
```
import aurora_dsql_psycopg2 as dsql
conn = dsql.connect("your-cluster")
```
##### asyncpg
```
import asyncio
import aurora_dsql_asyncpg as dsql
conn = await dsql.connect("your-cluster")
```
**Nota:**
En el escenario “solo se usa el ID de clúster”, se usa la región que se configuró previamente en la máquina, por ejemplo:
```
aws configure set region us-east-1
```
Si no se ha establecido la región o el ID de clúster indicado se encuentra en una región diferente, la conexión producirá un error. Para que funcione, proporcione la región como parámetro, como se muestra en el siguiente ejemplo:
##### psycopg
```
import aurora_dsql_psycopg as dsql
config = {
"region": "us-east-1",
}
conn = dsql.connect("your-cluster", **config)
```
##### psycopg2
```
import aurora_dsql_psycopg2 as dsql
config = {
"region": "us-east-1",
}
conn = dsql.connect("your-cluster", **config)
```
##### asyncpg
```
import asyncio
import aurora_dsql_asyncpg as dsql
config = {
"region": "us-east-1",
}
conn = await dsql.connect("your-cluster", **config)
```
### Cadena de conexión
#### psycopg
```
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
```
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
```
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")
```
### Configuración avanzada
#### psycopg
```
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
```
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
```
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)
```
### 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 |
| user | string | No | Nombre de usuario de DSQL. Predeterminado: admin |
| dbname | string | No | Nombre de la base de datos. Predeterminado: postgres |
| region | string | No | Región de AWS (se detecta automáticamente desde el nombre de host si no se proporciona) |
| port | int | No | El valor predeterminado es 5432 |
| custom\$1credentials\$1provider | CredentialProvider | No | Proveedor de credenciales de AWS personalizadas |
| profile | string | No | El nombre del perfil de IAM. Valor predeterminado: predeterminado. |
| token\$1duration\$1secs | int | No | Tiempo de caducidad del token en segundos |
También se admiten todas las opciones de conexión estándar de las bibliotecas psycopg, psycopg2 y asyncpg subyacentes, con la excepción de los parámetros **krbsrvname** y **gsslib** que no admite DSQL.
### Uso del conector de Aurora DSQL para Python con agrupación de conexiones
El conector de Aurora DSQL para Python funciona con la agrupación de conexiones integrada de psycopg, psycopg2 y asyncpg. El conector gestiona la generación del token de IAM durante el establecimiento de la conexión, lo que permite que los grupos de conexiones funcionen con normalidad.
#### psycopg
En el caso de psycopg, el conector implementa una clase de conexión denominada DSQLConnection que se puede pasar directamente al constructor psycopg\$1pool.ConnectionPool. Para las operaciones asíncronas, también hay una versión asíncrona de la clase denominada 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
)
```
**Nota: Configuración de configuración max\$1lifetime**
El parámetro max\$1lifetime se debe establecer en menos de 3600 segundos (una hora), ya que es la duración máxima de conexión permitida por la base de datos de Aurora DSQL. Si se establece max\$1lifetime más bajo, el grupo de conexiones puede administrar de forma proactiva el reciclaje de conexiones, lo que resulta más eficaz que gestionar los errores de tiempo de espera de conexión de la base de datos.
#### psycopg2
Para psycopg2, el conector proporciona una clase denominada AuroraDSQLThreadedConnectionPool que hereda de psycopg2.pool.ThreadedConnectionPool. La clase AuroraDSQLThreadedConnectionPool solo invalida el método de conexión interna. El resto de la implementación lo proporciona psycopg2.pool.ThreadedConnectionPool sin cambios.
```
import aurora_dsql_psycopg2 as dsql
pool = dsql.AuroraDSQLThreadedConnectionPool(
minconn=2,
maxconn=8,
**conn_params,
)
```
#### asyncpg
Para asyncpg, el conector proporciona una función create\$1pool que devuelve una instancia 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)
```
## 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 que no son de administrador
+ Los tókenes se generan de forma dinámica para cada conexión
## Ejemplos
Para ver el código de ejemplo completo, consulte los ejemplos que se indican en las secciones siguientes. Para obtener instrucciones sobre cómo ejecutar los ejemplos, consulte los archivos READMDE de ejemplos.
### psycopg
[Ejemplos README](https://github.com/awslabs/aurora-dsql-connectors/blob/main/python/connector/examples/psycopg/README.md)
| Descripción | Ejemplos |
| --- | --- |
| Uso del conector de Aurora DSQL para Python para conexiones básicas | [Ejemplo de conexión básica](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/psycopg/src/example_preferred.py) |
| Uso del conector de Aurora DSQL para Python para conexiones asíncronas básicas | [Ejemplo de conexión asíncrona básica](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) |
| Uso del conector de Aurora DSQL para Python con grupo de conexiones | [Ejemplo de conexión básica con grupo de conexiones](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/psycopg/src/alternatives/pool/example_with_nonconcurrent_connection_pool.py) |
| | [Ejemplo de conexiones simultáneas con grupo de conexiones](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/psycopg/src/example_preferred.py) |
| Uso del conector de Aurora DSQL para Python con grupo de conexiones asíncronas | [Ejemplo de conexión básica con grupo de conexiones asíncronas](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/psycopg/src/alternatives/pool/example_with_async_connection_pool.py) |
### psycopg2
[Ejemplos README](https://github.com/awslabs/aurora-dsql-connectors/blob/main/python/connector/examples/psycopg2/README.md)
| Descripción | Ejemplos |
| --- | --- |
| Uso del conector de Aurora DSQL para Python para conexiones básicas | [Ejemplo de conexión básica](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/psycopg2/src/example_preferred.py) |
| Uso del conector de Aurora DSQL para Python con grupo de conexiones | [Ejemplo de conexión básica con grupo de conexiones](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/psycopg2/src/alternatives/pool/example_with_nonconcurrent_connection_pool.py) |
| | [Ejemplo de conexiones simultáneas con grupo de conexiones](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/psycopg2/src/example_preferred.py) |
### asyncpg
[Ejemplos README](https://github.com/awslabs/aurora-dsql-connectors/blob/main/python/connector/examples/asyncpg/README.md)
| Descripción | Ejemplos |
| --- | --- |
| Uso del conector de Aurora DSQL para Python para conexiones básicas | [Ejemplo de conexión básica](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/asyncpg/src/example_preferred.py) |
| Uso del conector de Aurora DSQL para Python con grupo de conexiones | [Ejemplo de conexión básica con grupo de conexiones](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/asyncpg/src/alternatives/pool/example_with_nonconcurrent_connection_pool.py) |
| | [Ejemplo de conexiones simultáneas con grupo de conexiones](https://github.com/awslabs/aurora-dsql-connectors/tree/main/python/connector/examples/asyncpg/src/example_preferred.py) |
# Conexión a clústeres de Aurora DSQL con un conector de Go
El [conector de Aurora DSQL para Go](https://github.com/awslabs/aurora-dsql-connectors/tree/main/go/pgx) envuelve [pgx](https://github.com/jackc/pgx) con la autenticación IAM automática. El conector se encarga de la generación de tokens, la configuración SSL y la gestión de conexiones para que usted pueda centrarse en la lógica de su aplicación.
## Acerca del conector
Aurora DSQL requiere una autenticación basada en IAM con tokens de duración limitada que los controladores de Go PostgreSQL existentes no admiten de forma nativa. El conector de Aurora DSQL para Go añade una capa de autenticación sobre el controlador pgx que gestiona la generación de tokens IAM, lo que le permite conectarse a Aurora DSQL sin cambiar sus flujos de trabajo de pgx existentes.
### ¿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 tokens**: el conector genera tokens de autenticación utilizando credenciales de AWS, y estos tokens tienen una duración configurable.
El conector de Aurora DSQL para Go está diseñado para comprender estos requisitos y generar automáticamente los tokens de autenticación de IAM al establecer las conexiones.
### Ventajas del conector de Aurora DSQL para Go
El conector de Aurora DSQL para Go le permite seguir utilizando sus flujos de trabajo de pgx existentes, al tiempo que habilita la autenticación de IAM a través de:
+ **Generación automática de tokens**: el conector genera automáticamente tokens de IAM para cada conexión.
+ **Agrupación de conexiones**: soporte integrado para `pgxpool` con generación automática de tokens por conexión.
+ **Configuración flexible**: compatibilidad con puntos de conexión completos o ID de clúster con detección automática de región.
+ **Compatibilidad con credenciales de AWS**: admite perfiles de AWS y proveedores de credenciales personalizados.
## Características principales de
Administración automática de tokens
El conector genera automáticamente los tokens de IAM para cada nueva conexión mediante credenciales previamente resueltas.
Grupo de conexiones
Agrupación de conexiones mediante `pgxpool` con generación automática de tokens por conexión.
Configuración de host flexible
Admite tanto puntos de conexión de clúster completos como ID de clúster con detección automática de región.
Seguridad SSL
SSL siempre está habilitado con el modo de verificación completa y negociación TLS directa.
## Requisitos previos
+ Go 1.24 o posterior
+ Credenciales de AWS configuradas
+ Un clúster de Aurora DSQL
El conector usa la [cadena de credenciales predeterminada del SDK de AWS para Go v2](https://docs.aws.amazon.com/sdk-for-go/v2/developer-guide/configure-gosdk.html#specifying-credentials), que resuelve las credenciales en el siguiente orden:
1. Variables de entorno (AWS\$1ACCESS\$1KEY\$1ID, AWS\$1SECRET\$1ACCESS\$1KEY)
1. Archivo de credenciales compartidas (\$1/.aws/credentials)
1. Archivo de configuración compartido (\$1/.aws/config)
1. Rol de IAM para Amazon EC2/ECS/Lambda
## Instalación
Instale el conector mediante los módulos Go:
```
go get github.com/awslabs/aurora-dsql-connectors/go/pgx/dsql
```
## Inicio rápido
En el siguiente ejemplo, se muestra cómo crear un grupo de conexiones y ejecutar una consulta:
```
package main
import (
"context"
"log"
"github.com/awslabs/aurora-dsql-connectors/go/pgx/dsql"
)
func main() {
ctx := context.Background()
// Create a connection pool
pool, err := dsql.NewPool(ctx, dsql.Config{
Host: "your-cluster.dsql.us-east-1.on.aws",
})
if err != nil {
log.Fatal(err)
}
defer pool.Close()
// Execute a query
var greeting string
err = pool.QueryRow(ctx, "SELECT 'Hello, DSQL!'").Scan(&greeting)
if err != nil {
log.Fatal(err)
}
log.Println(greeting)
}
```
## Opciones de configuración
El conector es compatible con las siguientes opciones de configuración:
| Campo | Tipo | Predeterminado | Descripción |
| --- | --- | --- | --- |
| Host | cadena | (obligatorio) | Punto de conexión de clúster o ID de clúster |
| Región | cadena | (detectado automáticamente) | Región de AWS; obligatorio si el host es un ID de clúster |
| Usuario | cadena | "admin" | Usuario de base de datos |
| Database | cadena | "postgres" | Nombre de base de datos |
| Puerto | int | 5432 | Database port (Puerto de base de datos) |
| Perfil | cadena | "" | Nombre de perfil de AWS para las credenciales |
| TokenDurationSecs | int | 900 (15 minutos) | Duración de validez del token en segundos (máximo permitido: 1 semana, valor predeterminado: 15 minutos) |
| MaxConns | int32 | 0 | Conexiones máximas de grupo (0 = pgxpool predeterminado) |
| MinConns | int32 | 0 | Conexiones de grupo mínimas (0 = pgxpool predeterminado) |
| MaxConnLifetime | time.Duration | 55 minutos | Tiempo máximo de conexión |
## Formato de la cadena de conexión
El conector admite los formatos de cadena de conexión PostgreSQL y DSQL:
```
postgres://[user@]host[:port]/[database][?param=value&...]
dsql://[user@]host[:port]/[database][?param=value&...]
```
Parámetros de consulta compatibles:
+ `region`: región de AWS
+ `profile`: nombre de perfil de AWS
+ `tokenDurationSecs`: duración de la validez del token en segundos
Ejemplos:
```
// Full endpoint (region auto-detected)
pool, _ := dsql.NewPool(ctx, "postgres://admin@cluster.dsql.us-east-1.on.aws/postgres")
// Using dsql:// scheme (also supported)
pool, _ := dsql.NewPool(ctx, "dsql://admin@cluster.dsql.us-east-1.on.aws/postgres")
// With explicit region
pool, _ := dsql.NewPool(ctx, "postgres://admin@cluster.dsql.us-east-1.on.aws/mydb?region=us-east-1")
// With AWS profile
pool, _ := dsql.NewPool(ctx, "postgres://admin@cluster.dsql.us-east-1.on.aws/postgres?profile=dev")
```
## Uso avanzado
### Configuración de host
El conector admite dos formatos de host:
**Punto de conexión completo** (región detectada automáticamente):
```
pool, _ := dsql.NewPool(ctx, dsql.Config{
Host: "your-cluster.dsql.us-east-1.on.aws",
})
```
**ID de clúster** (región requerida):
```
pool, _ := dsql.NewPool(ctx, dsql.Config{
Host: "your-cluster-id",
Region: "us-east-1",
})
```
### Ajuste de configuración de grupo
Configure el grupo de conexiones para su carga de trabajo:
```
pool, err := dsql.NewPool(ctx, dsql.Config{
Host: "your-cluster.dsql.us-east-1.on.aws",
MaxConns: 20,
MinConns: 5,
MaxConnLifetime: time.Hour,
MaxConnIdleTime: 30 * time.Minute,
HealthCheckPeriod: time.Minute,
})
```
### Uso de conexión única
Para scripts simples o cuando no es necesaria la agrupación de conexiones:
```
conn, err := dsql.Connect(ctx, dsql.Config{
Host: "your-cluster.dsql.us-east-1.on.aws",
})
if err != nil {
log.Fatal(err)
}
defer conn.Close(ctx)
// Use the connection
rows, err := conn.Query(ctx, "SELECT * FROM users")
```
### Uso de perfiles de AWS
Especificación de un perfil de AWS para credenciales:
```
pool, err := dsql.NewPool(ctx, dsql.Config{
Host: "your-cluster.dsql.us-east-1.on.aws",
Profile: "production",
})
```
## Reintento de OCC
Aurora DSQL utiliza control de simultaneidad optimista (OCC). Cuando dos transacciones modifican los mismos datos, la primera en confirmarse tiene prioridad y la segunda recibe un error de OCC.
El paquete `occretry` proporciona ayudantes para el reintento automático con retroceso exponencial y fluctuación. Instálelo con:
```
go get github.com/awslabs/aurora-dsql-connectors/go/pgx/occretry
```
Use `WithRetry` para escrituras transaccionales:
```
err := occretry.WithRetry(ctx, pool, occretry.DefaultConfig(), func(tx pgx.Tx) error {
_, err := tx.Exec(ctx, "UPDATE accounts SET balance = balance - $1 WHERE id = $2", 100, fromID)
if err != nil {
return err
}
_, err = tx.Exec(ctx, "UPDATE accounts SET balance = balance + $1 WHERE id = $2", 100, toID)
return err
})
```
Para instrucciones DDL o simples, use `ExecWithRetry`:
```
err := occretry.ExecWithRetry(ctx, pool, occretry.DefaultConfig(),
"CREATE TABLE IF NOT EXISTS users (id UUID PRIMARY KEY, name TEXT)")
```
**importante**
`WithRetry` administra `BEGIN`/`COMMIT`/`ROLLBACK` internamente. Su devolución de llamada recibe una transacción y debe contener solo operaciones de base de datos, además de ser segura para reintentarlo.
## Ejemplos
Para ver ejemplos y casos de uso más completos, consulte los [ejemplos del conector de Aurora DSQL para Go](https://github.com/awslabs/aurora-dsql-connectors/tree/main/go/pgx/example).
| Ejemplo | Descripción |
| --- | --- |
| [example\$1preferred](https://github.com/awslabs/aurora-dsql-connectors/tree/main/go/pgx/example/src/example_preferred.go) | Recomendado: grupo de conexiones con consultas simultáneas |
| [transacción](https://github.com/awslabs/aurora-dsql-connectors/tree/main/go/pgx/example/src/transaction) | Gestión de transacciones con BEGIN/COMMIT/ROLLBACK |
| [occ\$1retry](https://github.com/awslabs/aurora-dsql-connectors/tree/main/go/pgx/example/src/occ_retry) | Cómo gestionar los conflictos de OCC con un retroceso exponencial |
| [connection\$1string](https://github.com/awslabs/aurora-dsql-connectors/tree/main/go/pgx/example/src/connection_string) | Uso de cadenas de conexión para la configuración |
# 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) |
# Conexión a clústeres de Aurora DSQL con un conector de Ruby
El [conector de Aurora DSQL para Ruby](https://github.com/awslabs/aurora-dsql-connectors/tree/main/ruby/pg) es un conector de Ruby basado en [pg](https://github.com/ged/ruby-pg) que integra la autenticación de IAM para conectar aplicaciones Ruby a clústeres de Amazon Aurora DSQL.
El conector se encarga de la generación de tokens, la configuración SSL y la agrupación de conexiones para que usted pueda centrarse en la lógica de su aplicación.
## Acerca del conector
Amazon Aurora DSQL requiere una autenticación de IAM con tokens de duración limitada que los controladores PostgreSQL para Ruby existentes no admiten de forma nativa. El conector de Aurora DSQL para Ruby añade una capa de autenticación sobre el pg gem que gestiona la generación de tokens de IAM, lo que le permite conectarse a Aurora DSQL sin cambiar sus flujos de trabajo de pg existentes.
### ¿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 tokens**: el conector genera tokens de autenticación utilizando credenciales de AWS, y estos tokens tienen una duración configurable.
El conector de Aurora DSQL para Ruby comprende estos requisitos y genera automáticamente los tokens 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 token de Aurora DSQL.
+ **Basado en pg**: envuelve el popular gem de PostgreSQL para Ruby.
+ **Integración perfecta**: funciona con los flujos de trabajo de pg gem existentes.
+ **Agrupación de conexiones**: soporte integrado a través del gem `connection_pool` con la aplicación de max\$1lifetime.
+ **Detección automática de regiones**: extrae la región de AWS del nombre de host del clúster de DSQL.
+ **Compatibilidad con credenciales de AWS**: admite perfiles de AWS y proveedores de credenciales personalizadas.
+ **Reintento de OCC**: reintento opcional del control de simultaneidad optimista con retroceso exponencial.
## Aplicación de ejemplo
Para ver un ejemplo completo, consulte la [aplicación de ejemplo](https://github.com/awslabs/aurora-dsql-connectors/tree/main/ruby/pg/example) en GitHub.
## Guía de inicio rápido
### Requisitos
+ Ruby 3.1 o posterior
+ [Acceso a un clúster de Aurora DSQL](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/getting-started.html)
+ Credenciales de AWS configuradas (mediante AWS CLI, variables de entorno o roles de IAM).
## Instalación
Añada a su archivo gem:
```
gem "aurora-dsql-ruby-pg"
```
O instale directamente:
```
gem install aurora-dsql-ruby-pg
```
## Uso
### Conexión de grupo
```
require "aurora_dsql_pg"
# Create a connection pool with OCC retry enabled
pool = AuroraDsql::Pg.create_pool(
host: "your-cluster.dsql.us-east-1.on.aws",
occ_max_retries: 3
)
# Read
pool.with do |conn|
result = conn.exec("SELECT 'Hello, DSQL!'")
puts result[0]["?column?"]
end
# Write — you must wrap writes in a transaction
pool.with do |conn|
conn.transaction do
conn.exec_params("INSERT INTO users (id, name) VALUES (gen_random_uuid(), $1)", ["Alice"])
end
end
pool.shutdown
```
### Conexión única de
Para scripts simples o cuando no es necesaria la agrupación de conexiones:
```
conn = AuroraDsql::Pg.connect(host: "your-cluster.dsql.us-east-1.on.aws")
conn.exec("SELECT 1")
conn.close
```
### Uso avanzado
**Configuración de host**
El conector admite tanto puntos de conexión de clúster completos (detección automática de la región) como ID de clúster (se requiere especificar la región):
```
# Full endpoint (region auto-detected)
pool = AuroraDsql::Pg.create_pool(
host: "your-cluster.dsql.us-east-1.on.aws"
)
# Cluster ID (region required)
pool = AuroraDsql::Pg.create_pool(
host: "your-cluster-id",
region: "us-east-1"
)
```
**AWS Perfiles de**
Especificación de un perfil de AWS para credenciales:
```
pool = AuroraDsql::Pg.create_pool(
host: "your-cluster.dsql.us-east-1.on.aws",
profile: "production"
)
```
**Formato de la cadena de conexión**
El conector admite los formatos de cadena de conexión PostgreSQL:
```
postgres://[user@]host[:port]/[database][?param=value&...]
postgresql://[user@]host[:port]/[database][?param=value&...]
```
Parámetros de consulta compatibles: `region`, `profile`, `tokenDurationSecs`.
```
# Full endpoint with profile
pool = AuroraDsql::Pg.create_pool(
"postgres://admin@cluster.dsql.us-east-1.on.aws/postgres?profile=dev"
)
```
**Reintento de OCC**
Aurora DSQL utiliza control de simultaneidad optimista (OCC). Cuando dos transacciones modifican los mismos datos, la primera en confirmarse tiene prioridad y la segunda recibe un error de OCC.
El reintento de OCC es opcional. Establezca `occ_max_retries` al crear el grupo para habilitar el reintento automático con retroceso exponencial y fluctuación en `pool.with`:
```
pool = AuroraDsql::Pg.create_pool(
host: "your-cluster.dsql.us-east-1.on.aws",
occ_max_retries: 3
)
pool.with do |conn|
conn.transaction do
conn.exec_params("UPDATE accounts SET balance = balance - $1 WHERE id = $2", [100, from_id])
conn.exec_params("UPDATE accounts SET balance = balance + $1 WHERE id = $2", [100, to_id])
end
end
```
**aviso**
`pool.with` NO envuelve automáticamente su bloque en una transacción. Debe llamar a `conn.transaction` usted mismo para operaciones de escritura. En caso de conflicto de OCC, el conector vuelve a ejecutar todo el bloque, por lo que este debe contener solo operaciones de base de datos y ser seguro para repetir el intento.
Para omitir los reintentos en llamadas individuales, pase `retry_occ: false`:
```
pool.with(retry_occ: false) do |conn|
conn.exec("SELECT 1")
end
```
## Opciones de configuración
| Campo | Tipo | Predeterminado | Descripción |
| --- | --- | --- | --- |
| host | Cadena | (obligatorio) | Punto de conexión de clúster o ID de clúster |
| region | Cadena | (detectado automáticamente) | Región de AWS; obligatorio si el host es un ID de clúster |
| usuario | Cadena | "admin" | Usuario de base de datos |
| database | Cadena | "postgres" | Nombre de base de datos |
| puerto | Entero | 5432 | Database port (Puerto de base de datos) |
| profile | Cadena | nil | Nombre de perfil de AWS para las credenciales |
| token\$1duration | Entero | 900 (15 minutos) | Duración de validez del token en segundos (máximo permitido: 1 semana, valor predeterminado: 15 minutos) |
| credentials\$1provider | Aws::Credentials | nil | Proveedor de credenciales personalizadas |
| max\$1lifetime | Entero | 3300 (55 minutos) | Tiempo máximo de conexión en segundos |
| application\$1name | Cadena | nil | Prefijo ORM para application\$1name |
| registrador | Logger | nil | Registrador de advertencias de reintento de OCC |
| occ\$1max\$1retries | Entero | nil (deshabilitado) | Número máximo de reintentos de OCC en pool.with; habilita los reintentos cuando se establece |
`create_pool` también admite una palabra clave de `pool:` con un hash de opciones que usted pasa directamente a `ConnectionPool.new`. Si omite `pool:`, el conector se establece de forma predeterminada en `{size: 5, timeout: 5}`. Las claves que proporcione solo anularán esos valores predeterminados específicos.
```
pool = AuroraDsql::Pg.create_pool(
host: "your-cluster.dsql.us-east-1.on.aws",
pool: { size: 10, timeout: 10 }
)
```
## Autenticación
El conector gestiona automáticamente la autenticación de Aurora DSQL generando tokens usando las credenciales de AWS. Si no proporciona la región de AWS, el conector la analiza a partir del nombre de host.
Para obtener más información sobre la autenticación en Aurora DSQL, consulte [Autenticación y autorización para Aurora DSQL](authentication-authorization.md).
### 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
+ El conector genera tokens de forma dinámica para cada conexión
# Conexión a clústeres de Aurora DSQL con un conector de .NET
El [conector de Amazon Aurora DSQL para .NET](https://github.com/awslabs/aurora-dsql-connectors/tree/main/dotnet/npgsql) es un conector de .NET basado en [Npgsql](https://www.npgsql.org/) que integra la autenticación de IAM para conectar aplicaciones .NET a clústeres de Amazon Aurora DSQL.
El conector se encarga de la generación de tokens, la configuración SSL y la agrupación de conexiones para que usted pueda centrarse en la lógica de su aplicación.
## Acerca del conector
Amazon Aurora DSQL requiere una autenticación de IAM con tokens de duración limitada que los controladores PostgreSQL para .NET existentes no admiten de forma nativa. El conector de Aurora DSQL para .NET añade una capa de autenticación sobre Npgsql, que gestiona la generación de tokens de IAM, lo que le permite conectarse a Aurora DSQL sin cambiar sus flujos de trabajo de Npgsql existentes.
### ¿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 tokens**: el conector genera tokens de autenticación utilizando credenciales de AWS, y estos tokens tienen una duración configurable.
El conector de Aurora DSQL para .NET tiene en cuenta estos requisitos y genera automáticamente tokens de autenticación de IAM al establecer conexiones.
### Características
+ **Autenticación automática de IAM**: gestiona la generación y la actualización de token de Aurora DSQL.
+ **Basado en Npgsql**: incluye el popular controlador de PostgreSQL para.NET.
+ **Integración perfecta**: funciona con los flujos de trabajo de Npgsql existentes.
+ **Agrupación de conexiones**: soporte integrado a través de `NpgsqlDataSource` con aplicación de la duración máxima.
+ **Detección automática de regiones**: extrae la región de AWS del nombre de host del clúster de DSQL.
+ **Compatibilidad con credenciales de AWS**: admite perfiles de AWS y proveedores de credenciales personalizadas.
+ **Reintento de OCC**: reintento opcional del control de simultaneidad optimista con retroceso exponencial.
+ **Aplicación de SSL**: siempre utiliza SSL con el modo `verify-full` y negociación de TLS directa.
## Aplicación de ejemplo
Para ver un ejemplo completo, consulte la [aplicación de ejemplo](https://github.com/awslabs/aurora-dsql-connectors/tree/main/dotnet/npgsql/example) en GitHub.
## Guía de inicio rápido
### Requisitos
+ .NET 8.0 o posterior
+ [Acceso a un clúster de Aurora DSQL](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/getting-started.html)
+ Credenciales de AWS configuradas (mediante AWS CLI, variables de entorno o roles de IAM).
## Instalación
Añada el paquete a su proyecto:
```
dotnet add package Amazon.AuroraDsql.Npgsql
```
## Uso
### Conexión de grupo
```
using Amazon.AuroraDsql.Npgsql;
// Create a connection pool
await using var ds = await AuroraDsql.CreateDataSourceAsync(new DsqlConfig
{
Host = "your-cluster.dsql.us-east-1.on.aws",
OccMaxRetries = 3
});
// Read
await using (var conn = await ds.OpenConnectionAsync())
{
await using var cmd = conn.CreateCommand();
cmd.CommandText = "SELECT 'Hello, DSQL!'";
var greeting = await cmd.ExecuteScalarAsync();
Console.WriteLine(greeting);
}
// Transactional write with OCC retry
await ds.WithTransactionRetryAsync(async conn =>
{
await using var cmd = conn.CreateCommand();
cmd.CommandText = "INSERT INTO users (id, name) VALUES (gen_random_uuid(), @name)";
cmd.Parameters.AddWithValue("name", "Alice");
await cmd.ExecuteNonQueryAsync();
});
```
### Conexión única de
Para scripts sencillos o cuando no se necesita el uso de un grupo de conexiones:
```
await using var conn = await AuroraDsql.ConnectAsync(new DsqlConfig
{
Host = "your-cluster.dsql.us-east-1.on.aws"
});
await using var cmd = conn.CreateCommand("SELECT 1");
await cmd.ExecuteScalarAsync();
```
### Reintento de OCC
Aurora DSQL utiliza control de simultaneidad optimista (OCC). Cuando dos transacciones modifican los mismos datos, la primera en confirmarse tiene prioridad y la segunda recibe un error de OCC.
El reintento de OCC es opcional. Establezca `OccMaxRetries` en la configuración para habilitar el reintento automático con retroceso exponencial y fluctuación. Use `WithTransactionRetryAsync` para escrituras transaccionales:
```
await ds.WithTransactionRetryAsync(async conn =>
{
await using var cmd = conn.CreateCommand();
cmd.CommandText = "UPDATE accounts SET balance = balance - 100 WHERE id = @from";
cmd.Parameters.AddWithValue("from", fromId);
await cmd.ExecuteNonQueryAsync();
cmd.CommandText = "UPDATE accounts SET balance = balance + 100 WHERE id = @to";
cmd.Parameters.Clear();
cmd.Parameters.AddWithValue("to", toId);
await cmd.ExecuteNonQueryAsync();
});
```
Para instrucciones DDL o simples, use `ExecWithRetryAsync`:
```
await ds.ExecWithRetryAsync("CREATE TABLE IF NOT EXISTS users (id UUID PRIMARY KEY, name TEXT)");
```
**importante**
`WithTransactionRetryAsync` administra `BEGIN`/`COMMIT`/`ROLLBACK` internamente y abre una nueva conexión para cada intento. Su devolución de llamada debe contener solo operaciones de base de datos, además de ser segura para reintentarlo.
## Opciones de configuración
El conector también admite las cadenas de conexión `postgres://` y `postgresql://` con los parámetros de consulta `region` y `profile`.
| Campo | Tipo | Predeterminado | Descripción |
| --- | --- | --- | --- |
| Host | string | (obligatorio) | Punto de conexión de clúster o ID de clúster de 26 caracteres |
| Region | string? | (detectado automáticamente) | Región de AWS; obligatorio si el Host es un ID de clúster |
| User | string | "admin" | Usuario de base de datos |
| Database | string | "postgres" | Nombre de base de datos |
| Port | int | 5432 | Database port (Puerto de base de datos) |
| Profile | string? | null | Nombre de perfil de AWS para las credenciales |
| CustomCredentialsProvider | AWSCredentials? | null | Proveedor de credenciales de AWS personalizadas |
| TokenDurationSecs | int? | null (SDK predeterminado, 900s) | Duración de la validez del token en segundos |
| OccMaxRetries | int? | null (deshabilitado) | El número máximo predeterminado de reintentos de OCC para los métodos de reintento en el origen de datos |
| OrmPrefix | string? | null | Prefijo ORM precedido de application\$1name |
| LoggerFactory | ILoggerFactory? | null | Fábrica de registradores para advertencias y diagnósticos de reintentos |
| ConfigureConnectionString | Action? | null | Devolución de llamada para anular la configuración del grupo de conexiones o establecer propiedades adicionales de la cadena de conexión de Npgsql. SSL y Enlist son invariables de seguridad y no se pueden anular. |
## Autenticación
El conector gestiona automáticamente la autenticación de Aurora DSQL generando tokens usando las credenciales de AWS. Si no proporciona la región de AWS, el conector la analiza a partir del nombre de host.
Para obtener más información sobre la autenticación en Aurora DSQL, consulte [Autenticación y autorización para Aurora DSQL](authentication-authorization.md).
### 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
+ El conector genera tokens de forma dinámica para cada conexión