mat_views 0.1.2

data/app/jobs/mat_views/refresh_view_job.rb

@@ -0,0 +1,215 @@
+# 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
+  ##
+  # ActiveJob that handles `REFRESH MATERIALIZED VIEW` for a given
+  # {MatViews::MatViewDefinition}.
+  #
+  # The job mirrors {MatViews::CreateViewJob}'s lifecycle:
+  # it measures duration and persists state in {MatViews::MatViewRun}.
+  #
+  # The actual refresh implementation is delegated based on
+  # `definition.refresh_strategy`:
+  #
+  # - `"concurrent"` → {MatViews::Services::ConcurrentRefresh}
+  # - `"swap"`       → {MatViews::Services::SwapRefresh}
+  # - otherwise      → {MatViews::Services::RegularRefresh}
+  #
+  # Row count reporting can be controlled via `row_count_strategy`:
+  # - `:estimated` (default) — fast, approximate via reltuples
+  # - `:exact` — accurate `COUNT(*)`
+  # - `nil` — skip counting
+  #
+  # @see MatViews::MatViewDefinition
+  # @see MatViews::MatViewRun
+  # @see MatViews::Services::RegularRefresh
+  # @see MatViews::Services::ConcurrentRefresh
+  # @see MatViews::Services::SwapRefresh
+  #
+  # @example Enqueue a refresh with exact row count
+  #   MatViews::RefreshViewJob.perform_later(definition.id, :exact)
+  #
+  # @example Enqueue using keyword-hash form
+  #   MatViews::RefreshViewJob.perform_later(definition.id, row_count_strategy: :estimated)
+  #
+  class RefreshViewJob < ::ActiveJob::Base
+    ##
+    # Queue name for the job.
+    #
+    # Uses `MatViews.configuration.job_queue` when configured, otherwise `:default`.
+    #
+    queue_as { MatViews.configuration.job_queue || :default }
+
+    ##
+    # Perform the job for the given materialized view definition.
+    #
+    # Accepts either a symbol/string (`:estimated`, `:exact`) or a hash
+    # (`{ row_count_strategy: :exact }`) for `strategy_arg`.
+    #
+    # @api public
+    #
+    # @param definition_id [Integer, String] ID of {MatViews::MatViewDefinition}.
+    # @param strategy_arg [Symbol, String, Hash, nil] Row count strategy override.
+    #   When a Hash, looks for `:row_count_strategy` / `"row_count_strategy"`.
+    #
+    # @return [Hash] Serialized {MatViews::ServiceResponse#to_h}:
+    #   - `:status` [Symbol]
+    #   - `:payload` [Hash]
+    #   - `:error` [String, nil]
+    #   - `:duration_ms` [Integer]
+    #   - `:meta` [Hash]
+    #
+    # @raise [StandardError] Re-raised on unexpected failure after marking the run failed.
+    #
+    def perform(definition_id, strategy_arg = nil)
+      row_count_strategy = normalize_strategy(strategy_arg)
+      definition = MatViews::MatViewDefinition.find(definition_id)
+      run        = start_run(definition)
+
+      response, duration_ms = execute(definition, row_count_strategy: row_count_strategy)
+      finalize_run!(run, response, duration_ms)
+      response.to_h
+    rescue StandardError => e
+      fail_run!(run, e) if run
+      raise e
+    end
+
+    private
+
+    ##
+    # Normalize the strategy argument into a symbol or default.
+    #
+    # @api private
+    #
+    # @param arg [Symbol, String, Hash, nil]
+    # @return [Symbol] One of `:estimated`, `:exact`, or `:estimated` by default.
+    #
+    def normalize_strategy(arg)
+      case arg
+      when Hash
+        (arg[:row_count_strategy] || arg['row_count_strategy'] || :estimated).to_sym
+      when String, Symbol
+        arg.to_sym
+      else
+        :estimated
+      end
+    end
+
+    ##
+    # Execute the appropriate refresh service and measure duration.
+    #
+    # @api private
+    #
+    # @param definition [MatViews::MatViewDefinition]
+    # @param row_count_strategy [Symbol, nil]
+    # @return [Array(MatViews::ServiceResponse, Integer)] response and elapsed ms.
+    #
+    def execute(definition, row_count_strategy:)
+      started  = monotime
+      response = service(definition).new(definition, row_count_strategy: row_count_strategy).run
+      [response, elapsed_ms(started)]
+    end
+
+    ##
+    # Select the refresh service class based on the definition's strategy.
+    #
+    # @api private
+    #
+    # @param definition [MatViews::MatViewDefinition]
+    # @return [Class] One of the refresh service classes.
+    #
+    def service(definition)
+      case definition.refresh_strategy
+      when 'concurrent'
+        MatViews::Services::ConcurrentRefresh
+      when 'swap'
+        MatViews::Services::SwapRefresh
+      else
+        MatViews::Services::RegularRefresh
+      end
+    end
+
+    ##
+    # Begin a {MatViews::MatViewRun} row for lifecycle tracking.
+    #
+    # @api private
+    #
+    # @param definition [MatViews::MatViewDefinition]
+    # @return [MatViews::MatViewRun]
+    #
+    def start_run(definition)
+      MatViews::MatViewRun.create!(
+        mat_view_definition: definition,
+        status: :running,
+        started_at: Time.current,
+        operation: :refresh
+      )
+    end
+
+    ##
+    # Finalize the run with success/failure, timing, and meta from the response.
+    #
+    # @api private
+    #
+    # @param run [MatViews::MatViewRun]
+    # @param response [MatViews::ServiceResponse]
+    # @param duration_ms [Integer]
+    # @return [void]
+    #
+    def finalize_run!(run, response, duration_ms)
+      base_attrs = {
+        finished_at: Time.current,
+        duration_ms: duration_ms,
+        meta: response.payload || {}
+      }
+
+      if response.success?
+        run.update!(base_attrs.merge(status: :success, error: nil))
+      else
+        run.update!(base_attrs.merge(status: :failed, error: response.error.to_s.presence))
+      end
+    end
+
+    ##
+    # Mark the run failed due to an exception.
+    #
+    # @api private
+    #
+    # @param run [MatViews::MatViewRun]
+    # @param exception [Exception]
+    # @return [void]
+    #
+    def fail_run!(run, exception)
+      run.update!(
+        finished_at: Time.current,
+        duration_ms: run.duration_ms || 0,
+        error: "#{exception.class}: #{exception.message}",
+        status: :failed
+      )
+    end
+
+    ##
+    # Monotonic clock getter (for elapsed-time measurement).
+    #
+    # @api private
+    # @return [Float] seconds
+    #
+    def monotime = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+    ##
+    # Convert monotonic start time to elapsed milliseconds.
+    #
+    # @api private
+    # @param start [Float]
+    # @return [Integer] elapsed ms
+    #
+    def elapsed_ms(start) = ((monotime - start) * 1000).round
+  end
+end

