mat_views 0.1.2

data/lib/mat_views/engine.rb

@@ -0,0 +1,34 @@
+# 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
+  ##
+  # Rails Engine for MatViews.
+  #
+  # This engine encapsulates all functionality related to
+  # materialized views, including:
+  # - Defining materialized view definitions
+  # - Creating and refreshing views
+  # - Managing background jobs for refresh/create/delete
+  #
+  # By isolating the namespace, it ensures that routes, models,
+  # and helpers do not conflict with the host application.
+  #
+  # @example Mounting the engine in a Rails application
+  #   # config/routes.rb
+  #   Rails.application.routes.draw do
+  #     mount MatViews::Engine => "/mat_views"
+  #   end
+  #
+  class Engine < ::Rails::Engine
+    isolate_namespace MatViews
+
+    initializer 'mat_views.load_config' do
+      MatViews.configuration ||= MatViews::Configuration.new
+    end
+  end
+end

data/lib/mat_views/jobs/adapter.rb

@@ -0,0 +1,78 @@
+# 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.
+
+##
+# Top-level namespace for the mat_views engine.
+module MatViews
+  ##
+  # Namespace for job-related utilities and integrations.
+  module Jobs
+    ##
+    # Adapter class for handling job enqueuing across different backends.
+    #
+    # This class abstracts the job enqueueing process so MatViews can work
+    # with multiple background processing frameworks without changing core code.
+    #
+    # Supported adapters (configured via `MatViews.configuration.job_adapter`):
+    # - `:active_job` → {ActiveJob}
+    # - `:sidekiq`   → {Sidekiq::Client}
+    # - `:resque`    → {Resque}
+    #
+    # @example Enqueue via ActiveJob
+    #   MatViews.configuration.job_adapter = :active_job
+    #   MatViews::Jobs::Adapter.enqueue(MyJob, queue: :low, args: [1, "foo"])
+    #
+    # @example Enqueue via Sidekiq
+    #   MatViews.configuration.job_adapter = :sidekiq
+    #   MatViews::Jobs::Adapter.enqueue(MyWorker, queue: :critical, args: [42])
+    #
+    # @example Enqueue via Resque
+    #   MatViews.configuration.job_adapter = :resque
+    #   MatViews::Jobs::Adapter.enqueue(MyWorker, queue: :default, args: %w[a b c])
+    #
+    # @raise [ArgumentError] if the configured adapter is not recognized
+    #
+    class Adapter
+      ##
+      # Enqueue a job across supported backends.
+      #
+      # @api public
+      #
+      # @param job_class [Class] The job or worker class to enqueue.
+      #   - For `:active_job`, this should be a subclass of {ActiveJob::Base}.
+      #   - For `:sidekiq`, this should be a Sidekiq worker class.
+      #   - For `:resque`, this should be a Resque worker class.
+      #
+      # @param queue [String, Symbol] Target queue name.
+      # @param args [Array] Arguments to pass into the job/worker.
+      #
+      # @return [Object] Framework-dependent:
+      #   - For ActiveJob → enqueued {ActiveJob::Base} instance
+      #   - For Sidekiq → job ID hash
+      #   - For Resque → `true` if enqueue succeeded
+      #
+      # @raise [ArgumentError] if the configured adapter is not recognized.
+      #
+      def self.enqueue(job_class, queue:, args: [])
+        case MatViews.configuration.job_adapter
+        when :active_job
+          job_class.set(queue: queue.to_s).perform_later(*args)
+        when :sidekiq
+          Sidekiq::Client.push(
+            'class' => job_class.name,
+            'queue' => queue.to_s,
+            'args' => args
+          )
+        when :resque
+          Resque.enqueue_to(queue.to_s, job_class, *args)
+        else
+          raise ArgumentError, "Unknown job adapter: #{MatViews.configuration.job_adapter.inspect}"
+        end
+      end
+    end
+  end
+end

data/lib/mat_views/service_response.rb

