AWS Advanced Go Wrapper

← Back to Home

The AWS Advanced Go Wrapper is a Go database driver wrapper that provides AWS-specific enhancements for connecting to Amazon Aurora and RDS databases.

Latest Version: 2025-10-17
Repository: github.com/aws/aws-advanced-go-wrapper

Installation

go get github.com/aws/aws-advanced-go-wrapper

Quick Start

PostgreSQL:

import (
    "database/sql"
    _ "github.com/aws/aws-advanced-go-wrapper/pgdriver"
)

db, err := sql.Open("aws-wrapper:postgres", 
    "host=db-instance.cluster-xyz.us-east-1.rds.amazonaws.com "+
    "user=username password=password dbname=mydb "+
    "plugins=failover,iam")
if err != nil {
    panic(err)
}
defer db.Close()

MySQL:

import (
    "database/sql"
    _ "github.com/aws/aws-advanced-go-wrapper/mysqldriver"
)

db, err := sql.Open("aws-wrapper:mysql",
    "username:password@tcp(db-instance.cluster-xyz.us-east-1.rds.amazonaws.com:3306)/mydb?plugins=failover,iam")
if err != nil {
    panic(err)
}
defer db.Close()

Key Features

Failover Plugin: Automatic failover for Aurora clusters
IAM Authentication Plugin: AWS IAM database authentication
Secrets Manager Plugin: Credential management via AWS Secrets Manager
Read/Write Splitting Plugin: Intelligent query routing
Host Monitoring Plugin: Connection health tracking
Driver Support: Compatible with pgx (PostgreSQL) and go-sql-driver/mysql (MySQL)

Configuration

Configure plugins via connection string or DSN:

db, err := sql.Open("aws-wrapper:postgres",
    "host=myhost plugins=failover,iam failoverTimeoutMs=60000")

Common Configurations

Basic Failover

import (
    "database/sql"
    _ "github.com/aws/aws-advanced-go-wrapper/pgdriver"
)

db, err := sql.Open("aws-wrapper:postgres", 
    "host=cluster.region.rds.amazonaws.com "+
    "user=username password=password dbname=mydb "+
    "plugins=failover")
if err != nil {
    panic(err)
}
defer db.Close()

rows, err := db.Query("SELECT * FROM users")

IAM Authentication

db, err := sql.Open("aws-wrapper:postgres",
    "host=cluster.region.rds.amazonaws.com "+
    "user=iamuser dbname=mydb "+
    "plugins=failover,iam "+
    "region=us-east-1")

Secrets Manager

db, err := sql.Open("aws-wrapper:postgres",
    "plugins=failover,secretsManager "+
    "secretId=arn:aws:secretsmanager:region:account:secret:name "+
    "region=us-east-1")

Read/Write Splitting

db, err := sql.Open("aws-wrapper:postgres",
    "host=cluster.region.rds.amazonaws.com "+
    "user=username password=password dbname=mydb "+
    "plugins=failover,readWriteSplitting")

// Reads go to reader
rows, err := db.Query("SELECT * FROM users")

// Writes go to writer
_, err = db.Exec("INSERT INTO users VALUES ($1, $2)", "name", "email")

MySQL Example

import (
    "database/sql"
    _ "github.com/aws/aws-advanced-go-wrapper/mysqldriver"
)

db, err := sql.Open("aws-wrapper:mysql",
    "username:password@tcp(cluster.region.rds.amazonaws.com:3306)/mydb?plugins=failover,iam")
if err != nil {
    panic(err)
}
defer db.Close()

Connection Pooling

db, err := sql.Open("aws-wrapper:postgres", dsn)
if err != nil {
    panic(err)
}

// Configure connection pool
db.SetMaxOpenConns(25)
db.SetMaxIdleConns(5)
db.SetConnMaxLifetime(5 * time.Minute)
db.SetConnMaxIdleTime(10 * time.Minute)

Context Support

ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()

rows, err := db.QueryContext(ctx, "SELECT * FROM users WHERE id = $1", userID)
if err != nil {
    return err
}
defer rows.Close()

Transaction Handling

tx, err := db.Begin()
if err != nil {
    return err
}
defer tx.Rollback()

_, err = tx.Exec("INSERT INTO users VALUES ($1, $2)", "name", "email")
if err != nil {
    return err
}

err = tx.Commit()

AWS Advanced Drivers