mat_views 0.1.2 → 0.3.0

data/lib/mat_views/services/create_view.rb

@@ -8,25 +8,32 @@
 module MatViews
   module Services
     ##
-    # Service responsible for creating PostgreSQL materialized views.
+    # Service responsible for creating PostgreSQL materialised views.
     #
     # The service validates the view definition, handles existence checks,
     # executes `CREATE MATERIALIZED VIEW ... WITH DATA`, and, when the
     # refresh strategy is `:concurrent`, ensures a supporting UNIQUE index.
     #
-    # Returns a {MatViews::ServiceResponse}.
+    # Options:
+    # - `force:` (Boolean, default: false) → drop and recreate if the view already exists
+    # - `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::ConcurrentRefresh
     #
     # @example Create a new matview (no force)
-    #   svc = MatViews::Services::CreateView.new(defn)
-    #   response = svc.run
-    #   response.status # => :created or :noop
+    #   svc = MatViews::Services::CreateView.new(defn, **options)
+    #   response = svc.call
+    #   response.status # => :created or :skipped
     #
     # @example Force recreate an existing matview
     #   svc = MatViews::Services::CreateView.new(defn, force: true)
-    #   svc.run
+    #   svc.call
+    #
+    # @example via job, this is the typical usage and will create a run record in the DB
+    #   MatViews::Jobs::Adapter.enqueue(MatViews::Services::CreateViewJob, definition.id, **options)
     #
     class CreateView < BaseService
       ##
@@ -38,91 +45,101 @@ module MatViews
       ##
       # @param definition [MatViews::MatViewDefinition]
       # @param force [Boolean] Whether to drop+recreate an existing matview.
-      def initialize(definition, force: false)
-        super(definition)
-        @force = !!force
+      # @param row_count_strategy [Symbol, nil] one of `:estimated`, `:exact`, or `nil` (default: `:estimated`)
+      #
+      # Supports optional row count strategies:
+      # - `:estimated` → approximate, using `pg_class.reltuples`
+      # - `:exact` → accurate, using `COUNT(*)`
+      # - `nil` → skip row count
+      def initialize(definition, force: false, row_count_strategy: :estimated)
+        super(definition, row_count_strategy: row_count_strategy)
+        @force = force
+        # Transactions are disabled if unique_index_columns are present because
+        # PostgreSQL does not allow creating a UNIQUE INDEX CONCURRENTLY inside a transaction block.
+        # If a unique index is required (for concurrent refresh), we must avoid wrapping the operation in a transaction.
+        @use_transaction = definition.unique_index_columns.none?
       end
 
+      private
+
       ##
       # Execute the create operation.
       #
       # - Validates name, SQL, and concurrent-index requirements.
-      # - Handles existing view: noop (default) or drop+recreate (`force: true`).
-      # - Creates the materialized view WITH DATA.
+      # - Handles existing view: skipped (default) or drop+recreate (`force: true`).
+      # - Creates the materialised view WITH DATA.
       # - Creates a UNIQUE index if refresh strategy is concurrent.
       #
-      # @return [MatViews::ServiceResponse]
-      #   - `:created` on success (payload includes `view` and `created_indexes`)
-      #   - `:noop` if the view already exists and `force: false`
-      #   - `:error` if validation or execution fails
+      # @api private
       #
-      def run
-        prep = prepare!
-        return prep if prep # error response
-
-        # If exists, either noop or drop+recreate
-        existed = handle_existing!
+      # @return [MatViews::ServiceResponse]
+      #   - `status: :created or :skipped` 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 = create_with_data_sql
+        self.response = { view: "#{schema}.#{rel}", sql: [sql] }
+        # If exists, either skipped or drop+recreate
+        existed = handle_existing
         return existed if existed.is_a?(MatViews::ServiceResponse)
 
-        # Always create WITH DATA for a fresh view
-        create_with_data
+        response[:row_count_before] = UNKNOWN_ROW_COUNT
+        conn.execute(sql)
+        response[:row_count_after] = fetch_rows_count
 
         # For concurrent strategy, ensure the unique index so future
         # REFRESH MATERIALIZED VIEW CONCURRENTLY is allowed.
-        index_info = ensure_unique_index_if_needed
-
-        ok(:created, payload: { view: qualified_rel, **index_info })
-      rescue StandardError => e
-        error_response(
-          e,
-          payload: { view: qualified_rel },
-          meta: { sql: sql, force: force }
-        )
-      end
-
-      private
+        response.merge!(ensure_unique_index_if_needed)
 
