Conexión a clústeres de Aurora DSQL con un conector de Ruby

El conector de Aurora DSQL para Ruby es un conector de Ruby basado en 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:

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

Aplicación de ejemplo

Para ver un ejemplo completo, consulte la aplicación de ejemplo en GitHub.

Guía de inicio rápido

Requisitos

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

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

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.

Administrador frente a usuarios habituales