mat_views 0.1.2 → 0.3.0

data/lib/mat_views/services/base_service.rb

@@ -8,7 +8,7 @@
 module MatViews
   module Services
     ##
-    # Base class for service objects that operate on PostgreSQL materialized
+    # Base class for service objects that operate on PostgreSQL materialised
     # views (create/refresh/delete, schema discovery, quoting, and common
     # response helpers).
     #
@@ -19,28 +19,152 @@ module MatViews
     #
     # @example Subclassing BaseService
     #   class MyService < MatViews::Services::BaseService
-    #     def run
-    #       return err("missing view") unless view_exists?
-    #       # perform work...
-    #       ok(:updated, payload: { view: "#{schema}.#{rel}" })
-    #     rescue => e
-    #       error_response(e, meta: { op: "my_service" })
+    #     private
+    #     def assign_request
+    #     # assign @request hash keys
+    #     end
+    #
+    #     def prepare
+    #     # perform pre-flight checks, raise StandardError on failure
+    #     end
+    #
+    #     def _run
+    #     # perform the operation, return a MatViews::ServiceResponse
     #     end
     #   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.
+      # @return [MatViews::MatViewDefinition] The target materialised 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
+
+      ##
+      # wrap in transaction
+      # @return [Boolean]
+      attr_accessor :use_transaction
+
       ##
       # @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 = {}
+        @use_transaction = true
+      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 call
+        if use_transaction
+          ActiveRecord::Base.transaction { run_core }
+        else
+          run_core
+        end
+      rescue StandardError => e
+        # finish pending transaction if any
+        # eg: current transaction is aborted, commands ignored until end of transaction block
+        error_response(e)
       end
 
       private
 
+      ##
+      # Core run logic without transaction wrapper.
+      # Called by {#call}.
+      #
+      # @api private
+      # @return [MatViews::ServiceResponse]
+      def run_core
+        assign_request
+        prepare
+        _run
+      end
+
+      ##
+      # Assign the request parameters.
+      # Called by {#call} 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 {#call} 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 {#call} 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 +180,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
 
       ##
@@ -100,7 +224,7 @@ module MatViews
       # ────────────────────────────────────────────────────────────────
 
       ##
-      # Whether the materialized view exists for the resolved `schema` and `rel`.
+      # Whether the materialised view exists for the resolved `schema` and `rel`.
       #
       # @api private
       # @return [Boolean]
@@ -125,7 +249,7 @@ module MatViews
       end
 
       ##
-      # Drop the materialized view if it exists (idempotent).
+      # Drop the materialised view if it exists (idempotent).
       #
       # @api private
       # @return [void]
@@ -204,42 +328,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,30 +394,77 @@ 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
 
       ##
-      # Validate SQL starts with SELECT.
+      # Check for any UNIQUE index on the materialised view, required by CONCURRENTLY.
       #
       # @api private
       # @return [Boolean]
       #
-      def valid_sql?
-        definition.sql.to_s.strip.upcase.start_with?('SELECT')
+      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
+      # ────────────────────────────────────────────────────────────────
+
       ##
-      # Validate that the view name is a sane PostgreSQL identifier.
+      # Compute row count based on the configured strategy.
       #
       # @api private
-      # @return [Boolean]
-      def valid_name?
-        /\A[a-zA-Z_][a-zA-Z0-9_]*\z/.match?(definition.name.to_s)
+      # @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 materialised view.
+      #
+      # @api private
+      # @return [Integer]
+      #
+      def exact_rows_count
+        conn.select_value("SELECT COUNT(*) FROM #{qualified_rel}").to_i
       end
     end
   end

data/lib/mat_views/services/check_matview_exists.rb