-      # ────────────────────────────────────────────────────────────────
-      # internal
-      # ────────────────────────────────────────────────────────────────
+        ok(:created)
+      end
 
       ##
-      # Validate name, SQL, and concurrent strategy requirements.
+      # Validation step (invoked by BaseService#call before execution).
+      # Empty for this service as no other preparation is needed.
       #
       # @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('SQL must start with SELECT') unless valid_sql?
-        return err('refresh_strategy=concurrent requires unique_index_columns (non-empty)') if strategy == 'concurrent' && cols.empty?
+      # @return [void]
+      #
+      def prepare; end
 
-        nil
+      ##
+      # Assign the request parameters.
+      # Called by {#call} before {#prepare}.
+      #
+      # @api private
+      # @return [void]
+      #
+      def assign_request
+        self.request = { row_count_strategy: row_count_strategy, force: }
       end
 
       ##
-      # Handle existing matview: return noop if not forcing, or drop if forcing.
+      # Handle existing matview: return skipped if not forcing, or drop if forcing.
       #
       # @api private
       # @return [MatViews::ServiceResponse, nil]
       #
-      def handle_existing!
+      def handle_existing
         return nil unless view_exists?
 
-        return MatViews::ServiceResponse.new(status: :noop) unless force
+        return ok(:skipped) unless force
 
         drop_view
         nil
       end
 
       ##
-      # Execute the CREATE MATERIALIZED VIEW WITH DATA statement.
-      #
+      # SQL for `CREATE MATERIALIZED VIEW ... WITH DATA`.
       # @api private
-      # @return [void]
+      # @return [String]
       #
-      def create_with_data
-        conn.execute(<<~SQL)
+      def create_with_data_sql
+        <<~SQL
           CREATE MATERIALIZED VIEW #{qualified_rel} AS
           #{sql}
           WITH DATA
@@ -147,9 +164,9 @@ module MatViews
         concurrently = pg_idle?
         conn.execute(<<~SQL)
           CREATE UNIQUE INDEX #{'CONCURRENTLY ' if concurrently}#{quote_table_name(idx_name)}
-          ON #{qualified_rel} (#{cols.map { |c| quote_column_name(c) }.join(', ')})
+          ON #{qualified_rel} (#{cols.map { |col| quote_column_name(col) }.join(', ')})
         SQL
-        { created_indexes: [idx_name] }
+        { created_indexes: [idx_name], row_count_before: UNKNOWN_ROW_COUNT, row_count_after: fetch_rows_count }
       end
     end
   end

data/lib/mat_views/services/delete_view.rb

@@ -8,26 +8,26 @@
 module MatViews
   module Services
     ##
-    # Service that safely drops a PostgreSQL materialized view.
+    # Service that safely drops a PostgreSQL materialised view.
     #
     # Options:
-    # - `if_exists:` (Boolean, default: true) → idempotent drop (skip if absent)
-    # - `cascade:`   (Boolean, default: false) → use CASCADE instead of RESTRICT
+    # - `cascade:` (Boolean, default: false) → drop with CASCADE instead of RESTRICT
+    # - `row_count_strategy:` (Symbol, default: :none) → one of `:estimated`, `:exact`, or `:none or nil` to control row count reporting
     #
-    # Returns a {MatViews::ServiceResponse} from {MatViews::Services::BaseService}:
-    # - `ok(:deleted, ...)` when dropped successfully
-    # - `ok(:skipped, ...)` when absent and `if_exists: true`
-    # - `err("...")` or `error_response(...)` on validation or execution error
+    # Returns a {MatViews::ServiceResponse}
     #
     # @see MatViews::DeleteViewJob
     # @see MatViews::MatViewRun
     #
     # @example Drop a view if it exists
-    #   svc = MatViews::Services::DeleteView.new(defn)
-    #   svc.run
+    #   svc = MatViews::Services::DeleteView.new(defn, **options)
+    #   svc.call
     #
     # @example Force drop with CASCADE
-    #   MatViews::Services::DeleteView.new(defn, cascade: true).run
+    #   MatViews::Services::DeleteView.new(defn, cascade: true).call
+    #
+    # @example via job, this is the typical usage and will create a run record in the DB
+    #   MatViews::Jobs::Adapter.enqueue(MatViews::Services::DeleteViewJob, definition.id, **options)
     #
     class DeleteView < BaseService
       ##
@@ -36,122 +36,73 @@ module MatViews
       # @return [Boolean]
       attr_reader :cascade
 
