mat_views 0.1.2 → 0.2.0

data/lib/ext/exception.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+# Copyright Codevedas Inc. 2025-present
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+
+# Extend the Exception class to add a method for serializing error details.
+class Exception
+  # Serialize the exception into a hash with message, class, and backtrace.
+  #
+  # @return [Hash] serialized error details
+  def mv_serialize_error
+    {
+      message: message,
+      class: self.class.name,
+      backtrace: Array(backtrace)
+    }
+  end
+end

data/lib/generators/mat_views/install/templates/create_mat_view_runs.rb

@@ -23,8 +23,8 @@ class CreateMatViewRuns < ActiveRecord::Migration[7.1]
       t.datetime :started_at, comment: 'Timestamp when the operation started'
       t.datetime :finished_at, comment: 'Timestamp when the operation finished'
       t.integer  :duration_ms, comment: 'Duration of the operation in milliseconds'
-      t.text     :error, comment: 'Error message if the operation failed'
-      t.jsonb    :meta, null: false, default: {}, comment: 'Additional metadata about the run, such as job ID, row count or parameters'
+      t.jsonb :error, comment: 'Error details if the operation failed. :message, :class, :backtrace'
+      t.jsonb :meta, null: false, default: {}, comment: 'Additional metadata about the run, such as job ID, row count or parameters'
 
       t.timestamps
     end

data/lib/mat_views/jobs/adapter.rb

@@ -58,19 +58,22 @@ module MatViews
       # @raise [ArgumentError] if the configured adapter is not recognized.
       #
       def self.enqueue(job_class, queue:, args: [])
-        case MatViews.configuration.job_adapter
+        queue_str = queue.to_s
+        job_adapter = MatViews.configuration.job_adapter
+
+        case job_adapter
         when :active_job
-          job_class.set(queue: queue.to_s).perform_later(*args)
+          job_class.set(queue: queue_str).perform_later(*args)
         when :sidekiq
           Sidekiq::Client.push(
             'class' => job_class.name,
-            'queue' => queue.to_s,
+            'queue' => queue_str,
             'args' => args
           )
         when :resque
-          Resque.enqueue_to(queue.to_s, job_class, *args)
+          Resque.enqueue_to(queue_str, job_class, *args)
         else
-          raise ArgumentError, "Unknown job adapter: #{MatViews.configuration.job_adapter.inspect}"
+          raise ArgumentError, "Unknown job adapter: #{job_adapter.inspect}"
         end
       end
     end

data/lib/mat_views/service_response.rb

@@ -10,16 +10,19 @@ module MatViews
   # Encapsulates the result of a service operation within MatViews.
   #
   # Provides a consistent contract for all services by standardizing:
-  # - `status`: Symbol representing outcome (`:ok`, `:created`, `:updated`, `:noop`,
+  # - `status`: Symbol representing outcome (`:ok`, `:created`, `:updated`,
   #   `:skipped`, `:deleted`, `:error`)
-  # - `payload`: Arbitrary structured data returned by the service
-  # - `error`: Exception object or message if an error occurred
-  # - `meta`: Additional metadata such as SQL statements, timing, or strategies
+  # - `request`: Request detailed that service was invoked with
+  # - `response`: Response detailed that service returned, nil with :error status
+  # - `error`: Exception or error message, with :error status
+  #    - `message`: String description of the error
+  #    - `class`: Exception class name
+  #    - `backtrace`: Array of strings
   #
   # @example Successful response
   #   MatViews::ServiceResponse.new(
   #     status: :updated,
-  #     payload: { view: "public.users_mv" }
+  #     response: { ... }
   #   )
   #
   # @example Error response
@@ -29,32 +32,44 @@ module MatViews
   #   )
   #
   class ServiceResponse
-    attr_reader :status, :payload, :error, :meta
+    attr_reader :status, :request, :error, :response
+
+    # acceptable status values
+    ACCEPTABLE_STATES = %i[ok created updated skipped deleted error].freeze
+
+    # statuses indicating success
+    OK_STATES = %i[ok created updated skipped deleted].freeze
+
+    # statuses indicating error
+    ERROR_STATES = %i[error].freeze
 
     # @param status [Symbol] the outcome status
-    # @param payload [Hash] optional data payload
+    # @param request [Hash] request details
+    # @param response [Hash] response details
     # @param error [Exception, String, nil] error details if applicable
