aws_advanced_ruby_driver_wrapper 1.0.1 → 1.1.0

data/lib/aws_advanced_ruby_driver_wrapper/utils/telemetry/telemetry_const.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+#  Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+#  Licensed under the Apache License, Version 2.0 (the "License").
+#  You may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#  http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+
+module AwsAdvancedRubyDriverWrapper
+  module Utils
+    module Telemetry
+      # The levels a telemetry context can be opened at. Callers name a level with one of these
+      # constants, so that a mistyped level raises NameError where it is written.
+      module TraceLevel
+        # Always starts a new trace, whatever the settings say.
+        FORCE_TOP_LEVEL = :force_top_level
+        # Starts a new trace when +telemetry_submit_top_level+ is enabled, and is otherwise treated
+        # as {NESTED}.
+        TOP_LEVEL = :top_level
+        # Becomes a child of the current span. Outside of any trace nothing is recorded, so the
+        # wrapper does not start traces of its own unless asked to.
+        NESTED = :nested
+        # Records nothing.
+        NO_TRACE = :no_trace
+      end
+
+      # Instrumentation scope name the wrapper's tracer and meter are registered under.
+      INSTRUMENTATION_NAME = 'aws-advanced-ruby-driver-wrapper'
+
+      # Span attribute names, and the prefix of the name of a copied span.
+      module TelemetryConst
+        TRACE_NAME_ANNOTATION = 'trace_name'
+        RUBY_CALL_ANNOTATION = 'ruby_call'
+        PARENT_TRACE_ANNOTATION = 'parent_trace_id'
+        EXCEPTION_TYPE_ANNOTATION = 'exception_type'
+        EXCEPTION_MESSAGE_ANNOTATION = 'exception_message'
+        SOURCE_TRACE_ANNOTATION = 'source_trace_id'
+        COPY_TRACE_NAME_PREFIX = 'copy: '
+      end
+    end
+  end
+end

