AWS SDK for Go Version 2 – General Availability

We are excited to announce the General Availability (GA) release of the AWS SDK for Go version 2 (v2). This release follows the Release candidate of the AWS SDK for Go v2. Version 2 incorporates customer feedback from version 1 and takes advantage of modern Go language features.

The AWS SDK for Go v2 requires Go 1.15 or higher, and offers significant performance improvements in CPU and memory utilization over version 1. Review our Developer Guide to get started with AWS SDK for Go v2 or review the migration guide if you already use version 1.

What’s New in Version 2

Modularization

AWS SDK for Go v2 packages each AWS service client as an independent Go module, enabling you to model service dependencies in your application, and independently control service client and feature updates. This reduces the individual module size. We take advantage of Go modules, which became the default development mode in Go 1.13, and follow the Go module versioning strategy.

For example, the following commands add the Amazon DynamoDB client to your application.

$ go get github.com/aws/aws-sdk-go-v2/config
$ go get github.com/aws/aws-sdk-go-v2/service/dynamodb

See the Getting Started with the AWS SDK for Go V2 section of the developer guide for details.

Intuitive Configuration

AWS SDK for Go v2 provides a single Config type. This simplifies the Session and Config type interaction from the v1 SDK. In addition, we’ve moved the service-specific configuration flags to the individual service client option types. This improves discoverability of configuration values supported by the service client.

Use LoadDefaultConfig in the config package to create the default config value, and load configuration values from the external configuration sources. Here’s a quick example configuration in AWS SDK for Go v2.

// Load SDK configuration with shared config profile.
cfg, err := config.LoadDefaultConfig(context.TODO(),
    config.WithSharedConfigProfile("profile-name"),
)
// Create Amazon S3 API client using path style addressing.
client := s3.NewFromConfig(cfg, func(o *s3.Options) {
    o.UsePathStyle = true
})

See the Configuring the AWS SDK for Go V2 section of the developer guide for details.

Simplified API client methods

AWS SDK for Go v2 consolidates multiple ways to make an API call, providing a simpler API client. Service operations are now invoked on the client directly, with each operation method taking the API input along with context, and returning the response or error. This simplification enables easier mocking of the client when unit-testing your application.

client := s3.New(cfg)

// call operation with context
result, err := client.GetObject(context.TODO(), params)

Fewer API Parameter Pointers

AWS SDK for Go v2 reduces the amount of pointer references you are required to pass to the SDK. The SDK takes advantage of API model data to render types as values when possible, including map and slice elements. Additionally enums are now typed string aliases, generated as constants and used directly in your code. This improves experience with your IDE’s type assistance for enums.

The following example shows how value types for the Amazon Elastic Compute Cloud (Amazon EC2) DescribeInstance API’s Filters member slices are set.

result, err := client.DescribeInstances(context.TODO(), &ec2.DescribeInstancesInput {
    Filters: []types.Filter {
        {
            Name: aws.String("instance-state-name"),
            Values: []string {
                "running", 
                "pending", 
                "stopped",
           },
        },
    },
})

In the above example Filters and Values member are now value types, instead of pointers as in the v1 SDK.

Paginate with Iterator

Version 1 of the SDK uses call-back functions for paginators, and a single context across paginated operation calls. This makes it fairly difficult to handle errors, or control paginated operation call rate.

Version 2 of the SDK addresses the above issues, and provides context per page. It also enables easy iteration over API results that span multiple page. Here’s a quick example of paginator usage with v2 SDK:

p :=  s3.NewListObjectsV2Paginator(client, params)
 
// Iterate through the Amazon S3 object pages. 
for p.HasMorePages() {
    // next page takes a context
    page, err := p.NextPage(context.TODO())
    if err != nil {
        return fmt.Errorf("failed to get a page, %w", err)
    }
    fmt.Println("page contents: ", page.Contents)
}

Performance Improvements

AWS SDK for Go v2 generates type specific serializers and deserializers, eliminating the need for runtime-based reflection. Eliminating reflection results in a marked improvement in CPU and memory utilization when using the API clients.

Reviewing the results for our benchmark program using Amazon DynamoDB client, we notice significant overall improvements in CPU and memory utilization. We note around 50% reduction in CPU time, 32% reduction in number of bytes allocated, and 58% reduction in total allocations used!

We will continue to benchmark and analyze our clients and find opportunities to further optimize and reduce latency in the serialization layer. To explore more, take a look at our benchmark module.

Additional Features

We have also added following features to improve your experience :

Amazon DynamoDB AttributeValue and Expression Packages: Use the attributevalue package to easily translate your application’s Go types to Amazon DynamoDB AttributeValue types. Use the expression package to fluently build attribute updates and conditions. The following commands add the Amazon DynamoDB AttributeValue and Expression packages to your application.
```
$ go get github.com/aws/aws-sdk-go-v2/feature/dynamodb/attributevalue
$ go get github.com/aws/aws-sdk-go-v2/feature/dynamodb/expression
```
Amazon S3 Transfer Manager: Use this feature to easily, reliably, and efficiently transfer large files to and from Amazon S3 in multiple parts using a customizable number of goroutines. Explore more using our migration guide. The following command adds the Amazon S3 Transfer Manager to your application.
```
$ go get github.com/aws/aws-sdk-go-v2/feature/s3/manager
```
Error Wrapping: Error types have been redesigned to take advantage of error wrapping features introduced in Go 1.13.
Extensibility: New middleware design enables your application to extend or customize the request pipeline to fit your use case.
Improved discoverability and usage: API types are now in a separate types package. This makes it easier to see the set of operations supported by a service client and the respective inputs and outputs.
Waiters: Easily validate AWS resources are in a particular state. Use waiters before performing additional actions.

You can get started now using the AWS SDK for Go version 2. Documentation is available in our Developer Guide, the API Reference, and the migration guide. We value your feedback, so please tell us what you like and don’t like by opening an issue on GitHub. If you have feedback for version 2, create a Discussion on GitHub or upvote an existing issue.

AWS Developer Tools Blog