# Conexión a clústeres de Aurora DSQL con un conector de Ruby
<a name="SECTION_program-with-dsql-connector-for-ruby-pg"></a>

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
<a name="SECTION_program-with-dsql-connector-for-ruby-pg-about"></a>

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?
<a name="SECTION_program-with-dsql-connector-for-ruby-pg-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 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
<a name="SECTION_program-with-dsql-connector-for-ruby-pg-features"></a>
+ **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
<a name="SECTION_program-with-dsql-connector-for-ruby-pg-example-application"></a>

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
<a name="SECTION_program-with-dsql-connector-for-ruby-pg-quick-start"></a>

### Requisitos
<a name="SECTION_program-with-dsql-connector-for-ruby-pg-requirements"></a>
+ 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 name="SECTION_program-with-dsql-connector-for-ruby-pg-installation"></a>

Añada a su archivo gem:

```
gem "aurora-dsql-ruby-pg"
```

O instale directamente:

```
gem install aurora-dsql-ruby-pg
```

## Uso
<a name="SECTION_program-with-dsql-connector-for-ruby-pg-usage"></a>

### Conexión de grupo
<a name="SECTION_program-with-dsql-connector-for-ruby-pg-pool-connection"></a>

```
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
<a name="SECTION_program-with-dsql-connector-for-ruby-pg-single-connection"></a>

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
<a name="SECTION_program-with-dsql-connector-for-ruby-pg-advanced"></a>

**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
<a name="SECTION_program-with-dsql-connector-for-ruby-pg-configuration"></a>


| 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
<a name="SECTION_program-with-dsql-connector-for-ruby-pg-auth"></a>

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
<a name="SECTION_program-with-dsql-connector-for-ruby-pg-admin-vs-regular"></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
+ El conector genera tokens de forma dinámica para cada conexión