data/app/models/mat_views/application_record.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.
+
+##
+# Top-level namespace for the mat_views engine.
+module MatViews
+  ##
+  # Base model class for all ActiveRecord models in the mat_views engine.
+  #
+  # Inherits from {ActiveRecord::Base} and marks itself as an abstract class.
+  # Other engine models should subclass this rather than inheriting directly
+  # from {ActiveRecord::Base}, so that shared behavior or configuration can be
+  # applied in one place.
+  #
+  # @abstract
+  #
+  # @example Define a new model under mat_views
+  #   class MatViews::MatViewDefinition < MatViews::ApplicationRecord
+  #     self.table_name = "mat_view_definitions"
+  #   end
+  #
+  class ApplicationRecord < ActiveRecord::Base
+    ##
+    # Marks this record class as abstract, so it won’t be persisted to a table.
+    #
+    # @return [void]
+    #
+    self.abstract_class = true
+  end
+end

data/app/models/mat_views/mat_view_definition.rb

@@ -0,0 +1,98 @@
+# 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
+  ##
+  # Represents a **materialized view definition** managed by the engine.
+  #
+  # A definition stores the canonical name and SQL for a materialized view and
+  # drives lifecycle operations (create, refresh, delete) via background jobs
+  # and services. It also tracks operational history through associated
+  # run models.
+  #
+  # Validations ensure a sane PostgreSQL identifier for `name` and that `sql`
+  # begins with `SELECT` (case-insensitive).
+  #
+  # @see MatViews::CreateViewJob
+  # @see MatViews::RefreshViewJob
+  # @see MatViews::DeleteViewJob
+  # @see MatViews::Services::CreateView
+  # @see MatViews::Services::RegularRefresh
+  # @see MatViews::Services::ConcurrentRefresh
+  # @see MatViews::Services::SwapRefresh
+  #
+  # @example Creating a definition
+  #   defn = MatViews::MatViewDefinition.create!(
+  #     name: "mv_user_accounts",
+  #     sql:  "SELECT users.id, accounts.id AS account_id FROM users JOIN accounts ON ..."
+  #   )
+  #
+  # @example Enqueue a refresh
+  #   MatViews::RefreshViewJob.perform_later(defn.id, :estimated)
+  #
+  class MatViewDefinition < ApplicationRecord
+    ##
+    # Underlying database table name.
+    self.table_name = 'mat_view_definitions'
+
+    # ────────────────────────────────────────────────────────────────
+    # Associations
+    # ────────────────────────────────────────────────────────────────
+
+    ##
+    # Historical create runs linked to this definition.
+    #
+    # @return [ActiveRecord::Relation<MatViews::MatViewRun>]
+    #
+    has_many :mat_view_runs,
+             dependent: :destroy,
+             class_name: 'MatViews::MatViewRun'
+
+    # ────────────────────────────────────────────────────────────────
+    # Validations
+    # ────────────────────────────────────────────────────────────────
+
+    ##
+    # @!attribute name
+    #   @return [String] PostgreSQL identifier for the materialized view.
+    #
+    validates :name,
+              presence: true,
+              uniqueness: true,
+              format: { with: /\A[a-zA-Z_][a-zA-Z0-9_]*\z/ }
+
+    ##
+    # @!attribute sql
+    #   @return [String] SELECT statement used to materialize the view.
+    #
+    validates :sql,
+              presence: true,
+              format: { with: /\A\s*SELECT/i, message: 'must begin with a SELECT' }
+
+    # ────────────────────────────────────────────────────────────────
+    # Enums / configuration
+    # ────────────────────────────────────────────────────────────────
+
+    ##
+    # Refresh strategy that governs which service is used by {RefreshViewJob}.
+    #
+    # - `:regular`    → {MatViews::Services::RegularRefresh}
+    # - `:concurrent` → {MatViews::Services::ConcurrentRefresh}
+    # - `:swap`       → {MatViews::Services::SwapRefresh}
+    #
+    # @!attribute [rw] refresh_strategy
+    #   @return [String] one of `"regular"`, `"concurrent"`, `"swap"`
+    #
+    enum :refresh_strategy, { regular: 0, concurrent: 1, swap: 2 }
+
+    def last_run
+      mat_view_runs.order(created_at: :desc).first
+    end
+  end
+end