-    # @param meta [Hash] additional metadata
-    def initialize(status:, payload: {}, error: nil, meta: {})
+    def initialize(status:, request: {}, response: {}, error: nil)
+      raise ArgumentError, 'status is required' unless ACCEPTABLE_STATES.include?(status&.to_sym)
+      raise ArgumentError, 'error must be an Exception object' if error && !error.is_a?(Exception)
+
       @status = status.to_sym
-      @payload = payload
-      @error = error
-      @meta = meta
+      @request = request
+      @response = response
+      @error = error&.mv_serialize_error
     end
 
     # @return [Boolean] whether the response represents a success
     def success?
-      !error? && %i[ok created updated noop skipped deleted].include?(status)
+      OK_STATES.include?(status)
     end
 
     # @return [Boolean] whether the response represents an error
     def error?
-      !error.nil? || status == :error
+      ERROR_STATES.include?(status)
     end
 
     # @return [Hash] hash representation of the response
     def to_h
-      { status:, payload:, error:, meta: }
+      { status:, request:, response:, error: }.compact
     end
   end
 end

data/lib/mat_views/services/base_service.rb

@@ -29,18 +29,115 @@ module MatViews
     #   end
     #
     class BaseService
+      # Constant indicating unknown row count
+      UNKNOWN_ROW_COUNT = -1
+
+      # Allowed row count strategies
+      ALLOWED_ROW_STRATEGIES = %i[none estimated exact].freeze
+
+      # Default row count strategy
+      DEFAULT_ROW_STRATEGY = :estimated
+
+      # Default strategy when nil or unrecognized value is given
+      DEFAULT_NIL_STRATEGY = :none
+
       ##
       # @return [MatViews::MatViewDefinition] The target materialized view definition.
       attr_reader :definition
 
+      ##
+      # Row count strategy (`:estimated`, `:exact`, `nil`).
+      #
+      # @return [Symbol, nil]
+      attr_reader :row_count_strategy
+
+      ##
+      # request hash to be returned in service response
+      # @return [Hash]
+      attr_accessor :request
+
+      ##
+      # response hash to be returned in service response
+      # @return [Hash]
+      attr_accessor :response
+
       ##
       # @param definition [MatViews::MatViewDefinition]
-      def initialize(definition)
+      # @param row_count_strategy [Symbol, nil] one of `:estimated`, `:exact`, or `nil` (default: `:estimated`)
+      #
+      def initialize(definition, row_count_strategy: DEFAULT_ROW_STRATEGY)
         @definition = definition
+        @row_count_strategy = extract_row_strategy(row_count_strategy)
+        @request = {}
+        @response = {}
+      end
+
+      ##
+      # Execute the service operation.
+      #
+      # Calls {#assign_request}, {#prepare} and {#_run} in order.
+      #
+      # Concrete subclasses must implement these methods.
+      #
+      # @return [MatViews::ServiceResponse]
+      # @raise [NotImplementedError] if not implemented in subclass
+      def run
+        assign_request
+        prepare
+        _run
+      rescue StandardError => e
+        error_response(e)
       end
 
       private
 
+      ##
+      # Assign the request parameters.
+      # Called by {#run} before {#prepare}.
+      #
+      # Must be implemented in concrete subclasses.
+      #
+      # @api private
+      # @return [void]
+      # @raise [NotImplementedError] if not implemented in subclass
+      #
+      def assign_request
+        raise NotImplementedError, "Must implement #{self.class}##{__method__}"
+      end
+
+      ##
+      # Perform pre-flight checks.
+      # Called by {#run} after {#assign_request}.
+      #
+      # Must be implemented in concrete subclasses.
+      #
+      # @api private
+      # @return [nil] on success
+      # @raise [StandardError] on failure
+      # @raise [NotImplementedError] if not implemented in subclass
+      #
+      def prepare
+        raise NotImplementedError, "Must implement #{self.class}##{__method__}"
+      end
+
+      ##
+      # Execute the service operation.
+      # Called by {#run} after {#prepare}.
+      #
+      # Must be implemented in concrete subclasses.
+      #
+      # @api private
+      # @return [MatViews::ServiceResponse]
+      # @raise [NotImplementedError] if not implemented in subclass
+      #
+      def _run
+        raise NotImplementedError, "Must implement #{self.class}##{__method__}"
+      end
+
+      def extract_row_strategy(value)
+        ALLOWED_ROW_STRATEGIES.include?(value) ? value : DEFAULT_NIL_STRATEGY
+      end
+
       # ────────────────────────────────────────────────────────────────
       # Schema / resolution helpers
       # ────────────────────────────────────────────────────────────────