data/lib/aws_advanced_ruby_driver_wrapper/utils/telemetry/telemetry_factory.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+#  Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+#  Licensed under the Apache License, Version 2.0 (the "License").
+#  You may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#  http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+
+require_relative '../../errors'
+require_relative '../../property_definition'
+require_relative 'telemetry_const'
+require_relative 'null_telemetry'
+require_relative 'open_telemetry_factory'
+
+module AwsAdvancedRubyDriverWrapper
+  module Utils
+    module Telemetry
+      # Records the wrapper's traces and metrics through the backends selected by the connection
+      # properties. Traces and metrics are configured separately; whichever is disabled is not recorded.
+      class TelemetryFactory
+        TRACES_BACKENDS = { 'otlp' => OpenTelemetryFactory, 'none' => nil }.freeze
+        METRICS_BACKENDS = { 'otlp' => OpenTelemetryFactory, 'none' => nil }.freeze
+
+        # @param wrapper_props [Hash, Concurrent::Map] the wrapper properties of the connection
+        # @raise [Errors::AwsError] if telemetry is enabled and a backend is missing or not recognized
+        # @raise [LoadError] if a selected backend's gem is not installed
+        def initialize(wrapper_props)
+          @submit_top_level = PropertyDefinition::TELEMETRY_SUBMIT_TOP_LEVEL.get_bool(wrapper_props)
+
+          if PropertyDefinition::ENABLE_TELEMETRY.get_bool(wrapper_props)
+            @traces_factory = backend(PropertyDefinition::TELEMETRY_TRACES_BACKEND, TRACES_BACKENDS, wrapper_props)
+            @metrics_factory = backend(PropertyDefinition::TELEMETRY_METRICS_BACKEND, METRICS_BACKENDS, wrapper_props)
+          end
+
+          @traces_factory&.require_traces_api!
+          @metrics_factory&.require_metrics_api!
+        end
+
+        # Opens a context that the caller must close. Prefer {#in_context}, which closes it.
+        #
+        # @param name [String] the span name
+        # @param trace_level [Symbol] one of the {TraceLevel} constants
+        # @return [OpenTelemetryContext, NullTelemetryContext]
+        def open_telemetry_context(name, trace_level)
+          return NullTelemetryContext::INSTANCE if @traces_factory.nil?
+
+          trace_level = TraceLevel::NESTED if trace_level == TraceLevel::TOP_LEVEL && !@submit_top_level
+          @traces_factory.open_telemetry_context(name, trace_level)
+        end
+
+        # Runs the block inside a new context and closes the context when the block finishes.
+        #
+        # @param record_result [Boolean] whether to mark the span as succeeded or failed according to
+        #   how the block finishes. An error raised by the block marks it failed and is recorded on the
+        #   span. Leaving the block early with +break+, +next+, +return+ or +throw+ is not an error, so
+        #   it marks the span as succeeded.
+        # @param record_failure [Boolean] whether to mark the span as failed, recording the error, when
+        #   the block raises, while leaving its status unset when it does not. Implied by +record_result+.
+        # @yieldparam context [OpenTelemetryContext, NullTelemetryContext]
+        # @return the block's result
+        def in_context(name, trace_level, record_result: false, record_failure: false)
+          return yield NullTelemetryContext::INSTANCE if @traces_factory.nil?
+
+          context = open_telemetry_context(name, trace_level)
+          failed = false
+          begin
+            yield context
+          rescue Exception => e # rubocop:disable Lint/RescueException -- recorded, then re-raised
+            failed = true
+            if record_result || record_failure
+              context.record_exception(e)
+              context.success = false
+            end
+            raise
+          ensure
+            context.success = true if record_result && !failed
+            context.close
+          end
+        end
+
+        # Records a copy of a closed context's span at another trace level, typically {TraceLevel::FORCE_TOP_LEVEL},
+        # so that work recorded inside a trace, such as a failover, can also be found as a trace of
+        # its own. The copy has the same timings, attributes and status, is named with a +copy: +
+        # prefix, and is linked to the original.
+        #
+        # @param context [OpenTelemetryContext, NullTelemetryContext] a context that has been closed
+        def post_copy(context, trace_level)
+          @traces_factory&.post_copy(context, trace_level)
+        end
+
+        # @return [OpenTelemetryCounter, NullTelemetryCounter]
+        def create_counter(name)
+          return NullTelemetryCounter::INSTANCE if @metrics_factory.nil?
+
+          @metrics_factory.create_counter(name)
+        end
+
+        # A gauge reports one value for the whole process: creating a gauge with a name that already
+        # exists, from this connection or any other, replaces the callback it is read from. So the
+        # callback should report state shared by all connections (such as the size of a shared
+        # cache) rather than state of its own connection.
+        #
+        # @yieldreturn [Numeric] the gauge's current value, read each time metrics are collected
+        # @return [OpenTelemetryGauge, NullTelemetryGauge]
+        def create_gauge(name, &callback)
+          return NullTelemetryGauge::INSTANCE if @metrics_factory.nil?
+
+          @metrics_factory.create_gauge(name, callback)
+        end
+
+        # @return [Boolean] whether traces or metrics are being recorded
+        def in_use?
+          traces_in_use? || !@metrics_factory.nil?
+        end
+
+        # @return [Boolean] whether traces are being recorded
+        def traces_in_use?
+          !@traces_factory.nil?
+        end
+
+        private
+
+        def backend(property, backends, wrapper_props)
+          value = property.get_string(wrapper_props)
+          key = value&.downcase
+          return backends[key] if backends.key?(key)
+
+          raise Errors::AwsError,
+                "#{value.inspect} is not a valid #{property.name}. " \
+                "When enable_telemetry is true, #{property.name} must be one of: #{backends.keys.join(', ')}"
+        end
+      end
+    end
+  end
+end

data/lib/aws_advanced_ruby_driver_wrapper/utils/topology_utils.rb

@@ -73,8 +73,8 @@ module AwsAdvancedRubyDriverWrapper
       def query_topology(conn, initial_host_info, instance_template)
         results = @dialect.execute(conn, @dialect.topology_query)
         # We expect at least 4 columns. Note that the server may return 0 columns if failover has occurred.
