mat_views 0.1.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ed05279bf4f2812ebeb8cb882f38772636f28c273b0992a878e13fb06b95d17f
+  data.tar.gz: 8fa0d71481c042d1b763e012b91dfe397373161decf8a68ef13c27bd3349fb33
+SHA512:
+  metadata.gz: 3233a39ea2a44171bc95d15be3bfccf53f507f49efb946787888f3aeae95b94273126331ac607a83e3d9e23c1f8770a4b0362ee2825b6c7ae1c60aab6f9aff92
+  data.tar.gz: 05566cd4d75f7ef05465387a39794ca1cae6351375e8b298b7deec0f1503e517d09429f5d1b605042dd6f739c0fa6f868fc839ce600bf201228f206c01dbaec9

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 The mat_views Authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,121 @@
+# mat_views (engine)
+
+[![Gem](https://img.shields.io/gem/v/mat_views.svg?style=flat-square)](https://rubygems.org/gems/mat_views)
+[![CI](https://github.com/Code-Vedas/rails_materialized_views/actions/workflows/ci.yml/badge.svg)](https://github.com/Code-Vedas/rails_materialized_views/actions/workflows/ci.yml)
+![License](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)
+
+Rails engine that manages **PostgreSQL materialized views** with definitions, services, background jobs, and Rake tasks.
+
+---
+
+## Quickstart (diagram)
+
+```mermaid
+flowchart LR
+  A[Define MatViewDefinition] --> B[Create]
+  B --> C[Unique Index for CONCURRENT]
+  C --> D[Refresh: regular or concurrent or swap]
+  D --> E[Read MV]
+  D --> F[Track runs]
+```
+
+---
+
+## Install
+
+```bash
+bundle add mat_views
+bin/rails g mat_views:install
+bin/rails db:migrate
+```
+
+```ruby
+# config/initializers/mat_views.rb
+MatViews.configure do |c|
+  c.job_queue = :default
+end
+```
+
+---
+
+## Define a view
+
+```ruby
+defn = MatViews::MatViewDefinition.create!(
+  name: 'mv_user_activity',
+  sql: <<~SQL,
+    SELECT u.id AS user_id,
+           COUNT(a.*) AS accounts_count,
+           COUNT(e.*) AS events_count,
+           COUNT(s.*) AS sessions_count
+    FROM users u
+    LEFT JOIN accounts a ON a.user_id = u.id
+    LEFT JOIN events   e ON e.user_id = u.id
+    LEFT JOIN sessions s ON s.user_id = u.id
+    GROUP BY u.id
+  SQL
+  refresh_strategy: :concurrent,
+  unique_index_columns: ['user_id']
+)
+```
+
+---
+
+## Services & Jobs
+
+```ruby
+# Create
+MatViews::Services::CreateView.new(defn, force: true).run
+MatViews::CreateViewJob.perform_later(defn.id, force: true)
+
+# Refresh
+MatViews::Services::RegularRefresh.new(defn, row_count_strategy: :estimated).run
+MatViews::RefreshViewJob.perform_later(defn.id, row_count_strategy: :exact)
+
+# Delete
+MatViews::Services::DeleteView.new(defn, cascade: false, if_exists: true).run
+MatViews::DeleteViewJob.perform_later(defn.id, cascade: true)
+```
+
+**Uniform response**: `status`, `payload`, `meta`, `success?` / `error?`.
+
+---
+
+## Enqueue adapter
+
+```ruby
+MatViews::Jobs::Adapter.enqueue(job_class, queue: :default, args: [...])
+```
+
+- Uses your configured backend; **no guessing**.
+- Supports **ActiveJob**, **Sidekiq**, **Resque**.
+
+---
+
+## Rake tasks
+
+```bash
+# Create
+bundle exec rake mat_views:create_by_name\[VIEW_NAME,force,--yes]
+bundle exec rake mat_views:create_by_id\[ID,force,--yes]
+bundle exec rake mat_views:create_all\[force,--yes]
+
+# Refresh
+bundle exec rake mat_views:refresh_by_name\[VIEW_NAME,row_count_strategy,--yes]
+bundle exec rake mat_views:refresh_by_id\[ID,row_count_strategy,--yes]
+bundle exec rake mat_views:refresh_all\[row_count_strategy,--yes]
+
+# Delete
+bundle exec rake mat_views:delete_by_name\[VIEW_NAME,cascade,--yes]
+bundle exec rake mat_views:delete_by_id\[ID,cascade,--yes]
+bundle exec rake mat_views:delete_all\[cascade,--yes]
+```
+
+---
+
+## Docs & policies
+
+- Root README: [../README.md](../README.md)
+- **Contributing:** [../CONTRIBUTING.md](../CONTRIBUTING.md)
+- **Security policy:** [../SECURITY.md](../SECURITY.md)
+- **Code of Conduct:** [../CODE_OF_CONDUCT.md](../CODE_OF_CONDUCT.md)

data/Rakefile

@@ -0,0 +1,15 @@
+# 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 'bundler/setup'
+
+APP_RAKEFILE = File.expand_path('spec/dummy/Rakefile', __dir__)
+load 'rails/tasks/engine.rake'
+
+load 'rails/tasks/statistics.rake'
+
+require 'bundler/gem_tasks'

data/app/assets/stylesheets/mat_views/application.css

@@ -0,0 +1,15 @@
+/*
+ * This is a manifest file that'll be compiled into application.css, which will include all the files
+ * listed below.
+ *
+ * Any CSS and SCSS file within this directory, lib/assets/stylesheets, vendor/assets/stylesheets,
+ * or any plugin's vendor/assets/stylesheets directory can be referenced here using a relative path.
+ *
+ * You're free to add application-wide styles to this file and they'll appear at the bottom of the
+ * compiled file so the styles you add here take precedence over styles defined in any other CSS/SCSS
+ * files in this directory. Styles in this file should be added after the last require_* statement.
+ * It is generally better to create a new file per style scope.
+ *
+ *= require_tree .
+ *= require_self
+ */

data/app/jobs/mat_views/application_job.rb

@@ -0,0 +1,39 @@
+# 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.
+#
+# All classes, modules, and services for materialized view management
+# are defined under this namespace.
+#
+# @example Accessing a job
+#   MatViews::ApplicationJob
+#
+module MatViews
+  ##
+  # Base class for all background jobs in the mat_views engine.
+  #
+  # Inherits from {ActiveJob::Base} and provides a common superclass
+  # for engine jobs such as {MatViews::CreateViewJob} and {MatViews::RefreshViewJob}.
+  #
+  # @abstract
+  #
+  # @see MatViews::CreateViewJob
+  # @see MatViews::RefreshViewJob
+  # @see MatViews::DeleteViewJob
+  #
+  # @example Defining a custom job
+  #   class MyCustomJob < MatViews::ApplicationJob
+  #     def perform(definition_id)
+  #       # custom logic here
+  #     end
+  #   end
+  #
+  class ApplicationJob < ActiveJob::Base
+  end
+end

data/app/jobs/mat_views/create_view_job.rb

@@ -0,0 +1,188 @@
+# 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 *creation* of PostgreSQL materialized views for a
+  # given {MatViews::MatViewDefinition}.
+  #
+  # The job:
+  # 1. Normalizes the `force` argument.
+  # 2. Looks up the target {MatViews::MatViewDefinition}.
+  # 3. Starts a {MatViews::MatViewRun} row to track lifecycle/timing, with `operation: :create`.
+  # 4. Executes {MatViews::Services::CreateView}.
+  # 5. Finalizes the run with success/failure, duration, and payload meta.
+  #
+  # @see MatViews::Services::CreateView
+  # @see MatViews::MatViewDefinition
+  # @see MatViews::MatViewRun
+  #
+  # @example Enqueue a create job
+  #   MatViews::CreateViewJob.perform_later(definition.id, force: true)
+  #
+  # @example Inline run (test/dev)
+  #   MatViews::CreateViewJob.new.perform(definition.id, false)
+  #
+  class CreateViewJob < ::ActiveJob::Base
+    ##
+    # Queue name for the job.
+    #
+    # Uses `MatViews.configuration.job_queue` when configured, otherwise `:default`.
+    #
+    # @return [void]
+    #
+    queue_as { MatViews.configuration.job_queue || :default }
+
+    ##
+    # Perform the job for the given materialized view definition.
+    #
+    # @api public
+    #
+    # @param definition_id [Integer, String] ID of {MatViews::MatViewDefinition}.
+    # @param force_arg [Boolean, Hash, nil] Optional flag or hash (`{ force: true }`)
+    #   to force creation (drop/recreate) when supported by the service.
+    #
+    # @return [Hash] A serialized {MatViews::ServiceResponse#to_h}:
+    #   - `:status` [Symbol] one of `:ok, :created, :updated, :noop, :error`
+    #   - `:payload` [Hash] service-specific payload (also stored in run.meta)
+    #   - `:error` [String, nil] error message if any
+    #   - `:duration_ms` [Integer, nil]
+    #   - `:meta` [Hash]
+    #
+    # @raise [StandardError] Re-raised on unexpected failure after marking the run failed.
+    #
+    # @see MatViews::Services::CreateView
+    #
+    def perform(definition_id, force_arg = nil)
+      force = normalize_force(force_arg)
+
+      definition = MatViews::MatViewDefinition.find(definition_id)
+      run        = start_run(definition)
+
+      response, duration_ms = execute(definition, force: force)
+      finalize_run!(run, response, duration_ms)
+      response.to_h
+    rescue StandardError => e
+      fail_run!(run, e) if run
+      raise e
+    end
+
+    private
+
+    ##
+    # Normalize the `force` argument into a boolean.
+    #
+    # Accepts either a boolean-ish value or a Hash (e.g., `{ force: true }` or `{ "force" => true }`).
+    #
+    # @api private
+    #
+    # @param arg [Object] Raw argument; commonly `true/false`, `nil`, or `Hash`.
+    # @return [Boolean] Coerced force flag.
+    #
+    def normalize_force(arg)
+      case arg
+      when Hash
+        arg[:force] || arg['force'] || false
+      else
+        !!arg
+      end
+    end
+
+    ##
+    # Execute the create service and measure duration.
+    #
+    # @api private
+    #
+    # @param definition [MatViews::MatViewDefinition]
+    # @param force [Boolean]
+    # @return [Array(MatViews::ServiceResponse, Integer)] response and elapsed ms.
+    #
+    def execute(definition, force:)
+      started  = monotime
+      response = MatViews::Services::CreateView.new(definition, force: force).run
+      [response, elapsed_ms(started)]
+    end
+
+    ##
+    # Begin a {MatViews::MatViewRun} row for lifecycle tracking.
+    #
+    # @api private
+    #
+    # @param definition [MatViews::MatViewDefinition]
+    # @return [MatViews::MatViewRun] newly created run with `status: :running`
+    #
+    def start_run(definition)
+      MatViews::MatViewRun.create!(
+        mat_view_definition: definition,
+        status: :running,
+        started_at: Time.current,
+        operation: :create
+      )
+    end
+
+    ##
+    # Finalize the run with success/failure, timing, and meta from the response payload.
+    #
+    # @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 from a monotonic source.
+    #
+    def monotime = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+    ##
+    # Convert a monotonic start time to elapsed milliseconds.
+    #
+    # @api private
+    # @param start [Float] monotonic seconds.
+    # @return [Integer] elapsed milliseconds.
+    #
+    def elapsed_ms(start) = ((monotime - start) * 1000).round
+  end
+end

data/app/jobs/mat_views/delete_view_job.rb

@@ -0,0 +1,196 @@
+# 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 *deletion* of PostgreSQL materialized views via
+  # {MatViews::Services::DeleteView}.
+  #
+  # This job mirrors {MatViews::CreateViewJob} and {MatViews::RefreshViewJob}:
+  # it times the run and persists lifecycle state in {MatViews::MatViewRun}.
+  #
+  # @see MatViews::Services::DeleteView
+  # @see MatViews::MatViewDefinition
+  # @see MatViews::MatViewRun
+  #
+  # @example Enqueue a delete job
+  #   MatViews::DeleteViewJob.perform_later(definition.id, cascade: true)
+  #
+  # @example Inline run (test/dev)
+  #   MatViews::DeleteViewJob.new.perform(definition.id, false)
+  #
+  class DeleteViewJob < ::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.
+    #
+    # @api public
+    #
+    # @param definition_id [Integer, String] ID of {MatViews::MatViewDefinition}.
+    # @param cascade_arg [Boolean, String, Integer, Hash, nil] Cascade option.
+    #   Accepts:
+    #   - `true/false`
+    #   - `1` (treated as true)
+    #   - `"true"`, `"1"`, `"yes"` (case-insensitive)
+    #   - `{ cascade: true }` or `{ "cascade" => true }`
+    #
+    # @return [Hash] A serialized {MatViews::ServiceResponse#to_h}:
+    #   - `:status` [Symbol] `:success`, `:failed`, etc.
+    #   - `:payload` [Hash] response payload (also stored in run.meta)
+    #   - `:error` [String, nil]
+    #   - `:duration_ms` [Integer]
+    #   - `:meta` [Hash]
+    #
+    # @raise [StandardError] Re-raised on unexpected failure after marking the run failed.
+    #
+    def perform(definition_id, cascade_arg = nil)
+      cascade    = normalize_cascade?(cascade_arg)
+      definition = MatViews::MatViewDefinition.find(definition_id)
+      run        = start_run(definition)
+
+      response, duration_ms = execute(definition, cascade: cascade)
+      finalize_run!(run, response, duration_ms)
+      response.to_h
+    rescue StandardError => e
+      fail_run!(run, e) if run
+      raise e
+    end
+
+    private
+
+    ##
+    # Normalize cascade argument into a boolean.
+    #
+    # @api private
+    # @param arg [Object] Raw cascade argument.
+    # @return [Boolean] Whether to cascade drop.
+    #
+    def normalize_cascade?(arg)
+      value = if arg.is_a?(Hash)
+                arg[:cascade] || arg['cascade']
+              else
+                arg
+              end
+      cascade_value_trueish?(value)
+    end
+
+    ##
+    # Evaluate if a value is "truthy" for cascade purposes.
+    #
+    # @api private
+    # @param value [Object]
+    # @return [Boolean]
+    #
+    def cascade_value_trueish?(value)
+      case value
+      when true
+        true
+      when String
+        %w[true 1 yes].include?(value.strip.downcase)
+      when Integer
+        value == 1
+      else
+        false
+      end
+    end
+
+    ##
+    # Execute the delete service and measure duration.
+    #
+    # @api private
+    # @param definition [MatViews::MatViewDefinition]
+    # @param cascade [Boolean]
+    # @return [Array(MatViews::ServiceResponse, Integer)]
+    #
+    def execute(definition, cascade:)
+      started  = monotime
+      response = MatViews::Services::DeleteView.new(definition, cascade: cascade, if_exists: true).run
+      [response, elapsed_ms(started)]
+    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: :drop
+      )
+    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