@@ -56,9 +153,9 @@ module MatViews
       #
       def first_existing_schema
         raw_path   = conn.schema_search_path.presence || 'public'
-        candidates = raw_path.split(',').filter_map { |t| resolve_schema_token(t.strip) }
+        candidates = raw_path.split(',').filter_map { |token| resolve_schema_token(token.strip) }
         candidates << 'public' unless candidates.include?('public')
-        candidates.find { |s| schema_exists?(s) } || 'public'
+        candidates.find { |schema_str| schema_exists?(schema_str) } || 'public'
       end
 
       ##
@@ -204,42 +301,34 @@ module MatViews
       # Build a success response.
       #
       # @api private
-      # @param status [Symbol] e.g., `:ok`, `:created`, `:updated`, `:noop`
-      # @param payload [Hash] optional payload
-      # @param meta [Hash] optional metadata
+      # @param status [Symbol] e.g., `:ok`, `:created`, `:updated`, `:skipped`, `:deleted`
       # @return [MatViews::ServiceResponse]
       #
-      def ok(status, payload: {}, meta: {})
-        MatViews::ServiceResponse.new(status: status, payload: payload, meta: meta)
+      def ok(status)
+        MatViews::ServiceResponse.new(status:, request:, response:)
       end
 
       ##
-      # Build an error response with a message.
+      # Raise a StandardError with the given message.
       #
       # @api private
       # @param msg [String]
-      # @return [MatViews::ServiceResponse]
+      # @return [void]
+      # @raise [StandardError] with `msg`
       #
-      def err(msg)
-        MatViews::ServiceResponse.new(status: :error, error: msg)
+      def raise_err(msg)
+        raise StandardError, msg
       end
 
       ##
       # Build an error response from an exception, including backtrace.
       #
       # @api private
-      # @param exception [Exception]
-      # @param payload [Hash]
-      # @param meta [Hash]
+      # @param error [Exception]
       # @return [MatViews::ServiceResponse]
       #
-      def error_response(exception, payload: {}, meta: {})
-        MatViews::ServiceResponse.new(
-          status: :error,
-          error: "#{exception.class}: #{exception.message}",
-          payload: payload,
-          meta: { backtrace: Array(exception.backtrace), **meta }
-        )
+      def error_response(error)
+        MatViews::ServiceResponse.new(status: :error, error:, request:, response:)
       end
 
       # ────────────────────────────────────────────────────────────────
@@ -278,9 +367,10 @@ module MatViews
       #
       def pg_idle?
         rc = conn.raw_connection
-        status = rc.respond_to?(:transaction_status) ? rc.transaction_status : nil
+        return true unless rc.respond_to?(:transaction_status)
+
         # Only use CONCURRENTLY outside any tx/savepoint.
-        status.nil? || status == PG::PQTRANS_IDLE
+        rc.transaction_status == PG::PQTRANS_IDLE
       rescue StandardError
         false
       end
@@ -303,6 +393,71 @@ module MatViews
       def valid_name?
         /\A[a-zA-Z_][a-zA-Z0-9_]*\z/.match?(definition.name.to_s)
       end
+
+      ##
+      # Check for any UNIQUE index on the materialized view, required by CONCURRENTLY.
+      #
+      # @api private
+      # @return [Boolean]
+      #
+      def unique_index_exists?
+        conn.select_value(<<~SQL).to_i.positive?
+          SELECT COUNT(*)
+          FROM pg_index i
+          JOIN pg_class c ON c.oid = i.indrelid
+          JOIN pg_namespace n ON n.oid = c.relnamespace
+          WHERE n.nspname = #{conn.quote(schema)}
+            AND c.relname = #{conn.quote(rel)}
+            AND i.indisunique = TRUE
+        SQL
+      end
+
+      # ────────────────────────────────────────────────────────────────
+      # rows counting
+      # ────────────────────────────────────────────────────────────────
+
+      ##
+      # Compute row count based on the configured strategy.
+      #
+      # @api private
+      # @return [Integer, nil]
+      #
+      def fetch_rows_count
+        case row_count_strategy
+        when :estimated then estimated_rows_count
+        when :exact     then exact_rows_count
+        else
+          UNKNOWN_ROW_COUNT
+        end
+      end
+
+      ##
+      # Fast, approximate row count via `pg_class.reltuples`.
+      #
+      # @api private
+      # @return [Integer]
+      #
+      def estimated_rows_count
+        conn.select_value(<<~SQL).to_i
+          SELECT COALESCE(c.reltuples::bigint, 0)
+          FROM pg_class c
+          JOIN pg_namespace n ON n.oid = c.relnamespace
+          WHERE c.relkind IN ('m','r','p')
+            AND n.nspname = #{conn.quote(schema)}
+            AND c.relname = #{conn.quote(rel)}
+          LIMIT 1
+        SQL
+      end
+
+      ##
+      # Accurate row count using `COUNT(*)` on the materialized view.
+      #
+      # @api private
+      # @return [Integer]
+      #
+      def exact_rows_count
+        conn.select_value("SELECT COUNT(*) FROM #{qualified_rel}").to_i
+      end
     end
   end
 end

