athar 0.3.2 → 0.3.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3606e5dbd82d65ccb6070d0cd82a6408110f10eb6a449546d7ec4cf573d2cbd6
-  data.tar.gz: 158b8db5f4ce145bee31e562dfc6ab9ced0b7e5bab2c8cfbe7268b129c276836
+  metadata.gz: a2d955a6b91e0235f3d0320d0955a0ab48bb1d006dff1c9170b2b421d0d1eeea
+  data.tar.gz: 86d78661ae27929bca015f19de65a76fffc779360fb5c25b1a36bdbf88e738d6
 SHA512:
-  metadata.gz: 29961e6f2302bb2cc732629ccf57d775fa089f950424860e73b9d56b8f26faebd0dc00874137597774c33e450cd6c3ae32ab62b0647d7c842d8b44beb76ebac6
-  data.tar.gz: 3a6229cc444e9fe48d84fa8c61c00690047422d604b25a8daa0461222279684b1471d0b936a9648eccfbb659aa6b1707dd8ac1d305b1748535c2b12d0632af09
+  metadata.gz: 040a8737dabee43a223852a9d0c7d3678f7fe9e76df2fb5303bedaffa96a37a8e4bfa7f00d797ef439440b48745d9209c932248ebc4dfba7b5bfa5dd657f678f
+  data.tar.gz: 1303fbf477398696d6d7eac30f8ea7be923c5e54042f1b1539b118687d9f2e480c1a49794d8529ef073a8a438e15b94d7e8e87c17f35eb84114cd4fb0d89645b

data/CHANGELOG.md

@@ -4,6 +4,17 @@ All notable changes to this project will be documented in this file.
 
 The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.
 
+## [0.3.3] - 2026-05-10
+
+### Fixed
+
+- Fixed `PG::DatatypeMismatch: UNION types <pk_type> and bigint cannot be matched` when opening the dashboard on hosts where `Rails.configuration.generators.options[:active_record][:primary_key_type] = :uuid` (or `:integer`) caused the install migration to create the audit tables with a non-bigint primary key. The dashboard's UNION between `athar_deletions` and `athar_table_events` now resolves the audit `id` SQL type at runtime and types the empty UNION leg accordingly, so it composes cleanly regardless of the host's primary-key choice.
+
+### Added
+
+- `Athar.audit_connection` and `Athar.audit_db_config` module methods centralizing the connection both audit tables share. Multi-database hosts can route audit storage to a dedicated connection by calling `Athar::Deletion.connects_to(...)` in an initializer; the dashboard, retention, and generators follow automatically. The dashboard topbar now reflects the audit DB name when this routing is configured.
+- `FeedQuery` raises `ArgumentError` up-front when `athar_deletions.id` and `athar_table_events.id` resolve to different SQL types, replacing a cryptic Postgres UNION error with a clear message naming both tables and their detected types.
+
 ## [0.3.2] - 2026-05-10
 
 ### Fixed

data/lib/athar/dashboard/actor_options.rb

@@ -10,17 +10,17 @@ module Athar
         @cutoff = cutoff
       end
 
-      def call(connection: ActiveRecord::Base.connection)
+      def call
         Result.new(
-          users: load_users(connection),
-          system: load_system(connection),
+          users: load_users,
+          system: load_system,
           anonymous_label: "(anonymous)"
         )
       end
 
       private
 
-      def load_users(connection) # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
+      def load_users # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
         rows = connection.select_all(<<~SQL).to_a
           SELECT actor_type, actor_id::text AS actor_id, MAX(deleted_at) AS last_seen
           FROM #{Athar::DELETIONS_TABLE_NAME}
@@ -50,7 +50,7 @@ module Athar
         end
       end
 
-      def load_system(connection)
+      def load_system
         rows = connection.select_all(<<~SQL).to_a
           SELECT metadata->>'actor' AS name, MAX(deleted_at) AS last_seen
           FROM #{Athar::DELETIONS_TABLE_NAME}
@@ -64,7 +64,11 @@ module Athar
       end
 
       def quote(value)
-        ActiveRecord::Base.connection.quote(value)
+        connection.quote(value)
+      end
+
+      def connection
+        Athar.audit_connection
       end
     end
   end

