Skip to content

Latest commit

 

History

History

ruby-pg

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
src
src
 
 
test
test
 
 
Gemfile
Gemfile
 
 
README.md
README.md
 
 
Rakefile
Rakefile
 
 

README.md

Aurora DSQL with ruby-pg

Overview

This code example demonstrates how to use ruby-pg with Amazon Aurora DSQL. The example shows you how to connect to an Aurora DSQL cluster and perform basic database operations.

Aurora DSQL is a distributed SQL database service that provides high availability and scalability for your PostgreSQL-compatible applications. Ruby-pg is a popular PostgreSQL adapter for Ruby that allows you to interact with PostgreSQL databases using Ruby code.

About the code example

This example uses the Aurora DSQL Ruby-pg Connector which automatically handles IAM token generation for authentication.

The preferred example (src/example_preferred.rb) uses AuroraDsql::Pg.create_pool() with automatic token management, connection pooling, and OCC retry.

An alternative manual token approach is available in src/alternatives/manual_token/. This example uses the raw pg gem with aws-sdk-dsql to generate tokens directly, which is useful for custom authentication flows or when you need finer-grained control over connections.

The manual token alternative demonstrates a flexible connection approach that works for both admin and non-admin users:

  • When connecting as an admin user, the example uses the public schema and generates an admin authentication token.
  • When connecting as a non-admin user, the example uses a custom myschema schema and generates a standard authentication token.

⚠️ Important

  • Running this code might result in charges to your AWS account.
  • We recommend that you grant your code least privilege. At most, grant only the minimum permissions required to perform the task. For more information, see Grant least privilege.
  • This code is not tested in every AWS Region. For more information, see AWS Regional Services.

Run the example

Prerequisites

ruby --version

  • Libpq is required by ruby-pg. It is included with PostgreSQL installations. On systems without PostgreSQL, install it via a package manager:

    • Amazon Linux: sudo yum install libpq-devel
    • macOS (Homebrew): brew install libpq
    • Or download from the official website

    You may need to add libpq to your PATH:

    export PATH="$PATH:<your installed location>/libpq/bin"

  • You must have an Aurora DSQL cluster. For information about creating an Aurora DSQL cluster, see the Getting started with Aurora DSQL guide.

  • If connecting as a non-admin user (manual token alternative), ensure the user is linked to an IAM role and is granted access to the myschema schema. See the Using database roles with IAM roles guide.

Run the code

The example demonstrates the following operations:

  • Opening a connection pool to an Aurora DSQL cluster
  • Creating a table
  • Inserting data with transactional writes
  • Running concurrent queries using the pool

Note: Running the example will use actual resources in your AWS account and may incur charges.

Install dependencies:

bundle install

Set environment variables for your cluster details:

# e.g. "foo0bar1baz2quux3quuux4.dsql.us-east-1.on.aws"
export CLUSTER_ENDPOINT="<your cluster endpoint>"

Run the preferred example:

ruby src/example_preferred.rb

To run the manual token alternative (requires additional environment variables):

export REGION="<your cluster region>"
export CLUSTER_USER="<your cluster user>"

ruby src/alternatives/manual_token/example.rb

Run tests:

bundle exec rake test

Additional resources

Note: The connector automatically extracts the region from the cluster endpoint and defaults to the postgres database.

Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.

SPDX-License-Identifier: MIT-0