data/lib/mat_views/services/concurrent_refresh.rb

@@ -14,39 +14,26 @@ module MatViews
     #
     # It keeps the view readable during refresh, but **requires at least one
     # UNIQUE index** on the materialized view (a PostgreSQL constraint).
-    # Returns a {MatViews::ServiceResponse}.
     #
-    # Row-count reporting is optional and controlled by `row_count_strategy`:
-    # - `:estimated` — fast/approx via `pg_class.reltuples`
-    # - `:exact` — accurate `COUNT(*)`
-    # - `nil` (or any unrecognized value) — skip counting
+    # Options:
+    # - `row_count_strategy:` (Symbol, default: :none) → one of `:estimated`, `:exact`, or `:none or nil` to control row count reporting
+    #
+    # Returns a {MatViews::ServiceResponse}
     #
     # @see MatViews::Services::RegularRefresh
     # @see MatViews::Services::SwapRefresh
     #
     # @example Direct usage
-    #   svc = MatViews::Services::ConcurrentRefresh.new(definition, row_count_strategy: :exact)
+    #   svc = MatViews::Services::ConcurrentRefresh.new(definition, **options)
     #   response = svc.run
     #   response.success? # => true/false
     #
-    # @example Via job selection (within RefreshViewJob)
-    #   # When definition.refresh_strategy == "concurrent"
-    #   MatViews::RefreshViewJob.perform_later(definition.id, :estimated)
+    # @example via job, this is the typical usage and will create a run record in the DB
+    #   When definition.refresh_strategy == "concurrent"
+    #   MatViews::Jobs::Adapter.enqueue(MatViews::Services::RefreshViewJob, definition.id, **options)
     #
     class ConcurrentRefresh < BaseService
-      ##
-      # Strategy for computing row count after refresh.
-      #
-      # @return [Symbol, nil] one of `:estimated`, `:exact`, or `nil`
-      attr_reader :row_count_strategy
-
-      ##
-      # @param definition [MatViews::MatViewDefinition]
-      # @param row_count_strategy [Symbol, nil] `:estimated` (default), `:exact`, or `nil`
-      def initialize(definition, row_count_strategy: :estimated)
-        super(definition)
-        @row_count_strategy = row_count_strategy
-      end
+      private
 
       ##
       # Execute the concurrent refresh.
@@ -55,122 +42,49 @@ module MatViews
       # If validation fails, returns an error {MatViews::ServiceResponse}.
       #
       # @return [MatViews::ServiceResponse]
-      #   - `status: :updated` with payload `{ view:, row_count? }` on success
-      #   - `status: :error` with `error` on failure
-      #
-      # @raise [StandardError] bubbled after being wrapped into {#error_response}
-      #
-      def run
-        prep = prepare!
-        return prep if prep
-
+      #   - `status: :updated` on success, with `response` containing:
+      #     - `view` - the qualified view name
+      #     - `row_count_before` - if requested and available
+      #     - `row_count_after` - if requested and available
+      #   - `status: :error` with `error` on failure, with `error` containing:
+      #     - serlialized exception class, message, and backtrace in a hash
+      def _run
         sql = "REFRESH MATERIALIZED VIEW CONCURRENTLY #{qualified_rel}"
+        self.response = { view: "#{schema}.#{rel}", sql: [sql] }
 
+        response[:row_count_before] = fetch_rows_count
         conn.execute(sql)
+        response[:row_count_after] = fetch_rows_count
 