data/app/models/mat_views/mat_view_run.rb

@@ -0,0 +1,89 @@
+# 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
+  ##
+  # ActiveRecord model that tracks the lifecycle of *runs* for
+  # materialized views.
+  #
+  # Each record corresponds to a single attempt to mutate a materialized view
+  # from a {MatViews::MatViewDefinition}, storing its status, timing, and
+  # any associated error or metadata.
+  #
+  # This model provides an auditable history of view provisioning across
+  # environments, useful for telemetry, dashboards, and debugging.
+  #
+  # @see MatViews::MatViewDefinition
+  # @see MatViews::CreateViewJob
+  #
+  # @example Query recent successful runs
+  #   MatViews::MatViewRun.status_success.order(created_at: :desc).limit(10)
+  #
+  # @example Check if a definition has any failed runs
+  #   definition.mat_view_runs.status_failed.any?
+  #
+  class MatViewRun < ApplicationRecord
+    ##
+    # Underlying database table name.
+    self.table_name = 'mat_view_runs'
+
+    ##
+    # The definition this run belongs to.
+    #
+    # @return [MatViews::MatViewDefinition]
+    #
+    belongs_to :mat_view_definition, class_name: 'MatViews::MatViewDefinition'
+
+    ##
+    # Status of the create run.
+    #
+    # @!attribute [r] status
+    #   @return [Symbol] One of:
+    #     - `:pending` — queued but not yet started
+    #     - `:running` — currently executing
+    #     - `:success` — completed successfully
+    #     - `:failed` — encountered an error
+    #
+    enum :status, {
+      pending: 0,
+      running: 1,
+      success: 2,
+      failed: 3
+    }, prefix: :status
+
+    # Operation type of the run.
+    #
+    # @!attribute [r] operation
+    #   @return [Symbol] One of:
+    #     - `:create` — initial creation of the materialized view
+    #     - `:refresh` — refreshing an existing view
+    #     - `:drop` — dropping the materialized view
+    enum :operation, {
+      create: 0,
+      refresh: 1,
+      drop: 2
+    }, prefix: :operation
+
+    ##
+    # Validations
+    #
+    # Ensures that a status is always present.
+    validates :status, presence: true
+
+    ##
+    # Scopes
+    scope :create_runs, -> { where(operation: :create) }
+    scope :refresh_runs, -> { where(operation: :refresh) }
+    scope :drop_runs,    -> { where(operation: :drop) }
+
+    def row_count
+      meta['row_count']
+    end
+  end
+end