@@ -0,0 +1,60 @@
+# 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
+  ##
+  # 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`,
+  #   `: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
+  #
+  # @example Successful response
+  #   MatViews::ServiceResponse.new(
+  #     status: :updated,
+  #     payload: { view: "public.users_mv" }
+  #   )
+  #
+  # @example Error response
+  #   MatViews::ServiceResponse.new(
+  #     status: :error,
+  #     error: StandardError.new("Something went wrong")
+  #   )
+  #
+  class ServiceResponse
+    attr_reader :status, :payload, :error, :meta
+
+    # @param status [Symbol] the outcome status
+    # @param payload [Hash] optional data payload
+    # @param error [Exception, String, nil] error details if applicable
+    # @param meta [Hash] additional metadata
+    def initialize(status:, payload: {}, error: nil, meta: {})
+      @status = status.to_sym
+      @payload = payload
+      @error = error
+      @meta = meta
+    end
+
+    # @return [Boolean] whether the response represents a success
+    def success?
+      !error? && %i[ok created updated noop skipped deleted].include?(status)
+    end
+
+    # @return [Boolean] whether the response represents an error
+    def error?
+      !error.nil? || status == :error
+    end
+
+    # @return [Hash] hash representation of the response
+    def to_h
+      { status:, payload:, error:, meta: }
+    end
+  end
+end

data/lib/mat_views/services/base_service.rb