-        payload = { view: "#{schema}.#{rel}" }
-        payload[:row_count] = fetch_rows_count if row_count_strategy.present?
-
-        ok(:updated,
-           payload: payload,
-           meta: { sql: sql, row_count_strategy: row_count_strategy, concurrent: true })
-      rescue PG::ObjectInUse => e
-        # Common lock/contention error during concurrent refreshes.
-        error_response(e,
-                       meta: { sql: sql, row_count_strategy: row_count_strategy, concurrent: true },
-                       payload: { view: "#{schema}.#{rel}" })
-      rescue StandardError => e
-        error_response(e,
-                       meta: { sql: sql, backtrace: Array(e.backtrace), row_count_strategy: row_count_strategy, concurrent: true },
-                       payload: { view: "#{schema}.#{rel}" })
-      end
-
-      private
-
-      # ────────────────────────────────────────────────────────────────
-      # internal
-      # ────────────────────────────────────────────────────────────────
-
-      ##
-      # Perform pre-flight checks.
-      #
-      # @api private
-      # @return [MatViews::ServiceResponse, nil] error response or `nil` if OK
-      #
-      def prepare!
-        return err("Invalid view name format: #{definition.name.inspect}") unless valid_name?
-        return err("Materialized view #{schema}.#{rel} does not exist") unless view_exists?
-        return err("Materialized view #{schema}.#{rel} must have a unique index for concurrent refresh") unless unique_index_exists?
-
-        nil
+        ok(:updated)
       end
 
-      # ────────────────────────────────────────────────────────────────
-      # helpers: validation / schema / pg introspection
-      # (mirrors RegularRefresh for consistency)
-      # ────────────────────────────────────────────────────────────────
-
       ##
-      # Check for any UNIQUE index on the materialized view, required by CONCURRENTLY.
+      # Assign the request parameters.
+      # Called by {#run} before {#prepare}.
+      # Sets `concurrent: true` in the request hash.
       #
       # @api private
-      # @return [Boolean]
+      # @return [void]
       #
-      def unique_index_exists?
-        conn.select_value(<<~SQL).to_i.positive?
-          SELECT COUNT(*)
-          FROM pg_index i
-          JOIN pg_class c ON c.oid = i.indrelid
-          JOIN pg_namespace n ON n.oid = c.relnamespace
-          WHERE n.nspname = #{conn.quote(schema)}
-            AND c.relname = #{conn.quote(rel)}
-            AND i.indisunique = TRUE
-        SQL
+      def assign_request
+        self.request = { row_count_strategy: row_count_strategy, concurrent: true }
       end
 
-      # ────────────────────────────────────────────────────────────────
-      # rows counting (same as RegularRefresh)
-      # ────────────────────────────────────────────────────────────────
-
       ##
-      # Compute row count based on the configured strategy.
-      #
-      # @api private
-      # @return [Integer, nil]
-      #
-      def fetch_rows_count
-        case row_count_strategy
-        when :estimated then estimated_rows_count
-        when :exact     then exact_rows_count
-        end
-      end
-
-      ##
-      # Fast, approximate row count via `pg_class.reltuples`.
+      # Perform pre-flight checks.
+      # Called by {#run} after {#assign_request}.
       #
       # @api private
-      # @return [Integer]
+      # @return [nil] on success
+      # @raise [StandardError] on failure
       #
-      def estimated_rows_count
-        conn.select_value(<<~SQL).to_i
-          SELECT COALESCE(c.reltuples::bigint, 0)
-          FROM pg_class c
-          JOIN pg_namespace n ON n.oid = c.relnamespace
-          WHERE c.relkind IN ('m','r','p')
-            AND n.nspname = #{conn.quote(schema)}
-            AND c.relname = #{conn.quote(rel)}
-          LIMIT 1
-        SQL
-      end
+      def prepare
+        raise_err("Invalid view name format: #{definition.name.inspect}") unless valid_name?
+        raise_err("Materialized view #{schema}.#{rel} does not exist") unless view_exists?
+        raise_err("Materialized view #{schema}.#{rel} must have a unique index for concurrent refresh") unless unique_index_exists?
 
-      ##
-      # Accurate row count using `COUNT(*)` on the materialized view.
-      #
-      # @api private
-      # @return [Integer]
-      #
-      def exact_rows_count
-        conn.select_value("SELECT COUNT(*) FROM #{qualified_rel}").to_i
+        nil
       end
     end
   end