data/config/routes.rb

@@ -0,0 +1,12 @@
+# 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.
+
+MatViews::Engine.routes.draw do
+  # Routes for MatViews can be defined here.
+  # For example, you can add a root route or other resources as needed.
+  # root 'mat_views#home'
+end

data/lib/generators/mat_views/install/install_generator.rb

@@ -0,0 +1,86 @@
+# 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 'rails/generators'
+require 'rails/generators/migration'
+require 'rails/generators/active_record'
+
+##
+# Top-level namespace for the mat_views engine.
+module MatViews
+  ##
+  # Namespace for Rails generators shipped with the mat_views engine.
+  module Generators
+    ##
+    # Rails generator that installs MatViews into a host application by:
+    #
+    # 1. Copying migrations for definitions and run-tracking tables.
+    # 2. Creating an initializer at `config/initializers/mat_views.rb`.
+    # 3. Printing a success message with next steps.
+    #
+    # @example Run the installer
+    #   bin/rails g mat_views:install
+    #
+    # @see MatViews::MatViewDefinition
+    # @see MatViews::MatViewRun
+    #
+    class InstallGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+
+      ##
+      # Directory containing template files for the generator.
+      #
+      # @return [String] absolute path to templates dir
+      #
+      source_root File.expand_path('templates', __dir__)
+
+      ##
+      # Short description shown in `rails g --help`.
+      desc 'Installs MatViews: copies migrations and initializer.'
+
+      ##
+      # Copies all required migrations into the host app.
+      #
+      # @return [void]
+      #
+      def copy_migrations
+        migration_template 'create_mat_view_definitions.rb', 'db/migrate/create_mat_view_definitions.rb'
+        migration_template 'create_mat_view_runs.rb', 'db/migrate/create_mat_view_runs.rb'
+      end
+
+      ##
+      # Creates the engine initializer in the host app.
+      #
+      # @return [void]
+      #
+      def create_initializer
+        copy_file 'mat_views_initializer.rb', 'config/initializers/mat_views.rb'
+      end
+
+      ##
+      # Prints a success message after installation.
+      #
+      # @return [void]
+      #
+      def show_success_message
+        say "\n✅ MatViews installed! Don't forget to run:  rails db:migrate\n", :green
+      end
+
+      ##
+      # Computes the next migration number for copied migrations.
+      #
+      # Required by Rails to generate timestamped migration filenames.
+      #
+      # @param path [String] destination path for migrations
+      # @return [String] the next migration number (timestamp)
+      #
+      def self.next_migration_number(path)
+        ActiveRecord::Generators::Base.next_migration_number(path)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,29 @@
+# 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.
+
+# This migration creates the mat_view_definitions table, which stores definitions for materialized views.
+# It includes fields for the view name, SQL definition, refresh strategy, schedule, unique index columns,
+# dependencies, last refreshed timestamp, and timestamps for creation and updates.
+class CreateMatViewDefinitions < ActiveRecord::Migration[7.1]
+  def change
+    create_table :mat_view_definitions do |t|
+      t.string :name, null: false, comment: 'The name of the materialized view'
+      t.text :sql, null: false, comment: 'The SQL query defining the materialized view'
+      # refresh_strategy can be
+      # regular: 0 - Default strategy, in-place refresh.
+      # concurrent: 1 - Concurrent refresh, requires at least one unique index.
+      # swap: 2 - Swap the materialized view with a new one, uses more memory.
+      t.integer :refresh_strategy, default: 0, null: false,
+                                   comment: 'Strategy for refreshing the materialized view. Options: regular, concurrent, swap'
+      t.string :schedule_cron, comment: 'Cron schedule for automatic refresh of the materialized view'
+      t.jsonb :unique_index_columns, default: [], comment: 'Columns used for unique indexing, if any'
+      t.jsonb :dependencies, default: [],
+                             comment: 'Dependencies of the materialized view, such as other views or tables'
+      t.timestamps
+    end
+  end
+end

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

