mat_views 0.1.2

data/lib/mat_views/services/create_view.rb

@@ -0,0 +1,156 @@
+# 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
+    ##
+    # Service responsible for creating PostgreSQL materialized 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}.
+    #
+    # @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
+    #
+    # @example Force recreate an existing matview
+    #   svc = MatViews::Services::CreateView.new(defn, force: true)
+    #   svc.run
+    #
+    class CreateView < BaseService
+      ##
+      # Whether to force recreation (drop+create if exists).
+      #
+      # @return [Boolean]
+      attr_reader :force
+
+      ##
+      # @param definition [MatViews::MatViewDefinition]
+      # @param force [Boolean] Whether to drop+recreate an existing matview.
+      def initialize(definition, force: false)
+        super(definition)
+        @force = !!force
+      end
+
+      ##
+      # 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.
+      # - 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
+      #
+      def run
+        prep = prepare!
+        return prep if prep # error response
+
+        # If exists, either noop 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
+
+        # 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
+
+      # ────────────────────────────────────────────────────────────────
+      # internal
+      # ────────────────────────────────────────────────────────────────
+
+      ##
+      # Validate name, SQL, and concurrent strategy requirements.
+      #
+      # @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?
+
+        nil
+      end
+
+      ##
+      # Handle existing matview: return noop if not forcing, or drop if forcing.
+      #
+      # @api private
+      # @return [MatViews::ServiceResponse, nil]
+      #
+      def handle_existing!
+        return nil unless view_exists?
+
+        return MatViews::ServiceResponse.new(status: :noop) unless force
+
+        drop_view
+        nil
+      end
+
+      ##
+      # Execute the CREATE MATERIALIZED VIEW WITH DATA statement.
+      #
+      # @api private
+      # @return [void]
+      #
+      def create_with_data
+        conn.execute(<<~SQL)
+          CREATE MATERIALIZED VIEW #{qualified_rel} AS
+          #{sql}
+          WITH DATA
+        SQL
+      end
+
+      ##
+      # Ensure a UNIQUE index if refresh strategy is concurrent.
+      #
+      # Builds an index name like `public_mvname_uniq_col1_col2`.
+      # Creates it concurrently if the PG connection is idle.
+      #
+      # @api private
+      # @return [Hash] `{ created_indexes: [String] }` or empty array if not needed
+      #
+      def ensure_unique_index_if_needed
+        return { created_indexes: [] } unless strategy == 'concurrent'
+
+        # Name like: public_mvname_uniq_col1_col2
+        idx_name = [schema, rel, 'uniq', *cols].join('_')
+
+        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(', ')})
+        SQL
+        { created_indexes: [idx_name] }
+      end
+    end
+  end
+end

data/lib/mat_views/services/delete_view.rb

