Conectar-se a clusters do Aurora DSQL com um conector Ruby

O conector do Aurora DSQL para Ruby é um conector Ruby desenvolvido em pg que integra a autenticação do IAM para conectar aplicações Ruby aos clusters do Amazon Aurora DSQL.

O conector gerencia a geração de tokens, a configuração SSL e o agrupamento de conexões para que você se concentre na lógica da aplicação.

Sobre o conector

O Amazon Aurora DSQL exige autenticação do IAM com tokens de tempo limitado para os quais os drivers PostgreSQL do Ruby existentes não oferecem suporte nativo. O conector do Aurora DSQL para Ruby adiciona uma camada de autenticação sobre o driver pg que gerencia a geração de tokens do IAM, permitindo que você se conecte ao Aurora DSQL sem alterar seus fluxos de trabalho existentes do pg.

O que é a autenticação do Aurora DSQL?

Na autenticação do Aurora DSQL, a autenticação envolve:

O conector do Aurora DSQL para Ruby entende esses requisitos e gera tokens de autenticação do IAM automaticamente ao estabelecer conexões.

Recursos

Aplicativo de exemplo

Para ver um exemplo completo, consulte a aplicação de exemplo no GitHub.

Guia de início rápido

Requisitos

Instalação

Adicione a seu Gemfile:

gem "aurora-dsql-ruby-pg"

Ou instale diretamente:

gem install aurora-dsql-ruby-pg

Usage

Conexão do 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

Conexão única

Para scripts simples ou quando o agrupamento de conexões não é necessário:

conn = AuroraDsql::Pg.connect(host: "your-cluster.dsql.us-east-1.on.aws")
conn.exec("SELECT 1")
conn.close

Uso avançado

Configuração do host

O conector é compatível com endpoints de cluster completos (região detectada automaticamente) e IDs de cluster (região obrigatória):

# 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 Perfis do

Especifique um perfil da AWS para credenciais:

pool = AuroraDsql::Pg.create_pool(
  host: "your-cluster.dsql.us-east-1.on.aws",
  profile: "production"
)

Formato de string da conexão

O conector é compatível com os formatos de string de conexão do PostgreSQL:

postgres://[user@]host[:port]/[database][?param=value&...]
postgresql://[user@]host[:port]/[database][?param=value&...]

Parâmetros de consulta compatíveis: region, profile, tokenDurationSecs.

# Full endpoint with profile
pool = AuroraDsql::Pg.create_pool(
  "postgres://admin@cluster.dsql.us-east-1.on.aws/postgres?profile=dev"
)

Nova tentativa de OCC

O Aurora DSQL usa o controle de simultaneidade otimista (OCC). Quando duas transações modificam os mesmos dados, a primeira a confirmar vence e a segunda recebe um erro de OCC.

A nova tentativa do OCC é opcional. Defina occ_max_retries ao criar o agrupamento para ativar a nova tentativa automática com recuo exponencial e instabilidade em 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 pular a nova tentativa de chamadas individuais, passe retry_occ: false:

pool.with(retry_occ: false) do |conn|
  conn.exec("SELECT 1")
end

Opções de configuração

create_pool também aceita uma palavra-chave pool: com um hash de opções que você passa diretamente para ConnectionPool.new. Se você omitir pool:, o conector assume {size: 5, timeout: 5} como padrão. As chaves fornecidas substituem somente esses padrões específicos.

pool = AuroraDsql::Pg.create_pool(
  host: "your-cluster.dsql.us-east-1.on.aws",
  pool: { size: 10, timeout: 10 }
)

Autenticação

O conector gerencia automaticamente a autenticação do Aurora DSQL gerando tokens com o uso de credenciais da AWS. Se você não fornecer a região da AWS, o conector a analisará a partir do nome do host.

Para obter mais informações sobre autenticação no Aurora DSQL, consulte Autenticação e autorização para o Aurora DSQL.

Admin versus usuários regulares