https://github.com/pgx-contrib/pgxaws
AWS IAM authentication for pgx v5 — RDS, Aurora DSQL, and query caching with DynamoDB & S3
https://github.com/pgx-contrib/pgxaws
aurora aws cache dsql dynamodb golang iam pgx postgresql rds s3
Last synced: about 1 month ago
JSON representation
AWS IAM authentication for pgx v5 — RDS, Aurora DSQL, and query caching with DynamoDB & S3
- Host: GitHub
- URL: https://github.com/pgx-contrib/pgxaws
- Owner: pgx-contrib
- License: mit
- Created: 2024-07-31T06:13:52.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2026-05-04T13:34:44.000Z (about 1 month ago)
- Last Synced: 2026-05-04T15:34:39.761Z (about 1 month ago)
- Topics: aurora, aws, cache, dsql, dynamodb, golang, iam, pgx, postgresql, rds, s3
- Language: Go
- Homepage: https://pkg.go.dev/github.com/pgx-contrib/pgxaws
- Size: 314 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# pgxaws
[](https://github.com/pgx-contrib/pgxaws/actions/workflows/ci.yml)
[](https://github.com/pgx-contrib/pgxaws/releases)
[](https://pkg.go.dev/github.com/pgx-contrib/pgxaws)
[](LICENSE)
[](go.mod)
[](https://github.com/jackc/pgx)
[](https://github.com/aws/aws-sdk-go-v2)
AWS IAM authentication for [pgx v5](https://github.com/jackc/pgx), 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](https://github.com/pgx-contrib/pgxcache))
- **S3QueryCacher** — query result caching backed by S3 (implements [pgxcache](https://github.com/pgx-contrib/pgxcache))
## Installation
```bash
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.
```go
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](https://github.com/pgx-contrib/pgxcache):
```go
// 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](https://github.com/pgx-contrib/pgxcache):
```go
// 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
```bash
nix develop # enter shell with Go
go tool ginkgo run -r
```
### Run tests
```bash
# 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](LICENSE)