Services or capabilities described in AWS documentation might vary by Region. To see the differences applicable to the AWS European Sovereign Cloud Region, see the AWS European Sovereign Cloud User Guide.

Aurora DSQL Connector for Go pgx

The Aurora DSQL Connector for Go wraps pgx with automatic IAM authentication. The connector handles token generation, SSL configuration, and connection management so you can focus on your application logic.

About the connector

Aurora DSQL requires IAM-based authentication with time-limited tokens that existing Go PostgreSQL drivers do not natively support. The Aurora DSQL Connector for Go adds an authentication layer on top of the pgx driver that handles IAM token generation, allowing you to connect to Aurora DSQL without changing your existing pgx workflows.

What is Aurora DSQL Authentication?

In Aurora DSQL, authentication involves:

The Aurora DSQL Connector for Go is designed to understand these requirements and automatically generate IAM authentication tokens when establishing connections.

Benefits of the Aurora DSQL Connector for Go

The Aurora DSQL Connector for Go allows you to continue using your existing pgx workflows while enabling IAM authentication through:

Key features

Prerequisites

The connector uses the AWS SDK for Go v2 default credential chain, which resolves credentials in the following order:

Installation

Install the connector using Go modules:

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

Quick start

The following example shows how to create a connection pool and execute a query:

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

Configuration options

The connector supports the following configuration options:

Connection string format

The connector supports PostgreSQL and DSQL connection string formats:

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

Supported query parameters:

Examples:

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

Advanced usage

Host configuration

The connector supports two host formats:

Full endpoint (region auto-detected):

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

Cluster ID (region required):

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

Pool configuration tuning

Configure the connection pool for your 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,
})

Single connection usage

For simple scripts or when connection pooling is not needed:

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

Using AWS profiles

Specify an AWS profile for credentials:

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

OCC retry

Aurora DSQL uses optimistic concurrency control (OCC). When two transactions modify the same data, the first to commit wins and the second receives an OCC error.

The occretry package provides helpers for automatic retry with exponential backoff and jitter. Install it with:

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

Use WithRetry for transactional writes:

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

For DDL or single statements, use ExecWithRetry:

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

Examples

For more comprehensive examples and use cases, refer to the Aurora DSQL Connector for Go examples.