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

O conector do Aurora DSQL para Go encapsula o pgx com a autenticação automática do IAM. O conector gerencia a geração de tokens, a configuração SSL e o gerenciamento de conexões para que você se concentre na lógica da aplicação.

Sobre o conector

O Aurora DSQL exige autenticação baseada no IAM com tokens de tempo limitado para os quais os drivers Go do PostgreSQL não oferecem suporte nativo. O conector do Aurora DSQL para Go adiciona uma camada de autenticação sobre o driver pgx 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 pgx.

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

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

O conector do Aurora DSQL para Go foi projetado para entender esses requisitos e gerar tokens de autenticação do IAM automaticamente ao estabelecer conexões.

Benefícios do conector do Aurora DSQL para Go

O conector do Aurora DSQL para Go permite que você continue usando seus fluxos de trabalho existentes do pgx e, ao mesmo tempo, habilite a autenticação do IAM por meio de:

Atributos principais

Pré-requisitos

O conector usa a cadeia de credenciais padrão do AWS SDK para Go v2, que resolve as credenciais na seguinte ordem:

Instalação

Instale o conector usando os módulos do Go:

go get github.com/awslabs/aurora-dsql-connectors/go/pgx/dsql

Início rápido

O seguinte exemplo mostra como criar um grupo de conexões e executar uma 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)
}

Opções de configuração

O conector aceita as seguintes opções de configuração:

Formato de string da conexão

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

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

Parâmetros de consulta compatíveis:

Exemplos:

// 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 avançado

Configuração do host

O conector aceita dois formatos de host:

Endpoint completo (região detectada automaticamente):

pool, _ := dsql.NewPool(ctx, dsql.Config{
    Host: "your-cluster.dsql.us-east-1.on.aws",
})

ID do cluster (região obrigatória):

pool, _ := dsql.NewPool(ctx, dsql.Config{
    Host:   "your-cluster-id",
    Region: "us-east-1",
})

Ajuste da configuração do grupo

Configure o grupo de conexões para a workload:

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 conexão única

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

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

Usar perfis da AWS

Especifique um perfil da AWS para credenciais:

pool, err := dsql.NewPool(ctx, dsql.Config{
    Host:    "your-cluster.dsql.us-east-1.on.aws",
    Profile: "production",
})

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.

O pacote occretry fornece ajudantes para nova tentativa automática com recuo exponencial e instabilidade. Instale-o com:

go get github.com/awslabs/aurora-dsql-connectors/go/pgx/occretry

Use WithRetry para gravações transacionais:

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 declarações DDL ou únicas, use ExecWithRetry:

err := occretry.ExecWithRetry(ctx, pool, occretry.DefaultConfig(),
    "CREATE TABLE IF NOT EXISTS users (id UUID PRIMARY KEY, name TEXT)")

Exemplos

Para ver exemplos e casos de uso mais abrangentes, consulte exemplos do conector do Aurora DSQL para Go.