data/lib/athar/dashboard/connection_info.rb

@@ -6,12 +6,9 @@ module Athar
     class ConnectionInfo
       attr_reader :database, :version
 
-      def self.fetch(
-        connection: ActiveRecord::Base.connection,
-        db_config: ActiveRecord::Base.connection_db_config
-      )
-        version_num = connection.select_value("SHOW server_version_num").to_i
-        new(database: db_config.database.to_s, version: "pg#{version_num / 10_000}")
+      def self.fetch
+        version_num = Athar.audit_connection.select_value("SHOW server_version_num").to_i
+        new(database: Athar.audit_db_config.database.to_s, version: "pg#{version_num / 10_000}")
       end
 
       def initialize(database:, version:)

data/lib/athar/dashboard/feed_query.rb

@@ -3,9 +3,6 @@
 module Athar
   module Dashboard
     class FeedQuery # rubocop:disable Metrics/ClassLength
-      # Typed empty SELECT used for either UNION leg when the kind filter
-      # excludes that leg. Column types must match the live SELECTs above
-      # so PostgreSQL can compose the UNION without coercion.
       DELETION_SEARCH_COLUMNS = %w[
         record_type record_id::text schema_name table_name
         actor_type actor_id::text record_data::text metadata::text
@@ -15,22 +12,6 @@ module Athar
         schema_name table_name actor_type actor_id::text metadata::text
       ].freeze
 
-      EMPTY_LEG_SELECT = <<~SQL
-        SELECT
-          NULL::text        AS kind,
-          NULL::bigint      AS id,
-          NULL::text        AS record_type,
-          NULL::text        AS record_id,
-          NULL::text        AS schema_name,
-          NULL::text        AS table_name,
-          NULL::text        AS actor_type,
-          NULL::text        AS actor_id,
-          NULL::timestamptz AS occurred_at,
-          NULL::jsonb       AS record_data,
-          NULL::jsonb       AS metadata
-        WHERE FALSE
-      SQL
-
       def initialize(filters:, per_page: 25, now: Time.current, registry: nil)
         @filters = filters
         @per_page = per_page
@@ -38,11 +19,13 @@ module Athar
         @registry = registry
       end
 
-      def call(connection: ActiveRecord::Base.connection)
+      def call
+        audit_id_type # raise early on type mismatch instead of letting Postgres bubble a cryptic error
         connection.select_all(page_sql, "FeedQuery#call").map { |row| to_row(row) }
       end
 
-      def total(connection: ActiveRecord::Base.connection)
+      def total
+        audit_id_type
         connection.select_value(count_sql, "FeedQuery#total").to_i
       end
 
@@ -67,7 +50,7 @@ module Athar
       end
 
       def deletion_select
-        return EMPTY_LEG_SELECT if filters.kind == "truncate"
+        return empty_leg_select if filters.kind == "truncate"
 
         <<~SQL
           SELECT
@@ -88,7 +71,7 @@ module Athar
       end
 
       def table_event_select
-        return EMPTY_LEG_SELECT if filters.kind == "delete"
+        return empty_leg_select if filters.kind == "delete"
 
         <<~SQL
           SELECT
@@ -108,13 +91,52 @@ module Athar
         SQL
       end
 
