pgxaws

AWS IAM authentication for pgx v5, supporting Amazon RDS and Aurora DSQL connections, plus query caching backends using DynamoDB and S3.

Features

• IAM Authentication for Amazon RDS and Aurora DSQL via pgx.ConnConfig.BeforeConnect
• Automatic token refresh — tokens are renewed every 10 minutes in the background
• DynamoQueryCacher — query result caching backed by DynamoDB (implements pgxcache)
• S3QueryCacher — query result caching backed by S3 (implements pgxcache)

Installation

go get github.com/pgx-contrib/pgxaws

Usage

Connector (RDS / DSQL)

The Connector automatically detects whether the host is an RDS or DSQL endpoint and issues the appropriate IAM auth token.

config, err := pgxpool.ParseConfig(os.Getenv("PGX_DATABASE_URL"))
if err != nil {
    panic(err)
}

ctx := context.TODO()
// Create a new pgxaws.Connector
connector, err := pgxaws.Connect(ctx)
if err != nil {
    panic(err)
}
// close the connector
defer connector.Close()

config.BeforeConnect = connector.BeforeConnect

// Create a new pgxpool with the config
pool, err := pgxpool.NewWithConfig(ctx, config)
if err != nil {
    panic(err)
}
defer pool.Close()

rows, err := pool.Query(ctx, "SELECT * from organization")
if err != nil {
    panic(err)
}
defer rows.Close()

type Organization struct {
    Name string `db:"name"`
}

for rows.Next() {
    organization, err := pgx.RowToStructByName[Organization](rows)
    if err != nil {
        panic(err)
    }
    fmt.Println(organization.Name)
}

DynamoQueryCacher

Cache query results in DynamoDB using pgxcache:

// Create a new cacher
cacher := &pgxaws.DynamoQueryCacher{
    Client: dynamodb.NewFromConfig(cfg),
    Table:  "queries",
}

// create a new querier
querier := &pgxcache.Querier{
    Options: &pgxcache.QueryOptions{
        MaxLifetime: 30 * time.Second,
        MaxRows:     1,
    },
    Cacher:  cacher,
    Querier: conn,
}

rows, err := querier.Query(context.TODO(), "SELECT * from customer")

S3QueryCacher

Cache query results in S3 using pgxcache:

// Create a new cacher
cacher := &pgxaws.S3QueryCacher{
    Client: s3.NewFromConfig(cfg),
    Bucket: "queries",
}

// create a new querier
querier := &pgxcache.Querier{
    Options: &pgxcache.QueryOptions{
        MaxLifetime: 30 * time.Second,
        MaxRows:     1,
    },
    Cacher:  cacher,
    Querier: conn,
}

rows, err := querier.Query(context.TODO(), "SELECT * from customer")

Development

DevContainer

Open in VS Code with the Dev Containers extension. The environment provides Go, PostgreSQL 18, and Nix automatically.

PGX_DATABASE_URL=postgres://vscode@postgres:5432/pgxaws?sslmode=disable

Nix

nix develop          # enter shell with Go
go tool ginkgo run -r

Run tests

# Unit tests only (no database required)
go tool ginkgo run -r

# With integration tests
export PGX_DATABASE_URL="postgres://localhost/pgxaws?sslmode=disable"
go tool ginkgo run -r

Integration tests require real AWS infrastructure (RDS/DSQL/DynamoDB/S3) and are skipped automatically when credentials are not set.

License

MIT