-        if results.fields.empty?
-          logger.debug('The topology query returned a result with 0 columns. ' \
+        if topology_result_empty?(results)
+          logger.debug('The topology query returned a result with no rows or rows with no columns. ' \
                        'This may occur if the topology query is executed when the server is failing over.')
           return nil
         end
@@ -84,6 +84,13 @@ module AwsAdvancedRubyDriverWrapper
 
       private
 
+      # True if the topology query returned no rows, or rows without columns (the server may return
+      # no columns while failing over).
+      def topology_result_empty?(results)
+        first_row = results.first
+        first_row.nil? || first_row.empty?
+      end
+
       # Verifies the writer in the host list. If multiple writers exist, the one with the most recent
       # last_update_time is used as the current writer.
       #

data/lib/aws_advanced_ruby_driver_wrapper/version.rb

@@ -15,5 +15,5 @@
 #  limitations under the License.
 
 module AwsAdvancedRubyDriverWrapper
-  VERSION = '1.0.1'
+  VERSION = '1.1.0'
 end

data/lib/aws_advanced_ruby_driver_wrapper.rb

@@ -33,11 +33,12 @@ module AwsAdvancedRubyDriverWrapper
   @config = Configuration.new
 
   # Direct-driver connection classes are autoloaded so requiring this file alone is enough to use them:
-  # referencing either constant loads its driver-specific file on demand. Loading stays lazy - a client
-  # for one driver never loads the other driver's code, and the underlying 'pg'/'mysql2' gem is only
+  # referencing any of them loads its driver-specific file on demand. Loading stays lazy - a client
+  # for one driver never loads another driver's code, and the underlying 'pg'/'mysql2'/'trilogy' gem is only
   # required when a connection is actually opened.
   autoload :WrapperPgConnection, 'aws_advanced_ruby_driver_wrapper/postgresql'
   autoload :WrapperMysql2Client, 'aws_advanced_ruby_driver_wrapper/mysql'
+  autoload :WrapperTrilogyClient, 'aws_advanced_ruby_driver_wrapper/trilogy'
 
   # Other public entry points are autoloaded for the same reason, so they work from code that runs
   # before any connection is opened, such as a Rails initializer or a setup script.
@@ -148,6 +149,12 @@ if defined?(ActiveSupport) && ActiveSupport.respond_to?(:on_load)
       'ActiveRecord::ConnectionAdapters::AwsMysql2Adapter',
       'aws_advanced_ruby_driver_wrapper/active_record/aws_mysql2_adapter'
     )
+
+    ActiveRecord::ConnectionAdapters.register(
+      'aws_trilogy',
+      'ActiveRecord::ConnectionAdapters::AwsTrilogyAdapter',
+      'aws_advanced_ruby_driver_wrapper/active_record/aws_trilogy_adapter'
+    )
   end
 end
 

metadata

@@ -1,15 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: aws_advanced_ruby_driver_wrapper
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.1.0
 platform: ruby
 authors:
 - Amazon Web Services
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-10-07 00:00:00.000000000 Z
+date: 2026-11-05 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: bigdecimal
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
   requirement: !ruby/object:Gem::Requirement
@@ -30,6 +44,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 1.3.7
+- !ruby/object:Gem::Dependency
+  name: logger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: A Ruby DB driver wrapper that provides enhanced features for AWS RDS
   MySQL/PostgreSQL databases
 email:
@@ -48,6 +76,7 @@ files:
 - lib/aws_advanced_ruby_driver_wrapper/active_record/aws_connection_handler.rb
 - lib/aws_advanced_ruby_driver_wrapper/active_record/aws_mysql2_adapter.rb
 - lib/aws_advanced_ruby_driver_wrapper/active_record/aws_postgresql_adapter.rb
+- lib/aws_advanced_ruby_driver_wrapper/active_record/aws_trilogy_adapter.rb
 - lib/aws_advanced_ruby_driver_wrapper/active_record/type_adapter_alias.rb
 - lib/aws_advanced_ruby_driver_wrapper/custom_configuration.rb
 - lib/aws_advanced_ruby_driver_wrapper/db_dialects/aurora_mysql_dialect.rb
