Select your cookie preferences

We use essential cookies and similar tools that are necessary to provide our site and services. We use performance cookies to collect anonymous statistics, so we can understand how customers use our site and make improvements. Essential cookies cannot be deactivated, but you can choose “Customize” or “Decline” to decline performance cookies.

If you agree, AWS and approved third parties will also use cookies to provide useful site features, remember your preferences, and display relevant content, including relevant advertising. To accept or decline all non-essential cookies, choose “Accept” or “Decline.” To make more detailed choices, choose “Customize.”

Migrate from version 1 or 2 to version 3 of the AWS SDK for Ruby - AWS SDK for Ruby

Migrate from version 1 or 2 to version 3 of the AWS SDK for Ruby

The purpose of this topic is to help you migrate from version 1 or 2 of the AWS SDK for Ruby to version 3.

Side-by-side usage

It isn’t necessary to replace the version 1 or 2 of the AWS SDK for Ruby with version 3. You can use them together in the same application. See this blog post for more information.

A quick example follows.

require 'aws-sdk-v1' # version 1 require 'aws-sdk' # version 2 require 'aws-sdk-s3' # version 3 s3 = AWS::S3::Client.new # version 1 s3 = Aws::S3::Client.new # version 2 or 3

You don’t need to rewrite existing working version 1 or 2 code to start using the version 3 SDK. A valid migration strategy is to only write new code against the version 3 SDK.

General differences

Version 3 differs from version 2 in one important way.

  • Each service is available as a separate gem.

Version 2 differs from version 1 in several important ways.

  • Different root namespace –Aws versus AWS. This enables side-by-side usage.

  • Aws.config– Now a vanilla Ruby hash, instead of a method.

  • Strict constructor options - When constructing a client or resource object in the version 1 SDK, unknown constructor options are ignored. In version 2, unknown constructor options trigger an ArgumentError. For example:

    # version 1 AWS::S3::Client.new(http_reed_timeout: 10) # oops, typo'd option is ignored # version 2 Aws::S3::Client.new(http_reed_timeout: 10) # => raises ArgumentError

Client differences

There are no differences between the client classes in version 2 and version 3.

Between version 1 and version 2, the client classes have the fewest external differences. Many service clients will have compatible interfaces after client construction. Some important differences:

  • Aws::S3::Client - The version 1 Amazon S3 client class was hand-coded. Version 2 is generated from a service model. Method names and inputs are very different in version 2.

  • Aws::EC2::Client- Version 2 uses plural names for output lists, version 1 uses the suffix _set. For example:

    # version 1 resp = AWS::EC2::Client.new.describe_security_groups resp.security_group_set #=> [...] # version 2 resp = Aws::EC2::Client.new.describe_security_groups resp.security_groups #=> [...]
  • Aws::SWF::Client– Version 2 uses structured responses, where version 1 uses vanilla Ruby hashes.

  • Service class renames – Version 2 uses a different name for multiple services:

    • AWS::SimpleWorkflow has become Aws::SWF

    • AWS::ELB has become Aws::ElasticLoadBalancing

    • AWS::SimpleEmailService has become Aws::SES

  • Client configuration options – Some of the version 1 configuration options are renamed in version 2. Others are removed or replaced. Here are the primary changes:

    • :use_ssl has been removed. Version 2 uses SSL everywhere. To disable SSL you must configure an :endpoint that uses http://.

    • :ssl_ca_file is now :ssl_ca_bundle

    • :ssl_ca_path is now :ssl_ca_directory

    • Added :ssl_ca_store.

    • :endpoint must now be a fully qualified HTTP or HTTPS URI instead of a hostname.

    • Removed :*_port options for each service, now replaced by :endpoint.

    • :user_agent_prefix is now :user_agent_suffix

Resource differences

There are no differences between the resource interfaces in version 2 and version 3.

There are significant differences between the resource interfaces in version 1 and version 2. Version 1 was entirely hand-coded, where as version 2 resource interfaces are generated from a model. Version 2 resource interfaces are significantly more consistent. Some of the systemic differences include:

  • Separate resource class – In version 2, the service name is a module, not a class. In this module, it is the resource interface:

    # version 1 s3 = AWS::S3.new # version 2 s3 = Aws::S3::Resource.new
  • Referencing resources – The version 2 SDK separates collections and individual resource getters into two different methods:

    # version 1 s3.buckets['bucket-name'].objects['key'].delete # version 2 s3.bucket('bucket-name').object('key').delete
  • Batch operations – In version 1, all batch operations were hand-coded utilities. In version 2, many batch operations are autogenerated batching operations over the API. Version 2 batching interfaces are very different from version 1.

PrivacySite termsCookie preferences
© 2025, Amazon Web Services, Inc. or its affiliates. All rights reserved.