aurora-dsql-ruby-pg 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0af7ba782ac3c43e13044ec8ef592bf162fae89aabba8228747542d80e1eb79b
+  data.tar.gz: 8fcb277ac218333d5835dcca93628f3897c59770409f09970cd4ec4d6d193c86
+SHA512:
+  metadata.gz: 8a5478e20f6359ec8b5641a2f075711b0a8c642614c8d891f7d258b0a19f3bcb5fdb5e466e8032685a59eb0228f03733d6e2f250291191de1766b83fe4426fbd
+  data.tar.gz: f73b1322c292ae87a9583636246a3e1b7d9e1a78caf7b301efe7afd070e9cd7852cc5eb3f45da255af2a2c20ab5d9d0ba542303b64e5ab8357003b93ddb5c8b7

data/LICENSE

@@ -0,0 +1,175 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.

data/NOTICE

@@ -0,0 +1 @@
+Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.

data/README.md

@@ -0,0 +1,227 @@
+# Aurora DSQL Ruby pg Connector
+
+## Overview
+
+A Ruby connector for Amazon Aurora DSQL that wraps the [pg](https://github.com/ged/ruby-pg) gem with automatic IAM authentication. The connector handles token generation, SSL configuration, and connection pooling so you can focus on your application logic.
+
+## Features
+
+- Automatic IAM token generation
+- Connection pooling via `connection_pool` gem with max_lifetime enforcement
+- Single connection support for simpler use cases
+- Flexible host configuration (full endpoint or cluster ID)
+- Region auto-detection from endpoint hostname
+- Support for AWS profiles and custom credentials providers
+- SSL always enabled with `verify-full` mode and direct TLS negotiation (libpq 17+)
+- Opt-in OCC retry with exponential backoff on `pool.with`
+
+## Prerequisites
+
+- Ruby 3.1 or later
+- AWS credentials configured (see [Credentials Resolution](#credentials-resolution) below)
+- An Aurora DSQL cluster
+
+For information about creating an Aurora DSQL cluster, see the [Getting started with Aurora DSQL](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/getting-started.html) guide.
+
+### Credentials Resolution
+
+The connector uses the [AWS SDK for Ruby default credential chain](https://docs.aws.amazon.com/sdkref/latest/guide/standardized-credentials.html), which resolves credentials in the following order:
+
+1. **Environment variables** (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and optionally `AWS_SESSION_TOKEN`)
+2. **Shared credentials file** (`~/.aws/credentials`) with optional profile via `AWS_PROFILE` or `profile` config
+3. **Shared config file** (`~/.aws/config`)
+4. **IAM role for Amazon EC2/ECS/Lambda** (instance metadata or task role)
+
+The first source that provides valid credentials is used. You can override this by specifying `profile` for a specific AWS profile or `credentials_provider` for complete control over credential resolution.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "aurora-dsql-ruby-pg"
+```
+
+Or install directly:
+
+```bash
+gem install aurora-dsql-ruby-pg
+```
+
+## Quick Start
+
+```ruby
+require "aurora_dsql_pg"
+
+# Create a connection pool with OCC retry enabled
+pool = AuroraDsql::Pg.create_pool(
+  host: "your-cluster.dsql.us-east-1.on.aws",
+  occ_max_retries: 3
+)
+
+# Read
+pool.with do |conn|
+  result = conn.exec("SELECT 'Hello, DSQL!'")
+  puts result[0]["?column?"]
+end
+
+# Write — you must wrap writes in a transaction
+pool.with do |conn|
+  conn.transaction do
+    conn.exec_params("INSERT INTO users (id, name) VALUES (gen_random_uuid(), $1)", ["Alice"])
+  end
+end
+
+pool.shutdown
+```
+
+## Configuration Options
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `host` | `String` | (required) | Cluster endpoint or cluster ID |
+| `region` | `String` | (auto-detected) | AWS region |
+| `user` | `String` | `"admin"` | Database user |
+| `database` | `String` | `"postgres"` | Database name |
+| `port` | `Integer` | `5432` | Database port |
+| `profile` | `String` | `nil` | AWS profile name |
+| `token_duration` | `Integer` | `900` (15 min) | Token validity in seconds |
+| `credentials_provider` | `Aws::Credentials` | `nil` | Custom credentials |
+| `pool_size` | `Integer` | `5` | Connection pool size |
+| `checkout_timeout` | `Integer` | `5` | Seconds to wait for a pool connection |
+| `max_lifetime` | `Integer` | `3300` (55 min) | Max connection lifetime in seconds |
+| `application_name` | `String` | `nil` | ORM prefix for application_name |
+| `logger` | `Logger` | `nil` | Logger for OCC retry warnings |
+| `occ_max_retries` | `Integer` | `nil` (disabled) | Max OCC retries on `pool.with`; enables retry when set |
+
+## Connection String Format
+
+```ruby
+pool = AuroraDsql::Pg.create_pool(
+  "postgres://admin@cluster.dsql.us-east-1.on.aws/postgres?profile=dev"
+)
+```
+
+## Single Connection Usage
+
+```ruby
+conn = AuroraDsql::Pg.connect(host: "cluster.dsql.us-east-1.on.aws")
+conn.exec("SELECT 1")
+conn.close
+```
+
+The `Connection` wrapper delegates common methods (`exec_params`, `query`, `transaction`, `close`, `finished?`) directly. All other `PG::Connection` methods (e.g., `exec`, `prepare`, `exec_prepared`, `copy_data`) are also available via delegation. The underlying `PG::Connection` can be accessed directly via `conn.pg_conn` if needed.
+
+## OCC Retry
+
+Aurora DSQL uses optimistic concurrency control (OCC). When two transactions modify the same data, the first to commit wins and the second receives an OCC error.
+
+OCC retry is **opt-in**. Set `occ_max_retries` when creating the pool to enable automatic retry with exponential backoff and jitter on `pool.with`:
+
+```ruby
+pool = AuroraDsql::Pg.create_pool(
+  host: "your-cluster.dsql.us-east-1.on.aws",
+  occ_max_retries: 3  # retries up to 3 times on OCC conflict
+)
+```
+
+> **Important:** `pool.with` does NOT automatically wrap your block in a transaction. You must call `conn.transaction` yourself for write operations. On OCC conflict the entire block is re-executed, so it should contain only database operations and be safe to retry.
+
+```ruby
+pool.with do |conn|
+  conn.transaction do
+    conn.exec_params("UPDATE accounts SET balance = balance - $1 WHERE id = $2", [100, from_id])
+    conn.exec_params("UPDATE accounts SET balance = balance + $1 WHERE id = $2", [100, to_id])
+  end
+end
+```
+
+To skip retry on individual calls, pass `retry_occ: false`:
+
+```ruby
+pool.with(retry_occ: false) do |conn|
+  conn.exec("SELECT 1")
+end
+```
+
+For custom retry configuration (different backoff, etc.), use the `OCCRetry` module directly. Unlike `pool.with`, `OCCRetry.with_retry` automatically wraps the block in a transaction:
+
+```ruby
+AuroraDsql::Pg::OCCRetry.with_retry(pool, max_retries: 10) do |conn|
+  conn.exec_params("UPDATE ...", [...])
+end
+```
+
+For single SQL statements (DDL or DML), `exec_with_retry` provides a simple convenience without transaction wrapping:
+
+```ruby
+AuroraDsql::Pg::OCCRetry.exec_with_retry(pool, "CREATE TABLE users (id UUID PRIMARY KEY)")
+```
+
+To see OCC retries in your logs, pass a `logger` when creating the pool:
+
+```ruby
+pool = AuroraDsql::Pg.create_pool(
+  host: "your-cluster.dsql.us-east-1.on.aws",
+  occ_max_retries: 3,
+  logger: Logger.new(STDOUT)
+)
+```
+
+## Examples
+
+The `example/` directory contains runnable examples demonstrating various patterns:
+
+| Example | Description |
+|---------|-------------|
+| [example_preferred](example/src/example_preferred.rb) | Recommended: Connection pool with concurrent queries |
+| [manual_token](example/src/alternatives/manual_token/) | Manual IAM token generation without the connector |
+
+### Running examples
+
+```bash
+export CLUSTER_ENDPOINT=your-cluster.dsql.us-east-1.on.aws
+export CLUSTER_USER=admin
+export REGION=us-east-1
+cd example
+
+# Run the preferred example
+ruby src/example_preferred.rb
+
+# Run the manual token example
+ruby src/alternatives/manual_token/example.rb
+```
+
+## Development
+
+```bash
+cd ruby/pg
+bundle install
+bundle exec rake unit        # Run unit tests
+bundle exec rake integration # Run integration tests (requires CLUSTER_ENDPOINT)
+```
+
+## DSQL Best Practices
+
+When using this connector with Aurora DSQL, follow these practices:
+
+1. **UUID Primary Keys**: Always use `UUID DEFAULT gen_random_uuid()` - DSQL doesn't support sequences or SERIAL
+2. **OCC Handling**: DSQL uses optimistic concurrency control. Enable retry via `occ_max_retries` on the pool; for single connections, use `OCCRetry` explicitly
+3. **No Foreign Keys**: DSQL doesn't support foreign key constraints - enforce relationships in your application
+4. **Async Indexes**: Use `CREATE INDEX ASYNC` for index creation
+5. **Transaction Limits**: Transactions are limited to 3,000 rows, 10 MiB, and 5 minutes
+6. **Connection Limits**: Connections timeout after 60 minutes; configure pool `max_lifetime` accordingly
+7. **No SAVEPOINT**: Partial rollbacks via SAVEPOINT are not supported
+
+## Additional Resources
+
+- [Amazon Aurora DSQL Documentation](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/what-is-aurora-dsql.html)
+- [pg gem Documentation](https://deveiate.org/code/pg/)
+- [connection_pool Documentation](https://github.com/mperham/connection_pool)
+- [AWS SDK for Ruby](https://docs.aws.amazon.com/sdk-for-ruby/v3/api/)
+
+---
+
+Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+
+SPDX-License-Identifier: Apache-2.0

data/lib/aurora_dsql/pg/config.rb

@@ -0,0 +1,175 @@
+# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+require "uri"
+
+module AuroraDsql
+  module Pg
+    # Configuration for Aurora DSQL connections.
+    class Config
+      DEFAULTS = {
+        user: "admin",
+        database: "postgres",
+        port: 5432,
+        max_lifetime: 55 * 60,      # 55 minutes in seconds
+        token_duration: 15 * 60,    # 15 minutes in seconds
+        pool_size: 5,
+        checkout_timeout: 5         # seconds to wait for a pool connection
+      }.freeze
+
+      attr_accessor :host, :region, :user, :database, :port,
+                    :profile, :token_duration, :credentials_provider,
+                    :max_lifetime, :pool_size, :checkout_timeout,
+                    :application_name, :logger, :occ_max_retries
+
+      def initialize(**options)
+        @host = options[:host]
+        @region = options[:region]
+        @user = options[:user]
+        @database = options[:database]
+        @port = options[:port]
+        @profile = options[:profile]
+        @token_duration = options[:token_duration]
+        @credentials_provider = options[:credentials_provider]
+        @max_lifetime = options[:max_lifetime]
+        @pool_size = options[:pool_size]
+        @checkout_timeout = options[:checkout_timeout]
+        @application_name = options[:application_name]
+        @logger = options[:logger]
+        @occ_max_retries = options[:occ_max_retries]
+      end
+
+      # Parse a connection string into a Config.
+      VALID_SCHEMES = %w[postgres postgresql].freeze
+
+      def self.parse(conn_string)
+        uri = URI.parse(conn_string)
+
+        unless VALID_SCHEMES.include?(uri.scheme)
+          raise Error, "unsupported URI scheme '#{uri.scheme}', expected 'postgres' or 'postgresql'"
+        end
+
+        config = new(
+          host: uri.host,
+          user: uri.user,
+          database: uri.path&.delete_prefix("/"),
+          port: uri.port
+        )
+
+        # Parse query params for DSQL-specific options
+        if uri.query
+          params = URI.decode_www_form(uri.query).to_h
+          config.region = params["region"] if params["region"]
+          config.profile = params["profile"] if params["profile"]
+          config.token_duration = params["tokenDurationSecs"].to_i if params["tokenDurationSecs"]
+        end
+
+        config
+      end
+
+      # Build a Config from various input types.
+      # Accepts a connection String, a Config instance, nil (keyword args only),
+      # or any object that responds to #to_h (e.g. a Hash).
+      def self.from(config = nil, **options)
+        case config
+        when String then parse(config)
+        when Config then config
+        when nil then new(**options)
+        else
+          unless config.respond_to?(:to_h)
+            raise ArgumentError,
+                  "config must be a String, Config, Hash, or respond to #to_h, got #{config.class}"
+          end
+          new(**options.merge(config.to_h))
+        end
+      end
+
+      # Resolve and validate config, returning an immutable ResolvedConfig.
+      def resolve
+        validate!
+
+        resolved_host, resolved_region = resolve_host_and_region(@host, @region)
+
+        ResolvedConfig.new(
+          host: resolved_host,
+          region: resolved_region,
+          user: @user || DEFAULTS[:user],
+          database: @database || DEFAULTS[:database],
+          port: @port || DEFAULTS[:port],
+          profile: @profile,
+          token_duration: @token_duration || DEFAULTS[:token_duration],
+          credentials_provider: @credentials_provider,
+          max_lifetime: @max_lifetime || DEFAULTS[:max_lifetime],
+          pool_size: @pool_size || DEFAULTS[:pool_size],
+          checkout_timeout: @checkout_timeout || DEFAULTS[:checkout_timeout],
+          application_name: @application_name,
+          logger: @logger,
+          occ_max_retries: @occ_max_retries
+        ).freeze
+      end
+
+      private
+
+      def resolve_host_and_region(host, region)
+        if Util.cluster_id?(host)
+          region ||= Util.region_from_env
+          raise Error, "region is required when host is a cluster ID" unless region
+
+          [Util.build_hostname(host, region), region]
+        else
+          region ||= begin
+            Util.parse_region(host)
+          rescue ArgumentError
+            nil
+          end
+          region ||= Util.region_from_env
+          raise Error, "region is required: could not parse from hostname and not set" unless region
+
+          [host, region]
+        end
+      end
+
+      def validate!
+        raise Error, "host is required" if @host.nil? || @host.empty?
+
+        if @port
+          raise Error, "port must be an integer, got #{@port.class}" unless @port.is_a?(Integer)
+          raise Error, "port must be between 1 and 65535, got #{@port}" if @port < 1 || @port > 65_535
+        end
+
+        if @occ_max_retries
+          unless @occ_max_retries.is_a?(Integer) && @occ_max_retries > 0
+            raise Error, "occ_max_retries must be a positive integer, got #{@occ_max_retries.inspect}"
+          end
+        end
+      end
+    end
+
+    # Immutable resolved configuration ready for connection.
+    ResolvedConfig = Struct.new(
+      :host, :region, :user, :database, :port,
+      :profile, :token_duration, :credentials_provider,
+      :max_lifetime, :pool_size, :checkout_timeout,
+      :application_name, :logger, :occ_max_retries,
+      keyword_init: true
+    ) do
+      # Convert to pg connection parameters hash.
+      def to_pg_params(password:)
+        params = {
+          host: host,
+          port: port,
+          user: user,
+          dbname: database,
+          password: password,
+          sslmode: "verify-full",
+          application_name: AuroraDsql::Pg.build_application_name(application_name)
+        }
+
+        # Direct SSL negotiation (libpq 17+)
+        params[:sslnegotiation] = "direct" if PG.library_version >= 170_000
+
+        params
+      end
+    end
+  end
+end

data/lib/aurora_dsql/pg/connection.rb

@@ -0,0 +1,72 @@
+# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+require "pg"
+
+module AuroraDsql
+  module Pg
+    # Single connection wrapper for Aurora DSQL.
+    class Connection
+      attr_reader :pg_conn, :config
+
+      # Create a new connection to Aurora DSQL.
+      def self.connect(config = nil, **options)
+        resolved = Config.from(config, **options).resolve
+
+        token = Token.generate(
+          host: resolved.host,
+          region: resolved.region,
+          user: resolved.user,
+          credentials: resolved.credentials_provider,
+          profile: resolved.profile,
+          expires_in: resolved.token_duration
+        )
+
+        pg_conn = ::PG.connect(resolved.to_pg_params(password: token))
+        new(pg_conn, resolved)
+      end
+
+      def initialize(pg_conn, config)
+        @pg_conn = pg_conn
+        @config = config
+      end
+
+      # Delegate common pg methods
+
+      def exec_params(...)
+        @pg_conn.exec_params(...)
+      end
+
+      def query(...)
+        @pg_conn.query(...)
+      end
+
+      def transaction(...)
+        @pg_conn.transaction(...)
+      end
+
+      def close
+        @pg_conn.close
+      end
+
+      def finished?
+        @pg_conn.finished?
+      end
+
+      private
+
+      # Delegate remaining methods to PG::Connection.
+      def method_missing(method, ...)
+        if @pg_conn.respond_to?(method)
+          @pg_conn.send(method, ...)
+        else
+          super
+        end
+      end
+
+      def respond_to_missing?(method, include_private = false)
+        @pg_conn.respond_to?(method, include_private) || super
+      end
+    end
+  end
+end

data/lib/aurora_dsql/pg/occ_retry.rb

@@ -0,0 +1,97 @@
+# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+require "pg"
+
+module AuroraDsql
+  module Pg
+    # OCC (Optimistic Concurrency Control) retry utilities for Aurora DSQL.
+    module OCCRetry
+      # OCC error code for mutation conflicts.
+      ERROR_CODE_MUTATION = "OC000"
+
+      # OCC error code for schema conflicts.
+      ERROR_CODE_SCHEMA = "OC001"
+
+      # SQLSTATE for serialization failure.
+      SQLSTATE_SERIALIZATION_FAILURE = "40001"
+
+      # Default retry configuration.
+      DEFAULT_CONFIG = {
+        max_retries: 3,
+        initial_wait: 0.1,    # 100ms
+        max_wait: 5.0,        # 5 seconds
+        multiplier: 2.0
+      }.freeze
+
+      # Check if an error is an OCC conflict.
+      # Checks SQLSTATE first, then falls back to message matching.
+      def self.occ_error?(error)
+        return false if error.nil?
+
+        # Prefer structured SQLSTATE check when available
+        if error.respond_to?(:result) && error.result&.respond_to?(:error_field)
+          sqlstate = error.result.error_field(PG::Result::PG_DIAG_SQLSTATE)
+          return true if sqlstate == SQLSTATE_SERIALIZATION_FAILURE
+        end
+
+        # Fall back to message matching for OCC-specific codes
+        msg = error.message.to_s
+        msg.include?(ERROR_CODE_MUTATION) || msg.include?(ERROR_CODE_SCHEMA)
+      end
+
+      # Retry a block on OCC conflicts with exponential backoff and jitter.
+      # Used by both Pool#with and OCCRetry.with_retry.
+      def self.retry_on_occ(config = DEFAULT_CONFIG, logger: nil)
+        wait = config[:initial_wait]
+        last_error = nil
+
+        (0..config[:max_retries]).each do |attempt|
+          begin
+            return yield
+          rescue StandardError => e
+            raise unless occ_error?(e)
+
+            last_error = e
+
+            if attempt < config[:max_retries]
+              jittered_wait = wait + rand * wait / 4
+              logger&.warn(
+                "[AuroraDsql::Pg] OCC conflict detected, retrying " \
+                "(attempt #{attempt + 1}/#{config[:max_retries]}, wait #{jittered_wait.round(2)}s)"
+              )
+              sleep(jittered_wait)
+              wait = [wait * config[:multiplier], config[:max_wait]].min
+            end
+          end
+        end
+
+        # Re-raise inside rescue so Ruby sets .cause to the original OCC error.
+        begin
+          raise last_error
+        rescue StandardError
+          raise AuroraDsql::Pg::Error,
+                "Max retries (#{config[:max_retries]}) exceeded, last error: #{last_error&.message}"
+        end
+      end
+
+      # Execute a transactional block with automatic retry on OCC conflicts.
+      def self.with_retry(pool, config = {}, &block)
+        retry_on_occ(DEFAULT_CONFIG.merge(config)) do
+          pool.with(retry_occ: false) do |conn|
+            conn.transaction { block.call(conn) }
+          end
+        end
+      end
+
+      # Execute a single SQL statement with automatic retry on OCC conflicts.
+      # Unlike with_retry, this does NOT wrap in an explicit transaction,
+      # making it suitable for both DDL (CREATE TABLE, etc.) and single DML statements.
+      def self.exec_with_retry(pool, sql, max_retries: 3)
+        retry_on_occ(DEFAULT_CONFIG.merge(max_retries: max_retries)) do
+          pool.with(retry_occ: false) { |conn| conn.exec(sql) }
+        end
+      end
+    end
+  end
+end

data/lib/aurora_dsql/pg/pool.rb

@@ -0,0 +1,100 @@
+# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+require "pg"
+require "connection_pool"
+
+module AuroraDsql
+  module Pg
+    # Connection pool for Aurora DSQL with max_lifetime enforcement.
+    class Pool
+      # Wrapper to track connection creation time for max_lifetime enforcement.
+      PooledConnection = Struct.new(:conn, :created_at, keyword_init: true)
+
+      # Create a new connection pool.
+      def self.create(config = nil, **options)
+        new(Config.from(config, **options).resolve)
+      end
+
+      def initialize(resolved_config)
+        @config = resolved_config
+
+        @pool = ConnectionPool.new(
+          size: resolved_config.pool_size,
+          timeout: resolved_config.checkout_timeout
+        ) { create_connection }
+      end
+
+      # Maximum stale connection discards before giving up.
+      MAX_STALE_RETRIES = 10
+
+      # Check out a connection and yield it to the block.
+      # Enforces max_lifetime. Retries on OCC errors only when occ_max_retries
+      # is set in the pool config. Pass retry_occ: false to skip retry on
+      # individual calls.
+      def with(retry_occ: @config.occ_max_retries, &block)
+        return checkout_and_execute(&block) unless retry_occ
+
+        unless retry_occ.is_a?(Integer) && retry_occ > 0
+          raise ArgumentError,
+                "retry_occ must be false/nil or a positive integer, got #{retry_occ.inspect}. " \
+                "Configure occ_max_retries on the pool instead of passing retry_occ: true"
+        end
+
+        occ_config = OCCRetry::DEFAULT_CONFIG.merge(max_retries: retry_occ)
+        OCCRetry.retry_on_occ(occ_config, logger: @config.logger) { checkout_and_execute(&block) }
+      end
+
+      # Shutdown the pool, closing all connections.
+      def shutdown
+        @pool.shutdown { |wrapped| wrapped.conn.close rescue nil }
+      end
+
+      private
+
+      # Check out a connection, handling stale connection replacement.
+      # Loops because each @pool.with checkout may return a stale connection
+      # that must be discarded before retrying with a fresh one.
+      def checkout_and_execute(&block)
+        stale_retries = 0
+
+        loop do
+          @pool.with do |wrapped|
+            if stale?(wrapped)
+              stale_retries += 1
+              if stale_retries > MAX_STALE_RETRIES
+                raise AuroraDsql::Pg::Error,
+                      "unable to acquire a non-stale connection after #{MAX_STALE_RETRIES} attempts"
+              end
+              @config.logger&.warn(
+                "[AuroraDsql::Pg] Discarding stale connection " \
+                "(age #{(Time.now - wrapped.created_at).round}s, max_lifetime #{@config.max_lifetime}s)"
+              )
+              @pool.discard_current_connection
+              wrapped.conn.close rescue nil
+            else
+              return block.call(wrapped.conn)
+            end
+          end
+        end
+      end
+
+      def stale?(wrapped)
+        Time.now - wrapped.created_at > @config.max_lifetime
+      end
+
+      def create_connection
+        token = Token.generate(
+          host: @config.host,
+          region: @config.region,
+          user: @config.user,
+          credentials: @config.credentials_provider,
+          profile: @config.profile,
+          expires_in: @config.token_duration
+        )
+        conn = ::PG.connect(@config.to_pg_params(password: token))
+        PooledConnection.new(conn: conn, created_at: Time.now)
+      end
+    end
+  end
+end

data/lib/aurora_dsql/pg/token.rb

@@ -0,0 +1,39 @@
+# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+require "aws-sdk-dsql"
+
+module AuroraDsql
+  module Pg
+    # IAM token generation for Aurora DSQL.
+    class Token
+      ADMIN_USER = "admin"
+      # Generate an IAM authentication token.
+      def self.generate(host:, region:, user:, credentials: nil, profile: nil, expires_in: 15 * 60)
+        credentials ||= resolve_credentials(profile)
+
+        token_generator = Aws::DSQL::AuthTokenGenerator.new(credentials: credentials)
+        params = { endpoint: host, region: region, expires_in: expires_in }
+
+        begin
+          if user == ADMIN_USER
+            token_generator.generate_db_connect_admin_auth_token(**params)
+          else
+            token_generator.generate_db_connect_auth_token(**params)
+          end
+        rescue Aws::Errors::ServiceError => e
+          raise AuroraDsql::Pg::Error, "Failed to generate authentication token: #{e.message}"
+        end
+      end
+
+      # Resolve AWS credentials from profile or default chain.
+      def self.resolve_credentials(profile = nil)
+        if profile && !profile.empty?
+          Aws::SharedCredentials.new(profile_name: profile)
+        else
+          Aws::CredentialProviderChain.new.resolve
+        end
+      end
+    end
+  end
+end

data/lib/aurora_dsql/pg/util.rb

@@ -0,0 +1,41 @@
+# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+module AuroraDsql
+  module Pg
+    # Utility functions for host/region parsing.
+    module Util
+      # Pattern to extract region from DSQL hostname.
+      # Matches: cluster.dsql.us-east-1.on.aws or cluster.dsql-suffix.us-east-1.on.aws
+      REGION_PATTERN = /\.dsql[^.]*\.([^.]+)\.on\.aws\z/
+
+      # Pattern for valid DSQL cluster IDs: 26 lowercase alphanumeric characters.
+      CLUSTER_ID_PATTERN = /\A[a-z0-9]{26}\z/
+
+      # Extract AWS region from a DSQL hostname.
+      def self.parse_region(host)
+        match = host&.match(REGION_PATTERN)
+        raise ArgumentError, "Cannot parse region from hostname: #{host.inspect}" unless match
+
+        match[1]
+      end
+
+      # Check if the given string is a cluster ID (not a full hostname).
+      def self.cluster_id?(host)
+        return false if host.nil? || host.empty? || host.include?(".")
+
+        CLUSTER_ID_PATTERN.match?(host)
+      end
+
+      # Build a full DSQL hostname from cluster ID and region.
+      def self.build_hostname(cluster_id, region)
+        "#{cluster_id}.dsql.#{region}.on.aws"
+      end
+
+      # Get AWS region from environment variables.
+      def self.region_from_env
+        ENV["AWS_REGION"] || ENV["AWS_DEFAULT_REGION"]
+      end
+    end
+  end
+end

data/lib/aurora_dsql/pg/version.rb

@@ -0,0 +1,17 @@
+# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+module AuroraDsql
+  module Pg
+    VERSION = "1.0.0"
+    APPLICATION_NAME = "aurora-dsql-ruby-pg/#{VERSION}"
+
+    # Build application_name with optional ORM prefix.
+    def self.build_application_name(orm_prefix = nil)
+      prefix = orm_prefix.to_s.strip
+      return APPLICATION_NAME if prefix.empty?
+
+      "#{prefix}:#{APPLICATION_NAME}"
+    end
+  end
+end

data/lib/aurora_dsql_pg.rb

@@ -0,0 +1,26 @@
+# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+require_relative "aurora_dsql/pg/version"
+require_relative "aurora_dsql/pg/util"
+require_relative "aurora_dsql/pg/config"
+require_relative "aurora_dsql/pg/token"
+require_relative "aurora_dsql/pg/connection"
+require_relative "aurora_dsql/pg/pool"
+require_relative "aurora_dsql/pg/occ_retry"
+
+module AuroraDsql
+  module Pg
+    class Error < StandardError; end
+
+    # Create a single connection to Aurora DSQL.
+    def self.connect(config = nil, **options)
+      Connection.connect(config, **options)
+    end
+
+    # Create a connection pool for Aurora DSQL.
+    def self.create_pool(config = nil, **options)
+      Pool.create(config, **options)
+    end
+  end
+end

metadata

@@ -0,0 +1,133 @@
+--- !ruby/object:Gem::Specification
+name: aurora-dsql-ruby-pg
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Amazon Web Services
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-03-09 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: pg
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+- !ruby/object:Gem::Dependency
+  name: aws-sdk-dsql
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+- !ruby/object:Gem::Dependency
+  name: connection_pool
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.4'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.4'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: A connector that integrates IAM authentication for connecting Ruby applications
+  to Amazon Aurora DSQL clusters using the pg gem
+email:
+- aws-aurora-dsql-feedback@amazon.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- NOTICE
+- README.md
+- lib/aurora_dsql/pg/config.rb
+- lib/aurora_dsql/pg/connection.rb
+- lib/aurora_dsql/pg/occ_retry.rb
+- lib/aurora_dsql/pg/pool.rb
+- lib/aurora_dsql/pg/token.rb
+- lib/aurora_dsql/pg/util.rb
+- lib/aurora_dsql/pg/version.rb
+- lib/aurora_dsql_pg.rb
+homepage: https://github.com/awslabs/aurora-dsql-connectors
+licenses:
+- Apache-2.0
+metadata:
+  homepage_uri: https://github.com/awslabs/aurora-dsql-connectors
+  source_code_uri: https://github.com/awslabs/aurora-dsql-connectors/tree/main/ruby/pg
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Aurora DSQL connector for Ruby pg gem
+test_files: []