-      ##
-      # Whether to allow idempotent skipping if view is absent (default: true).
-      #
-      # @return [Boolean]
-      attr_reader :if_exists
-
       ##
       # @param definition [MatViews::MatViewDefinition]
       # @param cascade [Boolean] drop with CASCADE instead of RESTRICT
-      # @param if_exists [Boolean] skip if view not present
-      def initialize(definition, cascade: false, if_exists: true)
-        super(definition)
-        @cascade   = cascade ? true : false
-        @if_exists = if_exists ? true : false
+      # @param row_count_strategy [Symbol, nil] one of `:estimated`, `:exact`, or `nil` (default: `:estimated`)
+      def initialize(definition, cascade: false, row_count_strategy: :estimated)
+        super(definition, row_count_strategy: row_count_strategy)
+        @cascade = cascade ? true : false
       end
 
+      private
+
       ##
       # Run the drop operation.
       #
       # Steps:
-      # - Validate name format and (optionally) existence.
-      # - Return `:skipped` if absent and `if_exists` true.
+      # - Validate name format
+      # - return :skipped if absent
       # - Execute DROP MATERIALIZED VIEW.
       #
-      # @return [MatViews::ServiceResponse]
-      #
-      def run
-        prep = prepare!
-        return prep if prep
-
-        res = skip_early_if_absent
-        return res if res
-
-        perform_drop
-      end
-
-      private
-
-      # ────────────────────────────────────────────────────────────────
-      # internal
-      # ────────────────────────────────────────────────────────────────
-
-      ##
-      # Execute the DROP MATERIALIZED VIEW statement.
-      #
-      # @api private
-      # @return [MatViews::ServiceResponse]
-      #
-      def perform_drop
-        conn.execute(sql)
-
-        ok(:deleted,
-           payload: { view: "#{schema}.#{rel}" },
-           meta: { sql: sql, cascade: cascade, if_exists: if_exists })
-      rescue ActiveRecord::StatementInvalid => e
-        msg = "#{e.message} — dependencies exist. Use cascade: true to force drop."
-        error_response(
-          e.class.new(msg),
-          meta: { sql: sql, cascade: cascade, if_exists: if_exists },
-          payload: { view: "#{schema}.#{rel}" }
-        )
-      rescue StandardError => e
-        error_response(
-          e,
-          meta: { sql: sql, cascade: cascade, if_exists: if_exists },
-          payload: { view: "#{schema}.#{rel}" }
-        )
-      end
-
-      ##
-      # Skip early if view is absent and `if_exists` is true.
-      #
       # @api private
-      # @return [MatViews::ServiceResponse, nil]
       #
-      def skip_early_if_absent
-        return nil unless if_exists
-        return nil if view_exists?
-
-        ok(:skipped,
-           payload: { view: "#{schema}.#{rel}" },
-           meta: { sql: nil, cascade: cascade, if_exists: if_exists })
+      # @return [MatViews::ServiceResponse]
+      #   - `status: :deleted or :skipped` 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
+        self.response = { view: "#{schema}.#{rel}", sql: [drop_sql] }
+
+        return ok(:skipped) unless view_exists?
+
+        response[:row_count_before] = fetch_rows_count
+        conn.execute(drop_sql)
+        response[:row_count_after] = UNKNOWN_ROW_COUNT # view is gone
+        ok(:deleted)
       end
 
       ##
-      # Build the SQL DROP statement.
+      # Assign the request parameters.
+      # Called by {#call} before {#prepare}.
+      # Sets `concurrent: true` in the request hash.
       #
       # @api private
-      # @return [String]
+      # @return [void]
       #
-      def sql
-        @sql ||= build_sql
+      def assign_request
+        self.request = { row_count_strategy: row_count_strategy, cascade: cascade }
       end
 
       ##
-      # Validate name and existence depending on options.
+      # Validation step (invoked by BaseService#call before execution).
+      # Empty for this service as no other preparation is needed.
       #
       # @api private
-      # @return [MatViews::ServiceResponse, nil]
       #
-      def prepare!
-        return err("Invalid view name format: #{definition.name.inspect}") unless valid_name?
-        return nil if if_exists # skip hard existence check
-
-        return err("Materialized view #{schema}.#{rel} does not exist") unless view_exists?
-
-        nil
-      end
+      # @return [void]
+      def prepare; end
 
       ##
-      # Construct DROP SQL with cascade/restrict options.
+      # Build the SQL DROP statement.
       #
       # @api private
       # @return [String]
       #