@@ -0,0 +1,308 @@
+# 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
+    ##
+    # Base class for service objects that operate on PostgreSQL materialized
+    # views (create/refresh/delete, schema discovery, quoting, and common
+    # response helpers).
+    #
+    # Concrete services (e.g., {MatViews::Services::CreateView},
+    # {MatViews::Services::RegularRefresh}) should inherit from this class.
+    #
+    # @abstract
+    #
+    # @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" })
+    #     end
+    #   end
+    #
+    class BaseService
+      ##
+      # @return [MatViews::MatViewDefinition] The target materialized view definition.
+      attr_reader :definition
+
+      ##
+      # @param definition [MatViews::MatViewDefinition]
+      def initialize(definition)
+        @definition = definition
+      end
+
+      private
+
+      # ────────────────────────────────────────────────────────────────
+      # Schema / resolution helpers
+      # ────────────────────────────────────────────────────────────────
+
+      ##
+      # Resolve the first existing schema from `schema_search_path`,
+      # falling back to `"public"` if none are valid.
+      #
+      # Supports `$user`, quoted tokens, and ignores non-existent schemas.
+      #
+      # @api private
+      # @return [String] a valid schema name
+      #
+      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 << 'public' unless candidates.include?('public')
+        candidates.find { |s| schema_exists?(s) } || 'public'
+      end
+
+      ##
+      # Normalize a schema token:
+      # - strip surrounding quotes
+      # - expand `$user` to the current database user
+      #
+      # @api private
+      # @param token [String]
+      # @return [String]
+      #
+      def resolve_schema_token(token)
+        cleaned = token.delete_prefix('"').delete_suffix('"')
+        return current_user if cleaned == '$user'
+
+        cleaned
+      end
+
+      ##
+      # @api private
+      # @return [String] current PostgreSQL user
+      def current_user
+        @current_user ||= conn.select_value('SELECT current_user')
+      end
+
+      ##
+      # Check whether a schema exists.
+      #
+      # @api private
+      # @param name [String] schema name
+      # @return [Boolean]
+      #
+      def schema_exists?(name)
+        conn.select_value("SELECT to_regnamespace(#{conn.quote(name)}) IS NOT NULL")
+      end
+
+      # ────────────────────────────────────────────────────────────────
+      # View / relation helpers
+      # ────────────────────────────────────────────────────────────────
+
+      ##
+      # Whether the materialized view exists for the resolved `schema` and `rel`.
+      #
+      # @api private
+      # @return [Boolean]
+      #
+      def view_exists?
+        conn.select_value(<<~SQL).to_i.positive?
+          SELECT COUNT(*)
+          FROM pg_matviews
+          WHERE schemaname = #{conn.quote(schema)}
+            AND matviewname = #{conn.quote(rel)}
+        SQL
+      end
+
+      ##
+      # Fully-qualified, safely-quoted relation name, e.g. `"public"."mv_users"`.
+      #
+      # @api private
+      # @return [String]
+      #
+      def qualified_rel
+        %(#{quote_table_name(schema)}.#{quote_table_name(rel)})
+      end
+
+      ##
+      # Drop the materialized view if it exists (idempotent).
+      #
+      # @api private
+      # @return [void]
+      #
+      def drop_view
+        conn.execute(<<~SQL)
+          DROP MATERIALIZED VIEW IF EXISTS #{qualified_rel}
+        SQL
+      end
+
+      ##
+      # Refresh strategy from the definition (stringified).
+      #
+      # @api private
+      # @return [String] one of `"regular"`, `"concurrent"`, `"swap"` (or custom)
+      #
+      def strategy
+        @strategy ||= definition.refresh_strategy.to_s
+      end
+
+      ##
+      # Unqualified relation (matview) name from the definition.
+      #
+      # @api private
+      # @return [String]
+      #
+      def rel
+        @rel ||= definition.name.to_s
+      end
+
+      ##
+      # SQL `SELECT …` for the materialization.
+      #
+      # @api private
+      # @return [String]
+      #
+      def sql
+        @sql ||= definition.sql.to_s
+      end
+
+      ##
+      # Unique index column list (normalized to strings, unique).
+      #
+      # @api private
+      # @return [Array<String>]
+      #
+      def cols
+        @cols ||= Array(definition.unique_index_columns).map(&:to_s).uniq
+      end
+
+      ##
+      # ActiveRecord connection.
+      #
+      # @api private
+      # @return [ActiveRecord::ConnectionAdapters::AbstractAdapter]
+      #
+      def conn
+        @conn ||= ActiveRecord::Base.connection
+      end
+
+      ##
+      # Resolved, existing schema for this operation.
+      #
+      # @api private
+      # @return [String]
+      #
+      def schema
+        @schema ||= first_existing_schema
+      end
+
+      # ────────────────────────────────────────────────────────────────
+      # Response helpers
+      # ────────────────────────────────────────────────────────────────
+
+      ##
+      # 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
+      # @return [MatViews::ServiceResponse]
+      #
+      def ok(status, payload: {}, meta: {})
+        MatViews::ServiceResponse.new(status: status, payload: payload, meta: meta)
+      end
+
+      ##
+      # Build an error response with a message.
+      #
+      # @api private
+      # @param msg [String]
+      # @return [MatViews::ServiceResponse]
+      #
+      def err(msg)
+        MatViews::ServiceResponse.new(status: :error, error: msg)
+      end
+
+      ##
+      # Build an error response from an exception, including backtrace.
+      #
+      # @api private
+      # @param exception [Exception]
+      # @param payload [Hash]
+      # @param meta [Hash]
+      # @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 }
+        )
+      end
+
+      # ────────────────────────────────────────────────────────────────
+      # Quoting / environment helpers
+      # ────────────────────────────────────────────────────────────────
+
+      ##
+      # Quote a column name for SQL.
+      #
+      # @api private
+      # @param name [String, Symbol]
+      # @return [String] quoted column name
+      #
+      def quote_column_name(name)
+        conn.quote_column_name(name)
+      end
+
+      ##
+      # Quote a table/relation name for SQL.
+      #
+      # @api private
+      # @param name [String, Symbol]
+      # @return [String] quoted relation name
+      #
+      def quote_table_name(name)
+        conn.quote_table_name(name)
+      end
+
+      ##
+      # Whether the underlying PG connection is idle (no active tx/savepoint).
+      #
+      # Used to guard `CONCURRENTLY` operations which must run outside a txn.
+      #
+      # @api private
+      # @return [Boolean]
+      #
+      def pg_idle?
+        rc = conn.raw_connection
+        status = rc.respond_to?(:transaction_status) ? rc.transaction_status : nil
+        # Only use CONCURRENTLY outside any tx/savepoint.
+        status.nil? || status == PG::PQTRANS_IDLE
+      rescue StandardError
+        false
+      end
+
+      ##
+      # Validate SQL starts with SELECT.
+      #
+      # @api private
+      # @return [Boolean]
+      #
+      def valid_sql?
+        definition.sql.to_s.strip.upcase.start_with?('SELECT')
+      end
+
+      ##
+      # Validate that the view name is a sane PostgreSQL identifier.
+      #
+      # @api private
+      # @return [Boolean]
+      def valid_name?
+        /\A[a-zA-Z_][a-zA-Z0-9_]*\z/.match?(definition.name.to_s)
+      end
+    end
+  end
+end

data/lib/mat_views/services/concurrent_refresh.rb

@@ -0,0 +1,177 @@
+# 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
+    ##
+    # Refresh service that runs:
+    #
+    #   `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}.
+    #
+    # 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
+    #
+    # @see MatViews::Services::RegularRefresh
+    # @see MatViews::Services::SwapRefresh
+    #
+    # @example Direct usage
+    #   svc = MatViews::Services::ConcurrentRefresh.new(definition, row_count_strategy: :exact)
+    #   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)
+    #
+    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
+
+      ##
+      # Execute the concurrent refresh.
+      #
+      # Validates name format, existence of the matview, and presence of a UNIQUE index.
+      # 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
+
+        sql = "REFRESH MATERIALIZED VIEW CONCURRENTLY #{qualified_rel}"
+
+        conn.execute(sql)
+
+        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
+      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`.
+      #
+      # @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