@@ -0,0 +1,32 @@
+# 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.
+
+# This migration creates the mat_view_runs table, which tracks the mutation runs(create,refresh,drop) of materialized views.
+# It includes references to the materialized view definition, status, operation type, timestamps,
+# duration, error messages, and additional metadata.
+class CreateMatViewRuns < ActiveRecord::Migration[7.1]
+  def change
+    create_table :mat_view_runs do |t|
+      t.references :mat_view_definition,
+                   null: false,
+                   foreign_key: true,
+                   comment: 'Reference to the materialized view definition'
+
+      # 0=pending, 1=running, 2=success, 3=failed
+      t.integer  :status, null: false, default: 0, comment: '0=pending,1=running,2=success,3=failed'
+      # 0=create, 1=refresh, 2=drop
+      t.integer  :operation, null: false, default: 0, comment: '0=create,1=refresh,2=drop'
+      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.timestamps
+    end
+  end
+end

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

@@ -0,0 +1,23 @@
+# 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.
+
+MatViews.configure do |config|
+  ### Job Adapter Configuration
+  # Set job adapter for MatViews
+  # This can be set to :active_job, :sidekiq, and :resque,
+  # defaults to :active_job.
+  #
+  # Depending on your application's job processing setup.
+  # Uncomment the line below to set the job adapter.
+  # config.job_adapter = :active_job
+
+  # job_queue is the queue name for the job adapter.
+  # Default is :default.
+  # This is used to specify the queue where MatViews jobs will be enqueued.
+  # Uncomment the line below to set the job queue.
+  # config.job_queue = :default
+end

data/lib/mat_views/configuration.rb

@@ -0,0 +1,49 @@
+# 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
+  ##
+  # Configuration for the MatViews engine.
+  #
+  # This class provides customization points for how MatViews integrates
+  # with background job systems and controls default behavior across
+  # the engine.
+  #
+  # @example Configure in an initializer
+  #   MatViews.configure do |config|
+  #     config.job_adapter = :sidekiq
+  #     config.job_queue   = :low_priority
+  #   end
+  #
+  # Supported job adapters:
+  # - `:active_job` (default)
+  # - `:sidekiq`
+  # - `:resque`
+  #
+  class Configuration
+    ##
+    # The job adapter to use for enqueuing jobs.
+    #
+    # @return [Symbol] :active_job, :sidekiq, or :resque
+    attr_accessor :job_adapter
+
+    ##
+    # The default queue name to use for jobs.
+    #
+    # @return [Symbol, String]
+    attr_accessor :job_queue
+
+    ##
+    # Initialize with defaults.
+    #
+    # @return [void]
+    def initialize
+      @job_adapter = :active_job
+      @job_queue   = :default
+    end
+  end
+end