-      def build_sql
+      def drop_sql
         drop_mode = cascade ? ' CASCADE' : ' RESTRICT'
         %(DROP MATERIALIZED VIEW IF EXISTS #{qualified_rel}#{drop_mode})
       end

data/lib/mat_views/services/regular_refresh.rb

@@ -13,32 +13,25 @@ module MatViews
     # This is the safest option for simple or low-frequency updates where
     # blocking reads during refresh is acceptable.
     #
-    # Supports optional row counting strategies:
-    # - `:estimated` → uses `pg_class.reltuples` (fast, approximate)
-    # - `:exact`     → runs `COUNT(*)` (accurate, but potentially slow)
-    # - `nil`        → no row count included in payload
+    # Options:
+    # - `row_count_strategy:` (Symbol, default: :none) → one of `:estimated`, `:exact`, or `:none or nil` to control row count reporting
     #
-    # @return [MatViews::ServiceResponse]
+    # Returns a {MatViews::ServiceResponse}
     #
-    # @example
-    #   svc = MatViews::Services::RegularRefresh.new(defn)
-    #   svc.run
+    # @see MatViews::Services::ConcurrentRefresh
+    # @see MatViews::Services::SwapRefresh
+    #
+    # @example Direct usage
+    #   svc = MatViews::Services::RegularRefresh.new(definition, **options)
+    #   response = svc.call
+    #   response.success? # => true/false
+    #
+    # @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::RegularRefresh, definition.id, **options)
     #
     class RegularRefresh < BaseService
-      ##
-      # The row count strategy requested.
-      # One of `:estimated`, `:exact`, `nil`, or unrecognized symbol.
-      #
-      # @return [Symbol, nil]
-      attr_reader :row_count_strategy
-
-      ##
-      # @param definition [MatViews::MatViewDefinition]
-      # @param row_count_strategy [Symbol, nil] row counting mode
-      def initialize(definition, row_count_strategy: :estimated)
-        super(definition)
-        @row_count_strategy = row_count_strategy
-      end
+      private
 
       ##
       # Perform the refresh.
@@ -49,97 +42,48 @@ module MatViews
       # - Optionally compute row count.
       #
       # @return [MatViews::ServiceResponse]
+      #   - `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
-        prep = prepare!
-        return prep if prep
-
+      def _run
         sql = "REFRESH MATERIALIZED VIEW #{qualified_rel}"
 
-        conn.execute(sql)
+        self.response = { view: "#{schema}.#{rel}", sql: [sql] }
 
-        payload = { view: "#{schema}.#{rel}" }
-        payload[:row_count] = fetch_rows_count if row_count_strategy.present?
+        response[:row_count_before] = fetch_rows_count
+        conn.execute(sql)
+        response[:row_count_after] = fetch_rows_count
 
-        ok(:updated,
-           payload: payload,
-           meta: { sql: sql, row_count_strategy: row_count_strategy })
-      rescue StandardError => e
-        error_response(
-          e,
-          meta: {
-            sql: sql,
-            backtrace: Array(e.backtrace),
-            row_count_strategy: row_count_strategy
-          },
-          payload: { view: "#{schema}.#{rel}" }
-        )
+        ok(:updated)
       end
 
-      private
-
-      # ────────────────────────────────────────────────────────────────
-      # internal
-      # ────────────────────────────────────────────────────────────────
-
       ##
-      # Validate name and existence of the materialized view.
+      # Validation step (invoked by BaseService#call before execution).
+      # Ensures view exists.
       #
       # @api private
-      # @return [MatViews::ServiceResponse, nil]
       #
-      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?
-
-        nil
-      end
-
-      # ────────────────────────────────────────────────────────────────
-      # rows counting
-      # ────────────────────────────────────────────────────────────────
-
-      ##
-      # Pick the appropriate row count method.
-      #
-      # @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
-      end
+      def prepare
+        raise_err "Materialized view #{schema}.#{rel} does not exist" unless view_exists?
 
-      ##
-      # Fast/approx via `pg_class.reltuples`.
-      # Updated by `ANALYZE` and autovacuum.
-      #
-      # @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
+        nil
       end
 
       ##
-      # Accurate count via `COUNT(*)`.
-      # Potentially slow on large materialized views.
+      # Assign the request parameters.
+      # Called by {#call} before {#prepare}.
       #
       # @api private
-      # @return [Integer]
+      # @return [void]
       #
-      def exact_rows_count
-        conn.select_value("SELECT COUNT(*) FROM #{qualified_rel}").to_i
+      def assign_request
+        self.request = { row_count_strategy: row_count_strategy }
       end
     end
   end