@@ -0,0 +1,76 @@
+# 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.
+
+module MatViews
+  module Services
+    # MatViews::Services::CheckMatviewExists
+    # --------------------------------------
+    # Service object that checks whether the underlying PostgreSQL **materialised view**
+    # for a given {MatViews::MatViewDefinition} currently exists.
+    #
+    # ### Contract
+    # - Inherits from {MatViews::Services::BaseService}.
+    # - Uses BaseService helpers such as `definition`, `view_exists?`,
+    #   `ok`, `raise_err`, and the `request`/`response` accessors.
+    # - The public entrypoint is `#call` (defined in BaseService), which will call the
+    #   private lifecycle hooks here: {#prepare}, {#assign_request}, and {#_run}.
+    #
+    # ### Result
+    # - On success: status `:ok`, with `response: { exists: true|false }`.
+    # - On validation failure (bad view name): raises via {BaseService#raise_err}.
+    #
+    # @example Check if a materialised view exists
+    #   defn = MatViews::MatViewDefinition.find(1)
+    #   res  = MatViews::Services::CheckMatviewExists.new(defn).call
+    #   if res.success?
+    #     puts res.response[:exists] ? "Exists" : "Missing"
+    #   else
+    #     warn res.error
+    #   end
+    #
+    # @see MatViews::Services::BaseService
+    # @see MatViews::MatViewDefinition
+    #
+    class CheckMatviewExists < BaseService
+      private
+
+      # Core execution step (invoked by BaseService#call).
+      #
+      # @api private
+      #
+      # Sets {#response} to `{ exists: Boolean }` and marks the service as ok.
+      #
+      # @return [void]
+      def _run
+        self.response = { exists: view_exists? }
+        ok(:ok)
+      end
+
+      # Validation step (invoked by BaseService#call before execution).
+      #
+      # @api private
+      #
+      # Empty for this service as no other preparation is needed.
+      #
+      # @return [void]
+      def prepare; end
+
+      # Request initialization (invoked by BaseService#call).
+      #
+      # @api private
+      #
+      # Establishes a canonical, immutable snapshot of the input request
+      # for logging/inspection purposes. This service does not require inputs,
+      # so it assigns an empty Hash.
+      #
+      # @return [void]
+      def assign_request
+        self.request = {}
+      end
+    end
+  end
+end

data/lib/mat_views/services/concurrent_refresh.rb

@@ -13,41 +13,33 @@ module MatViews
     #   `REFRESH MATERIALIZED VIEW CONCURRENTLY <schema>.<rel>`
     #
     # 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}.
+    # UNIQUE index** on the materialised view (a PostgreSQL constraint).
     #
-    # 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)
-    #   response = svc.run
+    #   svc = MatViews::Services::ConcurrentRefresh.new(definition, **options)
+    #   response = svc.call
     #   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
+        super
+        @use_transaction = false
       end
 
+      private
+
       ##
       # Execute the concurrent refresh.
       #
@@ -55,122 +47,47 @@ 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
-      end
-
-      # ────────────────────────────────────────────────────────────────
-      # helpers: validation / schema / pg introspection
-      # (mirrors RegularRefresh for consistency)
-      # ────────────────────────────────────────────────────────────────
-
-      ##
-      # 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
+        ok(:updated)
       end
 
-      # ────────────────────────────────────────────────────────────────
-      # rows counting (same as RegularRefresh)
-      # ────────────────────────────────────────────────────────────────
-
       ##
-      # Compute row count based on the configured strategy.
+      # Assign the request parameters.
+      # Called by {#call} before {#prepare}.
+      # Sets `concurrent: true` in the request hash.
       #
       # @api private
-      # @return [Integer, nil]
+      # @return [void]
       #
-      def fetch_rows_count
-        case row_count_strategy
-        when :estimated then estimated_rows_count
-        when :exact     then exact_rows_count
-        end
+      def assign_request
+        self.request = { row_count_strategy: row_count_strategy, concurrent: true }
       end
 
       ##
-      # Fast, approximate row count via `pg_class.reltuples`.
+      # Validation step (invoked by BaseService#call before execution).
       #
       # @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("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