activerecord-trino-adapter 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b38f0bee0dc9764f269632d9b138de7aff8c4fb3fb696c8862bd8de23a34999e
+  data.tar.gz: 8a24ba5209ee11e82ee43d67182798599b96b1a9f1a621b4f60edf0a2ae3c0ed
+SHA512:
+  metadata.gz: 83cba7a9d4c291d021d94729bd2e1fbb37e101ec19749163b4eebcee99969360cd46e3831e0d952eb63770d6db53e46abce9627fa82208f3103b38361c15148b
+  data.tar.gz: fd39bfe9b1025178a0a95e35b03bbd9617a3859931e7eea02af7a8ce96a8cf02dd7090469fe08ceca19208a1c9f53a20d83345ca78229e2adb426408102fa624

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright Power Home Remodeling Group, LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,151 @@
+# activerecord-trino-adapter
+
+A read-only ActiveRecord SQL adapter for [Trino](https://trino.io/), built on top of the [`trino-client`](https://rubygems.org/gems/trino-client) gem.
+
+Lets a Rails application query a Trino data warehouse using familiar ActiveRecord scopes and `where` chains while preventing accidental writes. Designed for analytical use cases where the warehouse is the source of truth and the application only needs to read from it.
+
+## Features
+
+- **Read-only by design.** All write paths (`insert`, `update`, `delete`, transactions, migrations, schema changes) raise `ActiveRecord::Trino::ReadOnlyError`.
+- **ActiveRecord-native.** Plugs into Rails 7.1+ multi-database via `database.yml` and `connects_to`.
+- **Opinionated safety belts.** `find_each` / `find_in_batches` are banned (they don't fit Trino's pagination model); hard query timeouts default to 150 seconds; slow queries emit `ActiveSupport::Notifications` for any subscriber to pick up.
+- **SQL-injection conscious.** Trino has no parameterized queries, so every literal flows through a tight, fuzz-tested `quote` implementation.
+- **Schema introspection** via Trino's `information_schema.columns`, with a small but practical type map (varchar, integer, decimal, boolean, date, timestamp, timestamp with time zone, json, etc.).
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "activerecord-trino-adapter"
+```
+
+Then in your `config/database.yml`:
+
+```yaml
+warehouse:
+  adapter: trino
+  host: <%= ENV["TRINO_HOST"] %>
+  port: <%= ENV.fetch("TRINO_PORT", 8080) %>
+  ssl: <%= ENV.fetch("TRINO_SSL", "false") %>
+  user: <%= ENV["TRINO_USER"] %>
+  password: <%= ENV["TRINO_PASSWORD"] %>
+  catalog: <%= ENV["TRINO_CATALOG"] %>
+  schema: <%= ENV["TRINO_SCHEMA"] %>
+  query_timeout: 150
+  plan_timeout: 30
+```
+
+And an abstract record that connects to it:
+
+```ruby
+class WarehouseRecord < ActiveRecord::Base
+  self.abstract_class = true
+  connects_to database: { reading: :warehouse }
+end
+
+class SalesByDay < WarehouseRecord
+  self.table_name = "sales_by_day"
+end
+```
+
+Now standard AR queries work against Trino:
+
+```ruby
+SalesByDay.where(month: "2026-04").order(:territory_id).limit(100)
+```
+
+## What is and is not supported
+
+Supported:
+- `where`, `order`, `limit`, `offset`, `select`, `pluck`, `find_by`, `count`, `sum`, `average`
+- Scopes, including chained scopes
+- Type-cast reads for varchar, integer (all widths), real/double, decimal, boolean, date, timestamp, timestamp with time zone, time, json, uuid
+
+Not supported (raises):
+- Any write path: `save`, `update`, `delete`, `destroy`, `insert`, `create_table`, transactions, savepoints
+- `find_each` / `find_in_batches` — Trino's pagination model is incompatible; use explicit `LIMIT`/`OFFSET` or `pluck` aggregates
+- Trino composite types (`array`, `map`, `row`) in result casting — select scalar columns or extract via Trino SQL (`element_at`, dot access)
+
+Out of design scope:
+- `joins` are not a design goal. The adapter passes SQL through to Trino, so a join across two Trino-backed models technically works, but it is not tested and the intended usage pattern is to query flat denormalized warehouse tables.
+- Cross-database joins (e.g., a MySQL model joined to a Trino model) do not work — Rails 7.1+ disallows joins across connection handles.
+
+## Configuration options
+
+All keys are read from the `database.yml` entry:
+
+| Key | Default | Description |
+|---|---|---|
+| `host` | _required_ | Trino server hostname (e.g. `trino.example.com`) — no scheme, no port |
+| `port` | `8080` (HTTP) / `443` (HTTPS) | Trino server port |
+| `ssl` | `false` | Whether to use HTTPS. When `true`, also passing `password` requires the connection to be HTTPS (trino-client policy) |
+| `user` | _required_ | Trino user |
+| `password` | _nil_ | Optional basic-auth password |
+| `catalog` | _required_ | Default Trino catalog |
+| `schema` | _required_ | Default Trino schema |
+| `query_timeout` | `150` | Hard ceiling on query duration, in seconds. Cap lower for user-facing paths and higher for backfills |
+| `plan_timeout` | `30` | Ceiling on Trino query-planning phase, in seconds |
+| `slow_query_threshold_seconds` | `20` | Threshold above which an `active_record_trino.slow_query` notification is emitted |
+
+## Instrumentation
+
+The adapter uses ActiveRecord's standard `AbstractAdapter#log` for query instrumentation, so any `ActiveSupport::Notifications` subscriber on `sql.active_record` picks up Trino queries automatically.
+
+In addition, queries exceeding `slow_query_threshold_seconds` emit an `active_record_trino.slow_query` notification with payload `{ sql:, duration:, query_id:, info_uri: }`. The `info_uri` deep-links to the query's stats page in the Trino web UI, which is handy for diagnosing slow paths.
+
+## Diagnostics
+
+For one-off latency investigation, `ActiveRecord::Trino::Diagnostics.profile(model_class)` runs a sample query and reports where the time went, broken down between the Ruby/AR side and Trino's own per-query stats:
+
+```ruby
+ActiveRecord::Trino::Diagnostics.profile(SalesByDay)
+# => {
+#   schema_time: 0.45,           # Ruby-side seconds for information_schema.columns
+#   query_time: 1.12,            # Ruby-side seconds for the sample SELECT
+#   query_id: "20260520_...",    # Trino query_id (deep-link via info_uri)
+#   info_uri: "https://...",     # URL to the query's stats page
+#   queued_time_ms: 50,          # Trino-side: queued waiting for resources
+#   elapsed_time_ms: 800,        # Trino-side: total wall clock
+#   cpu_time_ms: 200,            # Trino-side: CPU time spent
+#   wall_time_ms: 750,           # Trino-side: execution wall time
+#   state: "FINISHED"
+# }
+```
+
+The same metadata is available on the connection after any query:
+
+```ruby
+SalesByDay.first
+connection = SalesByDay.connection
+connection.last_query_id        # Trino query_id of the most recent query
+connection.last_query_info_uri  # Direct URL to the Trino UI for that query
+connection.last_query_stats     # Hash of state, queued_time_millis, elapsed_time_millis, etc.
+```
+
+## Development
+
+1. Clone the repository.
+2. Install dependencies: `bundle install`.
+3. Run the test suite: `bundle exec rspec`.
+4. Run the linter: `bundle exec rubocop`.
+
+### Testing across Rails versions
+
+Use Appraisal to run the suite against each supported Rails minor:
+
+```bash
+bundle exec appraisal install
+bundle exec appraisal rspec
+```
+
+### Testing changes locally in another app
+
+```ruby
+# In the consuming application's Gemfile
+gem "activerecord-trino-adapter", path: "path/to/activerecord-trino-adapter"
+```
+
+## License
+
+This project is licensed under the MIT License — see the [LICENSE.txt](LICENSE.txt) file for details.

data/lib/active_record/connection_adapters/trino/column.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "active_record/connection_adapters/column"
+
+module ActiveRecord
+  module ConnectionAdapters
+    module Trino
+      class Column < ActiveRecord::ConnectionAdapters::Column
+        def initialize(name:, sql_type:, type:, null: true)
+          metadata = ActiveRecord::ConnectionAdapters::SqlTypeMetadata.new(
+            sql_type: sql_type,
+            type: type.type
+          )
+          super(name.to_s, nil, metadata, null)
+          @cast_type = type
+        end
+
+        attr_reader :cast_type
+      end
+    end
+  end
+end

data/lib/active_record/connection_adapters/trino/database_statements.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  module ConnectionAdapters
+    module Trino
+      module DatabaseStatements
+        SLOW_QUERY_NOTIFICATION = "active_record_trino.slow_query"
+
+        STAT_FIELDS = %i[
+          state
+          queued_time_millis
+          elapsed_time_millis
+          cpu_time_millis
+          wall_time_millis
+        ].freeze
+
+        InternalResult = Struct.new(:column_names, :rows, :column_types, keyword_init: true)
+
+        def execute(sql, name = nil, **_kwargs)
+          log(sql, name) { run_trino_query(sql) }
+        end
+
+        # Rails 7.1 public path.
+        def exec_query(sql, name = "SQL", binds = [], prepare: false, async: false)
+          internal_exec_query(sql, name, binds, prepare: prepare, async: async)
+        end
+
+        # Rails 7.2+/8.0 canonical path that AR's select_all/select route through.
+        # rubocop:disable Lint/UnusedMethodArgument, Metrics/ParameterLists
+        def internal_exec_query(sql, name = "SQL", binds = [], prepare: false, async: false, allow_retry: false)
+          unless binds.empty?
+            raise ActiveRecord::Trino::Error,
+                  "activerecord-trino-adapter: bind variables are not supported; got #{binds.size} bind(s)"
+          end
+
+          internal = log(sql, name) { run_trino_query(sql) }
+          ActiveRecord::Result.new(internal.column_names, internal.rows, internal.column_types)
+        end
+        # rubocop:enable Lint/UnusedMethodArgument, Metrics/ParameterLists
+
+        def select_value(arel, name = nil, binds = [])
+          result = select_all(arel, name, binds)
+          result.rows.first&.first
+        end
+
+        def select_values(arel, name = nil, binds = [])
+          result = select_all(arel, name, binds)
+          result.rows.map(&:first)
+        end
+
+      private
+
+        # rubocop:disable Metrics/AbcSize
+        def run_trino_query(sql)
+          start = monotonic_now
+          query = client.query(sql)
+          internal = consume_query(query)
+          capture_query_metadata(query)
+          notify_slow_query(sql, monotonic_now - start)
+          internal
+        rescue ::Trino::Client::TrinoQueryTimeoutError => e
+          raise ActiveRecord::StatementTimeout.new(e.message, sql: sql)
+        rescue ::Trino::Client::TrinoQueryError => e
+          raise ActiveRecord::StatementInvalid.new(e.message, sql: sql)
+        rescue ::Trino::Client::TrinoHttpError => e
+          raise ActiveRecord::ConnectionFailed, e.message
+        ensure
+          query&.close if defined?(query) && query
+        end
+        # rubocop:enable Metrics/AbcSize
+
+        def consume_query(query)
+          columns = query.columns || []
+          rows = []
+          query.each_row_chunk { |chunk| rows.concat(chunk) if chunk }
+
+          column_names = columns.map(&:name)
+          column_types = columns.to_h { |c| [c.name, type_map.lookup(c.type)] }
+          InternalResult.new(column_names: column_names, rows: rows, column_types: column_types)
+        end
+
+        # Pull the Trino-side query metadata off of the final QueryResults
+        # page so callers can cross-reference in the Trino UI. Defensive
+        # against minor model differences across trino-client versions.
+        def capture_query_metadata(query)
+          results = query.current_results
+          return unless results
+
+          @last_query_id = results.id if results.respond_to?(:id)
+          @last_query_info_uri = results.info_uri if results.respond_to?(:info_uri)
+          @last_query_stats = extract_stats(results.stats) if results.respond_to?(:stats)
+        end
+
+        def extract_stats(stats)
+          return {} unless stats
+
+          STAT_FIELDS.each_with_object({}) do |field, acc|
+            acc[field] = stats.public_send(field) if stats.respond_to?(field)
+          end
+        end
+
+        def notify_slow_query(sql, duration)
+          return if duration < @slow_query_threshold
+
+          ActiveSupport::Notifications.instrument(
+            SLOW_QUERY_NOTIFICATION,
+            sql: sql,
+            duration: duration,
+            query_id: @last_query_id,
+            info_uri: @last_query_info_uri
+          )
+        end
+
+        def monotonic_now
+          Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        end
+      end
+    end
+  end
+end

data/lib/active_record/connection_adapters/trino/quoting.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+require "date"
+require "time"
+
+module ActiveRecord
+  module ConnectionAdapters
+    module Trino
+      module Quoting
+        QUOTED_TRUE = "true"
+        QUOTED_FALSE = "false"
+        QUOTED_NULL = "NULL"
+
+        TIMESTAMP_FORMAT = "%Y-%m-%d %H:%M:%S.%3N"
+        DATE_FORMAT = "%Y-%m-%d"
+
+        NUL_BYTE = /\x00/
+
+        # rubocop:disable Metrics/CyclomaticComplexity, Lint/DuplicateBranch
+        def quote(value)
+          case value
+          when nil then QUOTED_NULL
+          when true then QUOTED_TRUE
+          when false then QUOTED_FALSE
+          when BigDecimal then value.to_s("F")
+          when Numeric then value.to_s
+          when ::Date then "DATE '#{value.strftime(DATE_FORMAT)}'"
+          when ::Time, ::DateTime then quote_time(value)
+          when Symbol, String then quote_string_literal(value.to_s)
+          else quote_string_literal(value.to_s)
+          end
+        end
+        # rubocop:enable Metrics/CyclomaticComplexity, Lint/DuplicateBranch
+
+        def quote_string(string)
+          str = string.to_s
+          if str.match?(NUL_BYTE)
+            raise ActiveRecord::Trino::Error,
+                  "activerecord-trino-adapter: NUL byte detected in literal; refusing to quote"
+          end
+          str.gsub("'", "''")
+        end
+
+        def quote_column_name(name)
+          %("#{name.to_s.gsub('"', '""')}")
+        end
+
+        def quote_table_name(name)
+          name.to_s.split(".").map { |part| quote_column_name(part) }.join(".")
+        end
+
+        def quoted_true
+          QUOTED_TRUE
+        end
+
+        def quoted_false
+          QUOTED_FALSE
+        end
+
+        def quoted_date(value)
+          value.strftime(DATE_FORMAT)
+        end
+
+      private
+
+        def quote_string_literal(string)
+          "'#{quote_string(string)}'"
+        end
+
+        def quote_time(value)
+          time = value.respond_to?(:utc) ? value.utc : value
+          "TIMESTAMP '#{time.strftime(TIMESTAMP_FORMAT)}'"
+        end
+      end
+    end
+  end
+end

data/lib/active_record/connection_adapters/trino/read_only.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  module ConnectionAdapters
+    module Trino
+      module ReadOnly
+        WRITE_METHODS = %i[
+          insert
+          update
+          delete
+          exec_insert
+          exec_update
+          exec_delete
+          insert_fixture
+          insert_fixtures_set
+          truncate
+          truncate_tables
+          begin_db_transaction
+          commit_db_transaction
+          rollback_db_transaction
+          exec_rollback_db_transaction
+          begin_isolated_db_transaction
+          create_savepoint
+          exec_rollback_to_savepoint
+          release_savepoint
+          create_table
+          drop_table
+          create_join_table
+          drop_join_table
+          rename_table
+          add_column
+          remove_column
+          change_column
+          change_column_default
+          change_column_null
+          rename_column
+          add_index
+          remove_index
+          rename_index
+          add_foreign_key
+          remove_foreign_key
+          add_reference
+          remove_reference
+          add_belongs_to
+          remove_belongs_to
+          add_check_constraint
+          remove_check_constraint
+        ].freeze
+
+        WRITE_METHODS.each do |method|
+          define_method(method) do |*_args, **_kwargs, &_block|
+            raise ActiveRecord::Trino::ReadOnlyError,
+                  "activerecord-trino-adapter: #{method} is not supported by the Trino adapter " \
+                  "(activerecord-trino-adapter is read-only)"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_record/connection_adapters/trino/safety_belts.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  module ConnectionAdapters
+    module Trino
+      # Behaviors that constrain AR's typical OLTP-shaped query patterns so they
+      # don't accidentally hammer a Trino warehouse. Currently:
+      #
+      #   - `find_each` / `find_in_batches` raise: Trino's pagination model does
+      #     not fit AR's batching cursor.
+      #
+      # Timeouts and slow-query notifications live in DatabaseStatements; they
+      # apply regardless of caller pattern.
+      module SafetyBelts
+        BATCH_METHODS = %i[find_each find_in_batches in_batches].freeze
+
+        BATCH_METHODS.each do |method|
+          define_method(method) do |*_args, **_kwargs, &_block|
+            raise ActiveRecord::Trino::Error,
+                  "activerecord-trino-adapter: #{method} is not supported on Trino-backed models. " \
+                  "Use explicit LIMIT/OFFSET pagination or pluck aggregates instead."
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_record/connection_adapters/trino/schema_statements.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  module ConnectionAdapters
+    module Trino
+      module SchemaStatements
+        def columns(table_name)
+          rows = run_trino_query(columns_query(table_name.to_s)).rows
+          rows.map do |name, data_type, is_nullable|
+            Trino::Column.new(
+              name: name,
+              sql_type: data_type,
+              type: type_map.lookup(data_type),
+              null: nullable?(is_nullable)
+            )
+          end
+        end
+
+        def data_sources
+          run_trino_query("SHOW TABLES").rows.map(&:first)
+        end
+        alias tables data_sources
+
+        def table_exists?(table_name)
+          data_sources.include?(table_name.to_s)
+        end
+        alias data_source_exists? table_exists?
+
+        def primary_key(_table_name)
+          nil
+        end
+
+        def indexes(_table_name)
+          []
+        end
+
+        def foreign_keys(_table_name)
+          []
+        end
+
+        def views
+          []
+        end
+
+        def view_exists?(_view_name)
+          false
+        end
+
+        def schema_cache
+          @schema_cache ||= ActiveRecord::ConnectionAdapters::SchemaCache.new(self)
+        end
+
+      private
+
+        def columns_query(table_name)
+          <<~SQL.strip
+            SELECT column_name, data_type, is_nullable
+            FROM information_schema.columns
+            WHERE table_catalog = #{quote(trino_catalog)}
+              AND table_schema = #{quote(trino_schema)}
+              AND table_name = #{quote(table_name)}
+            ORDER BY ordinal_position
+          SQL
+        end
+
+        def trino_catalog
+          @client_options[:catalog]
+        end
+
+        def trino_schema
+          @client_options[:schema]
+        end
+
+        def nullable?(value)
+          value.to_s.casecmp?("yes")
+        end
+      end
+    end
+  end
+end

data/lib/active_record/connection_adapters/trino/type_map.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require "active_model"
+
+module ActiveRecord
+  module ConnectionAdapters
+    module Trino
+      class TypeMap
+        DECIMAL_PATTERN = /\Adecimal\((\d+)\s*(?:,\s*(\d+))?\)\z/i
+        TIMESTAMP_TZ_PATTERN = /\Atimestamp(?:\(\d+\))?\s+with\s+time\s+zone\z/i
+        COMPOSITE_PATTERN = /\A(?:array|map|row)\(/i
+
+        def self.build
+          new
+        end
+
+        def initialize
+          @cache = {}
+        end
+
+        def lookup(trino_type)
+          @cache[trino_type] ||= build_type(trino_type.to_s)
+        end
+
+      private
+
+        def build_type(sql_type)
+          normalized = sql_type.strip.downcase
+
+          string_type(normalized) ||
+            integer_type(normalized) ||
+            float_type(normalized) ||
+            date_time_type(normalized) ||
+            decimal_type(normalized) ||
+            scalar_type(normalized) ||
+            unsupported_type(normalized)
+        end
+
+        def string_type(normalized)
+          case normalized
+          when "varchar", /\Avarchar\(\d+\)\z/,
+               "char", /\Achar\(\d+\)\z/,
+               "varbinary", /\Avarbinary\(\d+\)\z/,
+               "uuid", "ipaddress", "hyperloglog", "qdigest"
+            ActiveModel::Type::String.new
+          end
+        end
+
+        def integer_type(normalized)
+          case normalized
+          when "tinyint" then ActiveModel::Type::Integer.new(limit: 1)
+          when "smallint" then ActiveModel::Type::Integer.new(limit: 2)
+          when "integer", "int" then ActiveModel::Type::Integer.new(limit: 4)
+          when "bigint" then ActiveModel::Type::Integer.new(limit: 8)
+          end
+        end
+
+        def float_type(normalized)
+          case normalized
+          when "real", "double" then ActiveModel::Type::Float.new
+          end
+        end
+
+        def date_time_type(normalized)
+          case normalized
+          when "date" then ActiveModel::Type::Date.new
+          when "time", /\Atime\(\d+\)\z/ then ActiveModel::Type::Time.new
+          when TIMESTAMP_TZ_PATTERN then ActiveRecord::Trino::Type::TimestampWithZone.new
+          when "timestamp", /\Atimestamp\(\d+\)\z/ then ActiveModel::Type::DateTime.new
+          end
+        end
+
+        def decimal_type(normalized)
+          return unless (match = DECIMAL_PATTERN.match(normalized))
+
+          ActiveModel::Type::Decimal.new(
+            precision: match[1].to_i,
+            scale: (match[2] || 0).to_i
+          )
+        end
+
+        def scalar_type(normalized)
+          case normalized
+          when "boolean" then ActiveModel::Type::Boolean.new
+          when "json" then ActiveRecord::Trino::Type::Json.new
+          end
+        end
+
+        def unsupported_type(normalized)
+          ActiveRecord::Trino::Type::Unsupported.new(normalized)
+        end
+      end
+    end
+  end
+end

data/lib/active_record/connection_adapters/trino_adapter.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require "active_record"
+require "active_record/connection_adapters/abstract_adapter"
+require "trino-client"
+
+require "active_record/trino"
+
+require_relative "trino/quoting"
+require_relative "trino/type_map"
+require_relative "trino/column"
+require_relative "trino/database_statements"
+require_relative "trino/schema_statements"
+require_relative "trino/read_only"
+require_relative "trino/safety_belts"
+
+module ActiveRecord
+  module ConnectionAdapters
+    class TrinoAdapter < AbstractAdapter
+      ADAPTER_NAME = "Trino"
+
+      include Trino::Quoting
+      include Trino::DatabaseStatements
+      include Trino::SchemaStatements
+      include Trino::ReadOnly
+
+      def initialize(...)
+        super
+        @client_options = ActiveRecord::Trino::Config.client_options(@config)
+        @slow_query_threshold = ActiveRecord::Trino::Config.slow_query_threshold(@config)
+        @client = build_client
+        install_safety_belts!
+      end
+
+      def adapter_name
+        ADAPTER_NAME
+      end
+
+      def active?
+        !@client.nil?
+      end
+
+      def reconnect!
+        disconnect!
+        @client = build_client
+      end
+
+      def disconnect!
+        @client = nil
+      end
+
+      def supports_transactions?
+        false
+      end
+
+      def supports_savepoints?
+        false
+      end
+
+      def supports_lazy_transactions?
+        false
+      end
+
+      def supports_advisory_locks?
+        false
+      end
+
+      def supports_explain?
+        true
+      end
+
+      def supports_migrations?
+        false
+      end
+
+      def supports_ddl_transactions?
+        false
+      end
+
+      def supports_views?
+        false
+      end
+
+      # ActiveRecord's adapter API expects this method name without a question mark.
+      def prepared_statements # rubocop:disable Naming/PredicateMethod
+        false
+      end
+
+      def requires_reloading?
+        false
+      end
+
+      def native_database_types
+        {}
+      end
+
+      def lookup_cast_type(sql_type)
+        type_map.lookup(sql_type)
+      end
+
+      def lookup_cast_type_from_column(column)
+        column.cast_type
+      end
+
+      attr_reader :client, :last_query_id, :last_query_info_uri, :last_query_stats
+
+    private
+
+      def build_client
+        ::Trino::Client.new(@client_options)
+      end
+
+      def type_map
+        @type_map ||= Trino::TypeMap.build
+      end
+
+      def install_safety_belts!
+        return unless defined?(::ActiveRecord::Relation)
+
+        return if ::ActiveRecord::Relation.include?(RelationSafetyBelts)
+
+        ::ActiveRecord::Relation.prepend(RelationSafetyBelts)
+      end
+
+      # The safety belts override AR::Relation batch methods only when the relation's
+      # connection is a TrinoAdapter, so they don't leak into other databases used in
+      # the same process.
+      module RelationSafetyBelts
+        Trino::SafetyBelts::BATCH_METHODS.each do |method|
+          define_method(method) do |*args, **kwargs, &block|
+            if connection.is_a?(::ActiveRecord::ConnectionAdapters::TrinoAdapter)
+              raise ActiveRecord::Trino::Error,
+                    "activerecord-trino-adapter: #{method} is not supported on Trino-backed models. " \
+                    "Use explicit LIMIT/OFFSET pagination or pluck aggregates instead."
+            else
+              super(*args, **kwargs, &block)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_record/trino/config.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  module Trino
+    module Config
+      DEFAULT_QUERY_TIMEOUT = 150
+      DEFAULT_PLAN_TIMEOUT = 30
+      DEFAULT_SLOW_QUERY_THRESHOLD_SECONDS = 20
+      DEFAULT_HTTP_PORT = 8080
+      DEFAULT_HTTPS_PORT = 443
+
+      REQUIRED_KEYS = %i[host user catalog schema].freeze
+
+    module_function
+
+      def client_options(config)
+        symbolized = symbolize(config)
+        validate!(symbolized)
+        ssl = symbolized.fetch(:ssl, false)
+        port = symbolized.fetch(:port, default_port(ssl))
+        {
+          server: "#{symbolized[:host]}:#{port}",
+          user: symbolized[:user],
+          password: symbolized[:password],
+          catalog: symbolized[:catalog],
+          schema: symbolized[:schema],
+          ssl: ssl,
+          http_proxy: symbolized[:http_proxy],
+          time_zone: symbolized[:time_zone],
+          query_timeout: symbolized.fetch(:query_timeout, DEFAULT_QUERY_TIMEOUT),
+          plan_timeout: symbolized.fetch(:plan_timeout, DEFAULT_PLAN_TIMEOUT),
+        }.compact
+      end
+
+      def default_port(ssl)
+        ssl ? DEFAULT_HTTPS_PORT : DEFAULT_HTTP_PORT
+      end
+
+      def slow_query_threshold(config)
+        symbolized = symbolize(config)
+        symbolized.fetch(:slow_query_threshold_seconds, DEFAULT_SLOW_QUERY_THRESHOLD_SECONDS).to_f
+      end
+
+      def validate!(config)
+        symbolized = symbolize(config)
+        missing = REQUIRED_KEYS.reject { |k| symbolized[k] && !symbolized[k].to_s.empty? }
+        return if missing.empty?
+
+        raise ActiveRecord::Trino::ConfigurationError,
+              "activerecord-trino-adapter: missing required config keys: #{missing.join(', ')}"
+      end
+
+      def symbolize(config)
+        config.to_h.transform_keys(&:to_sym)
+      end
+    end
+  end
+end

data/lib/active_record/trino/diagnostics.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "benchmark"
+
+module ActiveRecord
+  module Trino
+    # Diagnostic helpers for Trino-backed models. Useful when
+    # investigating why a Trino-backed query is slow.
+    module Diagnostics
+    module_function
+
+      # Profile a Trino-backed AR model's first-query latency. Resets
+      # the column cache to force a schema re-fetch, times it, then runs
+      # a sample SELECT and pulls the per-query breakdown from Trino's
+      # own response.
+      #
+      # Returns a Hash with:
+      #   :schema_time      Float seconds spent on information_schema.columns
+      #   :query_time       Float seconds spent on the sample SELECT (Ruby-side)
+      #   :query_id         Trino query_id (cross-reference in the Trino UI)
+      #   :info_uri         URL to the query's stats page in the Trino UI
+      #   :queued_time_ms   Trino-side: time the query spent queued
+      #   :elapsed_time_ms  Trino-side: total wall clock (queued + execution)
+      #   :cpu_time_ms      Trino-side: CPU time spent on the query
+      #   :wall_time_ms     Trino-side: wall-clock execution time (planning + exec)
+      #   :state            "FINISHED" / "FAILED" / etc.
+      #
+      # Note: the Trino 351 StatementStats model does not expose
+      # planning_time as a discrete field — it is folded into wall_time.
+      # If you need the planning slice specifically, subtract wall_time
+      # from elapsed_time as a rough approximation.
+      def profile(model_class)
+        connection = model_class.connection
+        model_class.reset_column_information
+        schema_time = ::Benchmark.realtime { model_class.columns }
+
+        # Issue the sample SELECT through the adapter directly so it is the
+        # last query touching the connection — AR's higher-level paths can
+        # fire follow-up bookkeeping queries (SHOW TABLES, etc.) that would
+        # otherwise overwrite last_query_* before we read them.
+        table = connection.quote_table_name(model_class.table_name)
+        sql = "SELECT * FROM #{table} LIMIT 1"
+        query_time = ::Benchmark.realtime { connection.exec_query(sql) }
+
+        build_result(connection, schema_time, query_time)
+      end
+
+      def build_result(connection, schema_time, query_time)
+        stats = connection.last_query_stats || {}
+        {
+          schema_time: schema_time,
+          query_time: query_time,
+          query_id: connection.last_query_id,
+          info_uri: connection.last_query_info_uri,
+          queued_time_ms: stats[:queued_time_millis],
+          elapsed_time_ms: stats[:elapsed_time_millis],
+          cpu_time_ms: stats[:cpu_time_millis],
+          wall_time_ms: stats[:wall_time_millis],
+          state: stats[:state],
+        }
+      end
+    end
+  end
+end

data/lib/active_record/trino/errors.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  module Trino
+    class Error < StandardError; end
+
+    class ReadOnlyError < Error; end
+
+    class UnsupportedTypeError < Error; end
+
+    class ConfigurationError < Error; end
+  end
+end

data/lib/active_record/trino/type/json.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "active_model"
+require "json"
+
+module ActiveRecord
+  module Trino
+    module Type
+      class Json < ActiveModel::Type::Value
+        def type
+          :json
+        end
+
+        def cast(value)
+          return value if value.nil? || value.is_a?(::Hash) || value.is_a?(::Array)
+          return value unless value.is_a?(::String)
+
+          ::JSON.parse(value)
+        rescue ::JSON::ParserError
+          value
+        end
+      end
+    end
+  end
+end

data/lib/active_record/trino/type/timestamp_with_zone.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "active_model"
+require "time"
+
+module ActiveRecord
+  module Trino
+    module Type
+      class TimestampWithZone < ActiveModel::Type::Value
+        def type
+          :datetime
+        end
+
+        def cast(value)
+          return value if value.nil? || value.is_a?(::Time) || value.is_a?(::DateTime)
+          return value unless value.is_a?(::String)
+
+          ::Time.parse(value)
+        rescue ::ArgumentError
+          value
+        end
+      end
+    end
+  end
+end

data/lib/active_record/trino/type/unsupported.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "active_model"
+
+module ActiveRecord
+  module Trino
+    module Type
+      class Unsupported < ActiveModel::Type::Value
+        def initialize(trino_type = nil)
+          super()
+          @trino_type = trino_type
+        end
+
+        def type
+          :unsupported
+        end
+
+        def cast(_value)
+          raise ActiveRecord::Trino::UnsupportedTypeError,
+                "activerecord-trino-adapter: cannot cast Trino type #{@trino_type.inspect}; " \
+                "select scalar columns explicitly or extract values via Trino SQL"
+        end
+      end
+    end
+  end
+end

data/lib/active_record/trino/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  module Trino
+    VERSION = "0.1.0"
+  end
+end

data/lib/active_record/trino.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "active_record"
+require "active_support"
+require "active_support/notifications"
+require "trino-client"
+
+require_relative "trino/version"
+require_relative "trino/errors"
+require_relative "trino/config"
+require_relative "trino/type/json"
+require_relative "trino/type/timestamp_with_zone"
+require_relative "trino/type/unsupported"
+require_relative "trino/diagnostics"
+
+if ActiveRecord::ConnectionAdapters.respond_to?(:register)
+  ActiveRecord::ConnectionAdapters.register(
+    "trino",
+    "ActiveRecord::ConnectionAdapters::TrinoAdapter",
+    "active_record/connection_adapters/trino_adapter"
+  )
+else
+  # Rails 7.1 uses the legacy adapter_method pattern: ActiveRecord::Base needs
+  # a trino_connection class method that returns a new TrinoAdapter. Rails 7.2+
+  # replaced this with ConnectionAdapters.register above.
+  require "active_record/connection_adapters/trino_adapter"
+  ActiveRecord::Base.singleton_class.define_method(:trino_connection) do |config|
+    ActiveRecord::ConnectionAdapters::TrinoAdapter.new(config)
+  end
+end
+
+module ActiveRecord
+  module Trino
+    def self.reset_schema_cache!(model_class)
+      model_class.reset_column_information
+      return unless model_class.connection.respond_to?(:schema_cache)
+
+      model_class.connection.schema_cache.clear!
+    end
+  end
+end

metadata

@@ -0,0 +1,216 @@
+--- !ruby/object:Gem::Specification
+name: activerecord-trino-adapter
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Garett Arrowood
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.1'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.1'
+- !ruby/object:Gem::Dependency
+  name: trino-client
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 2.2.4
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 2.2.4
+- !ruby/object:Gem::Dependency
+  name: appraisal
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 2.5.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 2.5.0
+- !ruby/object:Gem::Dependency
+  name: license_finder
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 7.2.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 7.2.1
+- !ruby/object:Gem::Dependency
+  name: pry-byebug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 3.10.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 3.10.1
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 3.13.2
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 3.13.2
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 1.82.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 1.82.1
+- !ruby/object:Gem::Dependency
+  name: rubocop-powerhome
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 3.26.2
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 3.26.2
+description: A read-only ActiveRecord SQL adapter for Trino, built on top of the trino-client
+  gem. Lets Rails applications query a Trino data warehouse using familiar ActiveRecord
+  scopes, where clauses, and joins, while preventing accidental writes.
+email:
+- garettarrowood@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- lib/active_record/connection_adapters/trino/column.rb
+- lib/active_record/connection_adapters/trino/database_statements.rb
+- lib/active_record/connection_adapters/trino/quoting.rb
+- lib/active_record/connection_adapters/trino/read_only.rb
+- lib/active_record/connection_adapters/trino/safety_belts.rb
+- lib/active_record/connection_adapters/trino/schema_statements.rb
+- lib/active_record/connection_adapters/trino/type_map.rb
+- lib/active_record/connection_adapters/trino_adapter.rb
+- lib/active_record/trino.rb
+- lib/active_record/trino/config.rb
+- lib/active_record/trino/diagnostics.rb
+- lib/active_record/trino/errors.rb
+- lib/active_record/trino/type/json.rb
+- lib/active_record/trino/type/timestamp_with_zone.rb
+- lib/active_record/trino/type/unsupported.rb
+- lib/active_record/trino/version.rb
+homepage: https://github.com/powerhome/activerecord-trino-adapter
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/powerhome/activerecord-trino-adapter
+  source_code_uri: https://github.com/powerhome/activerecord-trino-adapter
+  changelog_uri: https://github.com/powerhome/activerecord-trino-adapter/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: Read-only ActiveRecord adapter for Trino
+test_files: []