@@ -65,12 +94,15 @@ files:
 - lib/aws_advanced_ruby_driver_wrapper/db_dialects/utils/dialect_utils.rb
 - lib/aws_advanced_ruby_driver_wrapper/driver_dialects/driver_dialect.rb
 - lib/aws_advanced_ruby_driver_wrapper/driver_dialects/driver_dialect_manager.rb
+- lib/aws_advanced_ruby_driver_wrapper/driver_dialects/mysql2_driver_dialect.rb
 - lib/aws_advanced_ruby_driver_wrapper/driver_dialects/mysql_driver_dialect.rb
 - lib/aws_advanced_ruby_driver_wrapper/driver_dialects/pg_driver_dialect.rb
+- lib/aws_advanced_ruby_driver_wrapper/driver_dialects/trilogy_driver_dialect.rb
 - lib/aws_advanced_ruby_driver_wrapper/errors.rb
 - lib/aws_advanced_ruby_driver_wrapper/errors/error_handler.rb
 - lib/aws_advanced_ruby_driver_wrapper/errors/mysql_error_handler.rb
 - lib/aws_advanced_ruby_driver_wrapper/errors/pg_error_handler.rb
+- lib/aws_advanced_ruby_driver_wrapper/errors/trilogy_error_handler.rb
 - lib/aws_advanced_ruby_driver_wrapper/host/connection_string_host_list_provider.rb
 - lib/aws_advanced_ruby_driver_wrapper/host/global_aurora_host_list_provider.rb
 - lib/aws_advanced_ruby_driver_wrapper/host/host_availability.rb
@@ -87,6 +119,7 @@ files:
 - lib/aws_advanced_ruby_driver_wrapper/monitoring/monitor_state.rb
 - lib/aws_advanced_ruby_driver_wrapper/mysql.rb
 - lib/aws_advanced_ruby_driver_wrapper/plugins/blue_green/blue_green_plugin.rb
+- lib/aws_advanced_ruby_driver_wrapper/plugins/blue_green/drop_blue_connections_marker.rb
 - lib/aws_advanced_ruby_driver_wrapper/plugins/blue_green/host_mapper.rb
 - lib/aws_advanced_ruby_driver_wrapper/plugins/blue_green/iam_host_tracker.rb
 - lib/aws_advanced_ruby_driver_wrapper/plugins/blue_green/interim_status.rb
@@ -116,6 +149,9 @@ files:
 - lib/aws_advanced_ruby_driver_wrapper/plugins/default_plugin.rb
 - lib/aws_advanced_ruby_driver_wrapper/plugins/failover_mode.rb
 - lib/aws_advanced_ruby_driver_wrapper/plugins/failover_plugin.rb
+- lib/aws_advanced_ruby_driver_wrapper/plugins/federated_auth/base_saml_auth_plugin.rb
+- lib/aws_advanced_ruby_driver_wrapper/plugins/federated_auth/federated_auth_plugin.rb
+- lib/aws_advanced_ruby_driver_wrapper/plugins/federated_auth/okta_auth_plugin.rb
 - lib/aws_advanced_ruby_driver_wrapper/plugins/gdb/gdb_failover_mode.rb
 - lib/aws_advanced_ruby_driver_wrapper/plugins/gdb/gdb_failover_plugin.rb
 - lib/aws_advanced_ruby_driver_wrapper/plugins/iam_auth_plugin.rb
@@ -139,6 +175,8 @@ files:
 - lib/aws_advanced_ruby_driver_wrapper/plugins/kms_encryption/sanitizer.rb
 - lib/aws_advanced_ruby_driver_wrapper/plugins/kms_encryption/schema_name.rb
 - lib/aws_advanced_ruby_driver_wrapper/plugins/kms_encryption/schema_validator.rb
+- lib/aws_advanced_ruby_driver_wrapper/plugins/kms_encryption/sql/trigger_mysql.sql
+- lib/aws_advanced_ruby_driver_wrapper/plugins/kms_encryption/sql/trigger_pg.sql
 - lib/aws_advanced_ruby_driver_wrapper/plugins/kms_encryption/sql_runner.rb
 - lib/aws_advanced_ruby_driver_wrapper/plugins/kms_encryption/type_marker.rb
 - lib/aws_advanced_ruby_driver_wrapper/plugins/secrets_manager_plugin.rb