+      def empty_leg_select
+        <<~SQL
+          SELECT
+            NULL::text             AS kind,
+            NULL::#{audit_id_type} AS id,
+            NULL::text             AS record_type,
+            NULL::text             AS record_id,
+            NULL::text             AS schema_name,
+            NULL::text             AS table_name,
+            NULL::text             AS actor_type,
+            NULL::text             AS actor_id,
+            NULL::timestamptz      AS occurred_at,
+            NULL::jsonb            AS record_data,
+            NULL::jsonb            AS metadata
+          WHERE FALSE
+        SQL
+      end
+
+      # Native SQL type of the `id` column on both audit tables, used to type
+      # the empty UNION leg so it matches the live legs without coercion.
+      # The two tables are always created together by the install migration
+      # and share the same primary_key_type; we verify that here so a manual
+      # divergence raises a clear error rather than a cryptic UNION mismatch.
+      def audit_id_type
+        @audit_id_type ||= begin
+          deletions = connection.columns(Athar::DELETIONS_TABLE_NAME).find { |c| c.name == "id" }.sql_type
+          events = connection.columns(Athar::TABLE_EVENTS_TABLE_NAME).find { |c| c.name == "id" }.sql_type
+
+          if deletions != events
+            raise ArgumentError,
+                  "athar audit tables have mismatched id sql_types: " \
+                  "#{Athar::DELETIONS_TABLE_NAME}.id=#{deletions}, " \
+                  "#{Athar::TABLE_EVENTS_TABLE_NAME}.id=#{events}"
+          end
+
+          deletions
+        end
+      end
+
       def deletion_where_clause # rubocop:disable Metrics/AbcSize
         clauses = ["TRUE"]
         clauses << time_clause("deleted_at")
         clauses << "record_type = #{quote(filters.model)}" if filters.model
         # capture_mode is not on the audit row; mode filter operates by table.
         clauses << tables_with_mode_clause(filters.mode) if filters.mode != "all"
-        clauses << actor_clause("athar_deletions")
+        clauses << actor_clause
         clauses << search_clause(DELETION_SEARCH_COLUMNS)
         clauses.compact.join(" AND ")
       end
@@ -124,7 +146,7 @@ module Athar
         clauses << time_clause("occurred_at")
         clauses << tables_for_model_clause if filters.model
         clauses << tables_with_mode_clause(filters.mode) if filters.mode != "all"
-        clauses << actor_clause("athar_table_events")
+        clauses << actor_clause
         clauses << search_clause(TABLE_EVENT_SEARCH_COLUMNS)
         clauses.compact.join(" AND ")
       end
@@ -136,7 +158,7 @@ module Athar
         "#{column} >= #{quote(cutoff)}"
       end
 
-      def actor_clause(_table)
+      def actor_clause
         actor_filter = filters.actor_filter
         return nil unless actor_filter
 
@@ -182,13 +204,17 @@ module Athar
       end
 
       def quote(value)
