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

El conector de Aurora DSQL para Go envuelve 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:

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:

Características principales de

Requisitos previos

El conector usa la cadena de credenciales predeterminada del SDK de AWS para Go v2, que resuelve las credenciales en el siguiente orden:

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:

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:

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)")

Ejemplos

Para ver ejemplos y casos de uso más completos, consulte los ejemplos del conector de Aurora DSQL para Go.