@@ -154,6 +192,7 @@ files:
 - lib/aws_advanced_ruby_driver_wrapper/services/service_container.rb
 - lib/aws_advanced_ruby_driver_wrapper/services/service_utility.rb
 - lib/aws_advanced_ruby_driver_wrapper/services/session_state_service.rb
+- lib/aws_advanced_ruby_driver_wrapper/trilogy.rb
 - lib/aws_advanced_ruby_driver_wrapper/utils/accessible_regions.rb
 - lib/aws_advanced_ruby_driver_wrapper/utils/aurora_topology_utils.rb
 - lib/aws_advanced_ruby_driver_wrapper/utils/aws_credentials_utils.rb
@@ -169,6 +208,7 @@ files:
 - lib/aws_advanced_ruby_driver_wrapper/utils/multi_az_topology_utils.rb
 - lib/aws_advanced_ruby_driver_wrapper/utils/parser/encryption_annotation_parser.rb
 - lib/aws_advanced_ruby_driver_wrapper/utils/parser/mysql_statement_analyzer.rb
+- lib/aws_advanced_ruby_driver_wrapper/utils/parser/mysql_text.rb
 - lib/aws_advanced_ruby_driver_wrapper/utils/parser/pg_statement_analyzer.rb
 - lib/aws_advanced_ruby_driver_wrapper/utils/parser/query_analysis.rb
 - lib/aws_advanced_ruby_driver_wrapper/utils/parser/query_type.rb
@@ -178,12 +218,20 @@ files:
 - lib/aws_advanced_ruby_driver_wrapper/utils/rds_url_type.rb
 - lib/aws_advanced_ruby_driver_wrapper/utils/rds_utils.rb
 - lib/aws_advanced_ruby_driver_wrapper/utils/retry_util.rb
+- lib/aws_advanced_ruby_driver_wrapper/utils/saml_utils.rb
 - lib/aws_advanced_ruby_driver_wrapper/utils/sql_encoding.rb
 - lib/aws_advanced_ruby_driver_wrapper/utils/sql_method_analyzer.rb
 - lib/aws_advanced_ruby_driver_wrapper/utils/storage/cache_entry.rb
 - lib/aws_advanced_ruby_driver_wrapper/utils/storage/expiration_cache.rb
 - lib/aws_advanced_ruby_driver_wrapper/utils/storage/sliding_expiration_cache.rb
 - lib/aws_advanced_ruby_driver_wrapper/utils/storage/storage_service.rb
+- lib/aws_advanced_ruby_driver_wrapper/utils/telemetry/null_telemetry.rb
+- lib/aws_advanced_ruby_driver_wrapper/utils/telemetry/open_telemetry_context.rb
+- lib/aws_advanced_ruby_driver_wrapper/utils/telemetry/open_telemetry_counter.rb
+- lib/aws_advanced_ruby_driver_wrapper/utils/telemetry/open_telemetry_factory.rb
+- lib/aws_advanced_ruby_driver_wrapper/utils/telemetry/open_telemetry_gauge.rb
+- lib/aws_advanced_ruby_driver_wrapper/utils/telemetry/telemetry_const.rb
+- lib/aws_advanced_ruby_driver_wrapper/utils/telemetry/telemetry_factory.rb
 - lib/aws_advanced_ruby_driver_wrapper/utils/topology_utils.rb
 - lib/aws_advanced_ruby_driver_wrapper/version.rb
 - lib/aws_advanced_ruby_driver_wrapper/wrapper_property.rb
@@ -202,6 +250,10 @@ post_install_message: |
     gem install mysql2
     require 'aws_advanced_ruby_driver_wrapper/mysql'
 
+  To use with MySQL through trilogy:
+    gem install trilogy
+    require 'aws_advanced_ruby_driver_wrapper/trilogy'
+
   To use with PostgreSQL:
     gem install pg
     require 'aws_advanced_ruby_driver_wrapper/postgresql'