AWS SDK for Ruby (Version 3)

The AWS SDK for Ruby follows semantic versioning. You can safely depend on a major version, as minor and patch updates are guaranteed to be backwards compatible.

To view specific changes for a service, check the CHANGELOG.md file located at the root of that specific gem's directory (e.g., gems/aws-sdk-s3/CHANGELOG.md) or visit the service's page on RubyGems.org and look under the 'LINKS' section.

The recommended way to use V3 is to install only the specific service gems your project requires. This reduces the number of dependencies in your project. You must update both your Gemfile and your require statements in your code files.

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

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

s3 = Aws::S3::Client.new
ddb = Aws::DynamoDB::Client.new

Because aws-sdk-core in V2 does not contain service clients, you must change your Gemfile to use aws-sdk (version 3) or specific service gems, and update your require statements accordingly.

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

# Code Files
require 'aws-sdk'

s3 = Aws::S3::Client.new

Many AWS operations return truncated results. The SDK provides two ways to handle paging:

Automatic Enumeration

Every AWS response object is enumerable. Calling .each on a response object will automatically make subsequent API calls to fetch all pages of results.

Manual Paging Control

You can manually control paging using helper methods on the response object:

• resp.last_page?: Returns true if there are no more pages.
• resp.next_page?: Returns true if another page exists.
• resp.next_page: Returns a new response object for the next page of results.

If you maintain a library that depends on the AWS SDK, you have two upgrade options:

1. Preferred Path: Switch to specific service gems (e.g., aws-sdk-dynamodb) to keep your library's dependency footprint small.
2. Simplest Path: Open the dependency range for aws-sdk or aws-sdk-resources to allow V3. This is easier but adds many unnecessary gems to your users' dependency chains.

# Preferred: Gemspec File
Gem::Specification.new do |spec|
  spec.add_dependency('aws-sdk-dynamodb', '~> 1')
end

# Simplest: Gemspec File
Gem::Specification.new do |spec|
  spec.add_dependency('aws-sdk', '>= 2.0', '< 4')
end

If your project currently uses the monolithic aws-sdk gem, you can upgrade to V3 by updating your Gemfile. Note that this will pull in a large number of new dependencies because V3 is modularized. The modules, classes, and methods remain backwards compatible.

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

In aws-sdk-core v3.0.0, service modules were removed. The aws-sdk-core gem now only contains shared utilities like credential providers and logging. To use specific AWS services, you must now use their dedicated gems.

• If you previously used aws-sdk-core to access Amazon S3, replace it with aws-sdk-s3.
• If you want to load all available AWS service gems at once, use the aws-sdk gem.