@@ -0,0 +1,160 @@
+# 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
+    ##
+    # Service that safely drops a PostgreSQL materialized view.
+    #
+    # Options:
+    # - `if_exists:` (Boolean, default: true) → idempotent drop (skip if absent)
+    # - `cascade:`   (Boolean, default: false) → use CASCADE instead of RESTRICT
+    #
+    # 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
+    #
+    # @see MatViews::DeleteViewJob
+    # @see MatViews::MatViewRun
+    #
+    # @example Drop a view if it exists
+    #   svc = MatViews::Services::DeleteView.new(defn)
+    #   svc.run
+    #
+    # @example Force drop with CASCADE
+    #   MatViews::Services::DeleteView.new(defn, cascade: true).run
+    #
+    class DeleteView < BaseService
+      ##
+      # Whether to cascade the drop (default: false).
+      #
+      # @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
+      end
+
+      ##
+      # Run the drop operation.
+      #
+      # Steps:
+      # - Validate name format and (optionally) existence.
+      # - Return `:skipped` if absent and `if_exists` true.
+      # - 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 })
+      end
+
+      ##
+      # Build the SQL DROP statement.
+      #
+      # @api private
+      # @return [String]
+      #
+      def sql
+        @sql ||= build_sql
+      end
+
+      ##
+      # Validate name and existence depending on options.
+      #
+      # @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
+
+      ##
+      # Construct DROP SQL with cascade/restrict options.
+      #
+      # @api private
+      # @return [String]
+      #
+      def build_sql
+        drop_mode = cascade ? ' CASCADE' : ' RESTRICT'
+        %(DROP MATERIALIZED VIEW IF EXISTS #{qualified_rel}#{drop_mode})
+      end
+    end
+  end
+end

data/lib/mat_views/services/regular_refresh.rb

@@ -0,0 +1,146 @@
+# 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
+    ##
+    # Service that executes a standard (locking) `REFRESH MATERIALIZED VIEW`.
+    #
+    # 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
+    #
+    # @return [MatViews::ServiceResponse]
+    #
+    # @example
+    #   svc = MatViews::Services::RegularRefresh.new(defn)
+    #   svc.run
+    #
+    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
+
+      ##
+      # Perform the refresh.
+      #
+      # Steps:
+      # - Validate name & existence.
+      # - Run `REFRESH MATERIALIZED VIEW`.
+      # - Optionally compute row count.
+      #
+      # @return [MatViews::ServiceResponse]
+      #
+      def run
+        prep = prepare!
+        return prep if prep
+
+        sql = "REFRESH MATERIALIZED VIEW #{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 })
+      rescue StandardError => e
+        error_response(
+          e,
+          meta: {
+            sql: sql,
+            backtrace: Array(e.backtrace),
+            row_count_strategy: row_count_strategy
+          },
+          payload: { view: "#{schema}.#{rel}" }
+        )
+      end
+
+      private
+
+      # ────────────────────────────────────────────────────────────────
+      # internal
+      # ────────────────────────────────────────────────────────────────
+
+      ##
+      # Validate name and existence of the materialized view.
+      #
+      # @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]
+      #
+      def fetch_rows_count
+        case row_count_strategy
+        when :estimated then estimated_rows_count
+        when :exact     then exact_rows_count
+        end
+      end
+
+      ##
+      # 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
+      end
+
+      ##
+      # Accurate count via `COUNT(*)`.
+      # Potentially slow on large materialized views.
+      #
+      # @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/swap_refresh.rb

@@ -0,0 +1,221 @@
+# 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.
+
+require 'securerandom'
+
+module MatViews
+  module Services
+    ##
+    # Service that performs a **swap-style refresh** of a materialized view.
+    #
+    # Instead of locking the existing view, this strategy builds a new
+    # temporary materialized view and atomically swaps it in. This approach
+    # minimizes downtime and allows for safer rebuilds of large views.
+    #
+    # Steps:
+    # 1. Create a temporary MV from the provided SQL.
+    # 2. In a transaction: rename original → old, tmp → original, drop old.
+    # 3. Recreate declared unique indexes (if any).
+    #
+    # Supports optional row count strategies:
+    # - `:estimated` → approximate, using `pg_class.reltuples`
+    # - `:exact` → accurate, using `COUNT(*)`
+    # - `nil` → skip row count
+    #
+    # @return [MatViews::ServiceResponse]
+    #
+    # @example
+    #   svc = MatViews::Services::SwapRefresh.new(defn, row_count_strategy: :exact)
+    #   svc.run
+    #
+    class SwapRefresh < BaseService
+      ##
+      # Row count strategy (`:estimated`, `:exact`, `nil`).
+      #
+      # @return [Symbol, nil]
+      attr_reader :row_count_strategy
+
+      ##
+      # @param definition [MatViews::MatViewDefinition]
+      # @param row_count_strategy [Symbol, nil]
+      def initialize(definition, row_count_strategy: :estimated)
+        super(definition)
+        @row_count_strategy = row_count_strategy
+      end
+
+      ##
+      # Execute the swap refresh.
+      #
+      # @return [MatViews::ServiceResponse]
+      def run
+        prep = prepare!
+        return prep if prep
+
+        create_sql = %(CREATE MATERIALIZED VIEW #{q_tmp} AS #{definition.sql} WITH DATA)
+        steps = [create_sql]
+        conn.execute(create_sql)
+
+        steps.concat(swap_index)
+
+        payload = { view: "#{schema}.#{rel}" }
+        payload[:row_count] = fetch_rows_count if row_count_strategy.present?
+
+        ok(:updated, payload: payload, meta: { steps: steps, row_count_strategy: row_count_strategy, swap: true })
+      rescue StandardError => e
+        error_response(e,
+                       meta: {
+                         steps: steps,
+                         backtrace: Array(e.backtrace),
+                         row_count_strategy: row_count_strategy,
+                         swap: true
+                       },
+                       payload: { view: "#{schema}.#{rel}" })
+      end
+
+      private
+
+      # ────────────────────────────────────────────────────────────────
+      # internal
+      # ────────────────────────────────────────────────────────────────
+
+      ##
+      # Ensure name validity and existence of original view.
+      #
+      # @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
+
+      ##
+      # Perform rename/drop/index recreation in a transaction.
+      #
+      # @api private
+      # @return [Array<String>] SQL steps executed
+      def swap_index
+        steps = []
+        conn.transaction do
+          rename_orig_sql = %(ALTER MATERIALIZED VIEW #{qualified_rel} RENAME TO #{conn.quote_column_name(old_rel)})
+          steps << rename_orig_sql
+          conn.execute(rename_orig_sql)
+
+          rename_tmp_sql = %(ALTER MATERIALIZED VIEW #{q_tmp} RENAME TO #{conn.quote_column_name(rel)})
+          steps << rename_tmp_sql
+          conn.execute(rename_tmp_sql)
+
+          drop_old_sql = %(DROP MATERIALIZED VIEW #{q_old})
+          steps << drop_old_sql
+          conn.execute(drop_old_sql)
+
+          recreate_declared_unique_indexes!(schema:, rel:, steps:)
+        end
+        steps
+      end
+
+      ##
+      # Quote the temporary materialized view name.
+      #
+      # @api private
+      # @return [String] quoted temporary view name
+      def q_tmp
+        @q_tmp ||= conn.quote_table_name("#{schema}.#{tmp_rel}")
+      end
+
+      ##
+      # Quote the original materialized view name.
+      #
+      # @api private
+      # @return [String] quoted original view name
+      def q_old
+        @q_old ||= conn.quote_table_name("#{schema}.#{old_rel}")
+      end
+
+      ##
+      # Fully-qualified, safely-quoted temporary relation name.
+      #
+      # @api private
+      # @return [String]
+      def tmp_rel
+        @tmp_rel ||= "#{rel}__tmp_#{SecureRandom.hex(4)}"
+      end
+
+      ##
+      # Fully-qualified, safely-quoted old relation name.
+      #
+      # @api private
+      # @return [String]
+      def old_rel
+        @old_rel ||= "#{rel}__old_#{SecureRandom.hex(4)}"
+      end
+
+      ##
+      # Recreate declared unique indexes on the swapped-in view.
+      #
+      # @api private
+      # @param schema [String]
+      # @param rel [String]
+      # @param steps [Array<String>] collected SQL
+      def recreate_declared_unique_indexes!(schema:, rel:, steps:)
+        cols = Array(definition.unique_index_columns).map(&:to_s).reject(&:empty?)
+        return if cols.empty?
+
+        quoted_cols = cols.map { |c| conn.quote_column_name(c) }.join(', ')
+        idx_name    = conn.quote_column_name("#{rel}_uniq_#{cols.join('_')}")
+        q_rel       = conn.quote_table_name("#{schema}.#{rel}")
+
+        sql = %(CREATE UNIQUE INDEX #{idx_name} ON #{q_rel} (#{quoted_cols}))
+        steps << sql
+        conn.execute(sql)
+      end
+
+      # ────────────────────────────────────────────────────────────────
+      # rows counting
+      # ────────────────────────────────────────────────────────────────
+
+      ##
+      # Fetch the 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
+
+      ##
+      # 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 via `COUNT(*)`.
+      #
+      # @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/version.rb

@@ -0,0 +1,21 @@
+# 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
+  ##
+  # Defines the version of the MatViews gem.
+  #
+  # This constant is used to track and publish gem releases.
+  # It follows [Semantic Versioning](https://semver.org/):
+  #
+  # - MAJOR: Incompatible API changes
+  # - MINOR: Backwards-compatible functionality
+  # - PATCH: Backwards-compatible bug fixes
+  #
+  # @return [String] the current gem version
+  VERSION = '0.1.2'
+end