Upgrading from Version 2 to Version 3 of the AWS SDK for Ruby

Recently we announced the modularization of the AWS SDK for Ruby. This blog post will focus on how to upgrade your application to use the new service specific gems.

This blog post is divided up into sections based on how you currently depend on the AWS SDK for Ruby today. Find the section below that describes how you load the SDK today, and it will guide you in upgrading. Since version 3 is backwards compatible with version 2, you should not need to make additional changes beyond those described below.

Bunder: gem ‘aws-sdk’, ‘~>2’

Congratulations! You are following recommended best practices for how to depend on the SDK today. The simplest path to upgrade is to change the version from 2 to 3.

#gem 'aws-sdk', '~> 2'
gem 'aws-sdk', '~> 3'

See the section about using service specific gems below.

Bundler: gem ‘aws-sdk’ (without version)

It is not recommended to depend on the SDK without a major version constraint. Fortunately, version 3 is backwards compatible with version 2. Bundle updating your dependencies will work, but consider yourself lucky! You should add the version constraint to protect from future major version changes:

#gem 'aws-sdk'
gem 'aws-sdk', '~> 3'

See the section about using service specific gems below.

Bundler: gem ‘aws-sdk-core’, ‘~> 2’

The aws-sdk-core gem changes signification from version 2 to 3. In version 3, the core gem no longer defines any services. It will only contain shared utilities, such as credential providers, serializers, etc. To upgrade you must make two changes:

• Change your bundler dependency
• Change your ruby require statements

In bundler, replace aws-sdk-core, with aws-sdk:

#gem 'aws-sdk-core', '~> 2'
gem 'aws-sdk', '~> 3'

In code, replace any require statements on aws-sdk-core with aws-sdk.

#require 'aws-sdk-core'
require 'aws-sdk'

See the section about using service specific gems below.

Bundler: gem ‘aws-sdk-core’ (without version)

If you happen to bundle update before changing your Gemfile, your application will be broken. Version 3 of the aws-sdk-core gem no longer defines service modules and clients. It is a shared dependency of the 75+ service gems. To upgrade you must make two changes:

• Change your bundler dependency
• Change your ruby require statements

In bundler, replace aws-sdk-core, with aws-sdk:

#gem 'aws-sdk-core'
gem 'aws-sdk', '~> 3'

In code, replace any require statements on aws-sdk-core with aws-sdk.

#require 'aws-sdk-core'
require 'aws-sdk'

See the section about using service specific gems below.

Bundler: gem ‘aws-sdk-resource’ (with or without version)

In version 3, the aws-sdk-resources gem has been removed. This gem will not receive any further updates. Each service gem contains both the client interface, and the resource interfaces. To upgrade you must make two changes:

• Change your bundler dependency
• Change your ruby require statements

#gem 'aws-sdk-resources', '~> 2'
gem 'aws-sdk', '~> 3'

In code, replace any require statements on aws-sdk-resources with aws-sdk.

#require 'aws-sdk-core'
require 'aws-sdk'

See the section about using service specific gems below.

Using the Service Specific Gems

Each of the instructions above suggested using version 3 of the aws-sdk gem. This will work and is the shortest path to upgrading. It will however install 75+ service specific gems. You may choose to replace your dependency on the aws-sdk gem with service specific gems.

If my application depends on Amazon DynamoDB and Amazon S3, I could make the following changes:

In my Gemfile:

#gem 'aws-sdk', '~> 3'
gem 'aws-sdk-dynamodb', '~> 1'
gem 'aws-sdk-s3', '~> 1'

In my code:

#require 'aws-sdk'
require 'aws-sdk-s3'
require 'aws-sdk-dynamodb'

If you are a library maintainer, and you depend on the AWS SDK for Ruby, you should use service specific gems. Do no force your users to install every AWS service gem if you only depend on one.

Conclusion

Upgrading should be very simple. If you encounter any backwards incompatible changes, please open a GitHub issue. The modularized SDK will be in preview for a short period to hopefully catch these issues before going GA. You can also catch us in the gitter channel.