-        ActiveRecord::Base.connection.quote(value)
+        connection.quote(value)
+      end
+
+      def connection
+        Athar.audit_connection
       end
 
       def to_row(hash)
         {
           kind: hash["kind"],
-          id: hash["id"].to_i,
+          id: hash["id"],
           record_type: hash["record_type"],
           record_id: hash["record_id"],
           schema_name: hash["schema_name"],

data/lib/athar/dashboard/kpi_calculator.rb

@@ -19,27 +19,27 @@ module Athar
         @registry = registry
       end
 
-      def call(connection: ActiveRecord::Base.connection) # rubocop:disable Metrics/AbcSize
-        aggregates = aggregate(connection)
-        truncates_30d = truncate_count(connection)
+      def call # rubocop:disable Metrics/AbcSize
+        aggregates = aggregate
+        truncates_30d = truncate_count
 
         Result.new(
           # scope_total covers the same universe the feed UNIONs over: row
           # deletions plus all table events for the model's tables (not just
           # the last 30d), so "filtered N of M" never overshoots M.
-          scope_total: aggregates["scope_total"].to_i + table_event_total(connection),
+          scope_total: aggregates["scope_total"].to_i + table_event_total,
           last_24h: aggregates["last_24h"].to_i,
           last_7d: aggregates["last_7d"].to_i,
           prior_7d: aggregates["prior_7d"].to_i,
           distinct_actors_30d: aggregates["distinct_actors_30d"].to_i,
           truncates_30d: truncates_30d,
-          sparkline: Sparkline.new(model: @model, now: @now).buckets(connection: connection)
+          sparkline: Sparkline.new(model: @model, now: @now).buckets
         )
       end
 
       private
 
-      def aggregate(connection) # rubocop:disable Metrics/AbcSize
+      def aggregate # rubocop:disable Metrics/AbcSize
         sql = <<~SQL
           SELECT
             COUNT(*) AS scope_total,
@@ -56,7 +56,7 @@ module Athar
         connection.select_one(sql)
       end
 
-      def truncate_count(connection)
+      def truncate_count
         sql = <<~SQL
           SELECT COUNT(*) AS n FROM #{Athar::TABLE_EVENTS_TABLE_NAME}
           WHERE event_type = 'truncate' AND occurred_at > #{quote(@now - 30.days)}
@@ -65,7 +65,7 @@ module Athar
         connection.select_value(sql).to_i
       end
 
-      def table_event_total(connection)
+      def table_event_total
         sql = <<~SQL
           SELECT COUNT(*) AS n FROM #{Athar::TABLE_EVENTS_TABLE_NAME}
           WHERE TRUE #{table_scope_clause}
@@ -95,7 +95,11 @@ module Athar
       end
 
       def quote(value)
-        ActiveRecord::Base.connection.quote(value)
+        connection.quote(value)
+      end
+
+      def connection
+        Athar.audit_connection
       end
     end
   end

data/lib/athar/dashboard/model_registry.rb

@@ -37,7 +37,8 @@ module Athar
       PG_ARRAY_BARE   = /[^,]+/
 
       class << self
-        def discover(connection = ActiveRecord::Base.connection) # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/MethodLength,Metrics/PerceivedComplexity
+        def discover # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/MethodLength,Metrics/PerceivedComplexity
+          connection = Athar.audit_connection
           triggers = parse_delete_triggers(connection)
           truncate_keys = truncate_trigger_keys(connection)
           counts = load_counts(connection)

data/lib/athar/dashboard/sparkline.rb

@@ -10,7 +10,7 @@ module Athar
         @now = now
       end
 
-      def buckets(connection: ActiveRecord::Base.connection) # rubocop:disable Metrics/AbcSize
+      def buckets # rubocop:disable Metrics/AbcSize
         rows = connection.select_all(<<~SQL).to_a
           SELECT date_trunc('day', deleted_at) AS day, COUNT(*) AS n
           FROM #{Athar::DELETIONS_TABLE_NAME}
@@ -35,7 +35,11 @@ module Athar
       end
 
       def quote(value)
-        ActiveRecord::Base.connection.quote(value)
+        connection.quote(value)
+      end
+
+      def connection
+        Athar.audit_connection
       end
     end
   end

data/lib/athar/retention.rb

@@ -60,7 +60,7 @@ module Athar
       def prune_by_age(table, time_column, cutoff, batch_size, max_batches) # rubocop:disable Metrics/MethodLength
         return [0, 0] if max_batches <= 0
 
-        connection = ActiveRecord::Base.connection
+        connection = Athar.audit_connection
         total = 0
         batches = 0
         loop do
@@ -88,7 +88,7 @@ module Athar
       def prune_by_count(table, max_count, batch_size, max_batches) # rubocop:disable Metrics/MethodLength
         return [0, 0] if max_batches <= 0
 
-        connection = ActiveRecord::Base.connection
+        connection = Athar.audit_connection
         boundary = connection.select_one(
           <<~SQL
             SELECT deleted_at, id

data/lib/athar/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Athar
-  VERSION = "0.3.2"
+  VERSION = "0.3.3"
 end

data/lib/athar.rb

@@ -55,6 +55,19 @@ module Athar
     def without_capture(...)
       Context.without_capture(...)
     end
+
+    # The connection both audit tables share. The install migration creates
+    # `athar_deletions` and `athar_table_events` together, and the dashboard
+    # composes them via UNION — so they must live on a single physical
+    # connection. Centralized here so multi-DB hosts can route both via
+    # `Athar::Deletion.connects_to(...)` and the gem follows automatically.
+    def audit_connection
+      Deletion.connection
+    end
+
+    def audit_db_config
+      Deletion.connection_db_config
+    end
   end
 end
 

data/lib/generators/athar/model/model_generator.rb

@@ -441,7 +441,7 @@ module Athar
                                                       "athar_mask_#{mask}"
                                                     ])
 
-        !ActiveRecord::Base.connection.select_value(sql).nil?
+        !Athar.audit_connection.select_value(sql).nil?
       rescue StandardError
         # If we can't reach the DB, fall back to false. The trigger install
         # itself will fail loudly later if the function truly doesn't exist.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: athar
 version: !ruby/object:Gem::Version
-  version: 0.3.2
+  version: 0.3.3
 platform: ruby
 authors:
 - Ali Hamdi Ali Fadel