mat_views 0.1.2

data/lib/mat_views.rb

@@ -0,0 +1,57 @@
+# 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 'mat_views/version'
+require 'mat_views/engine'
+require 'mat_views/configuration'
+require 'mat_views/jobs/adapter'
+require 'mat_views/service_response'
+require 'mat_views/services/base_service'
+require 'mat_views/services/create_view'
+require 'mat_views/services/regular_refresh'
+require 'mat_views/services/concurrent_refresh'
+require 'mat_views/services/swap_refresh'
+require 'mat_views/services/delete_view'
+
+##
+# MatViews is a Rails engine that provides first-class support for
+# PostgreSQL materialized views in Rails applications.
+#
+# Features include:
+# - Declarative definitions for materialized views
+# - Safe creation, refresh (regular, concurrent, swap), and deletion
+# - Background job integration (ActiveJob, Sidekiq, Resque)
+# - Tracking of run history and metrics
+# - Rake task helpers for operational workflows
+#
+# Usage:
+#   MatViews.configure do |config|
+#     config.job_queue = :low_priority
+#     config.job_adapter = :sidekiq
+#   end
+#
+# Once mounted, Rails apps can leverage MatViews services and jobs
+# to manage materialized views consistently.
+module MatViews
+  class << self
+    # Global configuration for MatViews
+    # @return [MatViews::Configuration]
+    attr_accessor :configuration
+
+    # Configure MatViews via block.
+    #
+    # Example:
+    #   MatViews.configure do |config|
+    #     config.job_adapter = :sidekiq
+    #     config.job_queue   = :materialized
+    #   end
+    def configure
+      self.configuration ||= Configuration.new
+      yield(configuration)
+    end
+  end
+end

data/lib/tasks/helpers.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+require 'logger'
+
+module MatViews
+  module Tasks
+    ##
+    # Helpers module provides utility methods for MatViews Rake tasks.
+    #
+    # These helpers support:
+    # - Database connections
+    # - Logging
+    # - Parsing boolean/flag-like arguments
+    # - Confirmation prompts
+    # - Enqueueing background jobs for create, refresh, and delete operations
+    # - Looking up materialized view definitions
+    #
+    # By extracting this logic, Rake tasks can remain clean and declarative.
+    module Helpers
+      module_function
+
+      # Returns the current database connection.
+      # @return [ActiveRecord::ConnectionAdapters::AbstractAdapter]
+      def mv_conn
+        ActiveRecord::Base.connection
+      end
+
+      # Returns the Rails logger.
+      # @return [Logger]
+      def logger
+        Rails.logger
+      end
+
+      # Check if a value is a "truthy" boolean-like string.
+      # Recognized: 1, true, yes, y, --yes
+      # @param value [String, Boolean, nil]
+      # @return [Boolean]
+      def booleanish_true?(value)
+        str = value.to_s.strip.downcase
+        %w[1 true yes y --yes].include?(str)
+      end
+
+      # Whether confirmation should be skipped (YES env or arg).
+      def skip_confirm?(arg)
+        booleanish_true?(arg || ENV.fetch('YES', nil))
+      end
+
+      # Parse whether force mode is enabled (FORCE env or arg).
+      def parse_force?(arg)
+        booleanish_true?(arg || ENV.fetch('FORCE', nil))
+      end
+
+      # Parse row count strategy from arg or ROW_COUNT_STRATEGY env.
+      # Defaults to :estimated if blank.
+      def parse_row_count_strategy(arg)
+        s = (arg || ENV.fetch('ROW_COUNT_STRATEGY', nil)).to_s.strip
+        return :estimated if s.empty?
+
+        s.to_sym
+      end
+
+      # Check if a materialized view exists in schema.
+      # @param rel [String] relation name
+      # @param schema [String] schema name
+      # @return [Boolean]
+      def matview_exists?(rel, schema: 'public')
+        mv_conn.select_value(<<~SQL).to_i.positive?
+          SELECT COUNT(*)
+          FROM pg_matviews
+          WHERE schemaname = #{mv_conn.quote(schema)} AND matviewname = #{mv_conn.quote(rel)}
+        SQL
+      end
+
+      # Find a MatViewDefinition by raw name (schema.rel or rel).
+      # Raises if none found or mismatch with DB presence.
+      #
+      # @param raw_name [String] schema-qualified or unqualified view name
+      # @return [MatViews::MatViewDefinition]
+      # @raise [RuntimeError] if no definition found or mismatch with DB
+      def find_definition_by_name!(raw_name)
+        raise 'view_name is required' if raw_name.nil? || raw_name.to_s.strip.empty?
+
+        schema, rel =
+          if raw_name.to_s.include?('.')
+            parts = raw_name.to_s.split('.', 2)
+            [parts[0], parts[1]]
+          else
+            [nil, raw_name.to_s]
+          end
+
+        defn = MatViews::MatViewDefinition.find_by(name: rel)
+        return defn if defn
+
+        if schema && matview_exists?(rel, schema: schema)
+          raise "Materialized view #{schema}.#{rel} exists, but no MatViews::MatViewDefinition record was found for name=#{rel.inspect}"
+        end
+
+        raise "No MatViews::MatViewDefinition found for #{raw_name.inspect}"
+      end
+
+      # Ask user to confirm a destructive action, unless skipped.
+      #
+      # @param message [String] confirmation message
+      # @param skip [Boolean] whether to skip confirmation
+      # @raise [RuntimeError] if user declines confirmation
+      # @return [void]
+      #
+      # If `skip` is true, logs the message and returns without prompting.
+      # Otherwise, prompts user for confirmation and raises if declined.
+      def confirm!(message, skip: false)
+        if skip
+          logger.info("[mat_views] #{message} — confirmation skipped.")
+          return
+        end
+
+        logger.info("[mat_views] #{message}")
+        $stdout.print('Proceed? [y/N]: ')
+        $stdout.flush
+        ans = $stdin.gets&.strip&.downcase
+        return if ans&.start_with?('y')
+
+        raise 'Aborted.'
+      end
+
+      # Enqueue a CreateView job for given definition.
+      #
+      # @param definition_id [Integer] MatViewDefinition ID
+      # @param force [Boolean] whether to force creation
+      # @return [void]
+      def enqueue_create!(definition_id, force)
+        q = MatViews.configuration.job_queue || :default
+        MatViews::Jobs::Adapter.enqueue(
+          MatViews::CreateViewJob,
+          queue: q,
+          args: [definition_id, force]
+        )
+      end
+
+      # Enqueue a RefreshView job for given definition.
+      #
+      # @param definition_id [Integer] MatViewDefinition ID
+      # @param row_count_strategy [Symbol] :estimated or :exact
+      # @return [void]
+      #
+      # This method allows scheduling a refresh operation with the specified row count strategy.
+      # It uses the configured job adapter to enqueue the job.
+      def enqueue_refresh!(definition_id, row_count_strategy)
+        q = MatViews.configuration.job_queue || :default
+        MatViews::Jobs::Adapter.enqueue(
+          MatViews::RefreshViewJob,
+          queue: q,
+          args: [definition_id, row_count_strategy]
+        )
+      end
+
+      # Parse cascade option (CASCADE env or arg).
+      #
+      # @param arg [String, Boolean, nil] argument or environment variable value
+      # @return [Boolean] true if cascade is enabled, false otherwise
+      #
+      # This method checks if the CASCADE option is set to true, allowing for cascading drops.
+      # It defaults to the value of the CASCADE environment variable if not provided.
+      def parse_cascade?(arg)
+        booleanish_true?(arg || ENV.fetch('CASCADE', nil))
+      end
+
+      # Enqueue a DeleteView job for given definition.
+      #
+      # @param definition_id [Integer] MatViewDefinition ID
+      # @param cascade [Boolean] whether to drop with CASCADE
+      # @return [void]
+      #
+      # This method schedules a job to delete the materialized view, optionally with CASCADE.
+      # It uses the configured job adapter to enqueue the job.
+      def enqueue_delete!(definition_id, cascade)
+        q = MatViews.configuration.job_queue || :default
+        MatViews::Jobs::Adapter.enqueue(
+          MatViews::DeleteViewJob,
+          queue: q,
+          args: [definition_id, cascade]
+        )
+      end
+    end
+  end
+end

data/lib/tasks/mat_views_tasks.rake

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require 'rake'
+require_relative 'helpers'
+
+# rubocop:disable Metrics/BlockLength
+namespace :mat_views do
+  helpers = MatViews::Tasks::Helpers
+
+  # ───────────── CREATE ─────────────
+
+  desc 'Enqueue a CREATE for a specific view by its name (optionally schema-qualified)'
+  task :create_by_name, %i[view_name force yes] => :environment do |_t, args|
+    force = helpers.parse_force?(args[:force])
+    skip  = helpers.skip_confirm?(args[:yes])
+    defn  = helpers.find_definition_by_name!(args[:view_name])
+
+    helpers.confirm!("Enqueue CREATE for view=#{defn.name} (id=#{defn.id}), force=#{force}", skip: skip)
+    helpers.enqueue_create!(defn.id, force)
+    helpers.logger.info("[mat_views] Enqueued CreateViewJob for definition ##{defn.id} (#{defn.name}), force=#{force}")
+  end
+
+  desc 'Enqueue a CREATE for a specific view by its definition ID'
+  task :create_by_id, %i[definition_id force yes] => :environment do |_t, args|
+    raise 'mat_views:create_by_id requires a definition_id parameter' if args[:definition_id].to_s.strip.empty?
+
+    force = helpers.parse_force?(args[:force])
+    skip  = helpers.skip_confirm?(args[:yes])
+
+    defn = MatViews::MatViewDefinition.find_by(id: args[:definition_id])
+    raise "No MatViews::MatViewDefinition found for id=#{args[:definition_id]}" unless defn
+
+    helpers.confirm!("Enqueue CREATE for id=#{defn.id} (#{defn.name}), force=#{force}", skip: skip)
+    helpers.enqueue_create!(defn.id, force)
+    helpers.logger.info("[mat_views] Enqueued CreateViewJob for definition ##{defn.id} (#{defn.name}), force=#{force}")
+  end
+
+  desc 'Enqueue CREATE jobs for ALL defined materialized views'
+  task :create_all, %i[force yes] => :environment do |_t, args|
+    force = helpers.parse_force?(args[:force])
+    skip  = helpers.skip_confirm?(args[:yes])
+
+    scope = MatViews::MatViewDefinition.all
+    count = scope.count
+    if count.zero?
+      helpers.logger.info('[mat_views] No mat view definitions found.')
+      next
+    end
+
+    helpers.confirm!("Enqueue CREATE for ALL (#{count}) views, force=#{force}", skip: skip)
+    scope.find_each { |defn| helpers.enqueue_create!(defn.id, force) }
+    helpers.logger.info("[mat_views] Enqueued #{count} CreateViewJob(s), force=#{force}.")
+  end
+
+  # ───────────── REFRESH ─────────────
+
+  desc 'Enqueue a REFRESH for a specific view by its name (optionally schema-qualified)'
+  task :refresh_by_name, %i[view_name row_count_strategy yes] => :environment do |_t, args|
+    rcs  = helpers.parse_row_count_strategy(args[:row_count_strategy])
+    skip = helpers.skip_confirm?(args[:yes])
+    defn = helpers.find_definition_by_name!(args[:view_name])
+
+    helpers.confirm!("Enqueue REFRESH for view=#{defn.name} (id=#{defn.id}), row_count_strategy=#{rcs}", skip: skip)
+    helpers.enqueue_refresh!(defn.id, rcs)
+    helpers.logger.info("[mat_views] Enqueued RefreshViewJob for definition ##{defn.id} (#{defn.name}), row_count_strategy=#{rcs}")
+  end
+
+  desc 'Enqueue a REFRESH for a specific view by its definition ID'
+  task :refresh_by_id, %i[definition_id row_count_strategy yes] => :environment do |_t, args|
+    raise 'mat_views:refresh_by_id requires a definition_id parameter' if args[:definition_id].to_s.strip.empty?
+
+    rcs  = helpers.parse_row_count_strategy(args[:row_count_strategy])
+    skip = helpers.skip_confirm?(args[:yes])
+
+    defn = MatViews::MatViewDefinition.find_by(id: args[:definition_id])
+    raise "No MatViews::MatViewDefinition found for id=#{args[:definition_id]}" unless defn
+
+    helpers.confirm!("Enqueue REFRESH for id=#{defn.id} (#{defn.name}), row_count_strategy=#{rcs}", skip: skip)
+    helpers.enqueue_refresh!(defn.id, rcs)
+    helpers.logger.info("[mat_views] Enqueued RefreshViewJob for definition ##{defn.id} (#{defn.name}), row_count_strategy=#{rcs}")
+  end
+
+  desc 'Enqueue REFRESH jobs for ALL defined materialized views'
+  task :refresh_all, %i[row_count_strategy yes] => :environment do |_t, args|
+    rcs  = helpers.parse_row_count_strategy(args[:row_count_strategy])
+    skip = helpers.skip_confirm?(args[:yes])
+
+    scope = MatViews::MatViewDefinition.all
+    count = scope.count
+    if count.zero?
+      helpers.logger.info('[mat_views] No mat view definitions found.')
+      next
+    end
+
+    helpers.confirm!("Enqueue REFRESH for ALL (#{count}) views, row_count_strategy=#{rcs}", skip: skip)
+    scope.find_each { |defn| helpers.enqueue_refresh!(defn.id, rcs) }
+    helpers.logger.info("[mat_views] Enqueued #{count} RefreshViewJob(s), row_count_strategy=#{rcs}.")
+  end
+
+  # ───────────── DELETE ─────────────
+
+  desc 'Enqueue a DELETE (DROP MATERIALIZED VIEW) for a specific view by its name (optionally schema-qualified)'
+  task :delete_by_name, %i[view_name cascade yes] => :environment do |_t, args|
+    cascade = helpers.parse_cascade?(args[:cascade])
+    skip    = helpers.skip_confirm?(args[:yes])
+    defn    = helpers.find_definition_by_name!(args[:view_name])
+
+    helpers.confirm!("Enqueue DELETE for view=#{defn.name} (id=#{defn.id}), cascade=#{cascade}", skip: skip)
+    helpers.enqueue_delete!(defn.id, cascade)
+    helpers.logger.info("[mat_views] Enqueued DeleteViewJob for definition ##{defn.id} (#{defn.name}), cascade=#{cascade}")
+  end
+
+  desc 'Enqueue a DELETE (DROP MATERIALIZED VIEW) for a specific view by its definition ID'
+  task :delete_by_id, %i[definition_id cascade yes] => :environment do |_t, args|
+    raise 'mat_views:delete_by_id requires a definition_id parameter' if args[:definition_id].to_s.strip.empty?
+
+    cascade = helpers.parse_cascade?(args[:cascade])
+    skip    = helpers.skip_confirm?(args[:yes])
+
+    defn = MatViews::MatViewDefinition.find_by(id: args[:definition_id])
+    raise "No MatViews::MatViewDefinition found for id=#{args[:definition_id]}" unless defn
+
+    helpers.confirm!("Enqueue DELETE for id=#{defn.id} (#{defn.name}), cascade=#{cascade}", skip: skip)
+    helpers.enqueue_delete!(defn.id, cascade)
+    helpers.logger.info("[mat_views] Enqueued DeleteViewJob for definition ##{defn.id} (#{defn.name}), cascade=#{cascade}")
+  end
+
+  desc 'Enqueue DELETE jobs for ALL defined materialized views'
+  task :delete_all, %i[cascade yes] => :environment do |_t, args|
+    cascade = helpers.parse_cascade?(args[:cascade])
+    skip    = helpers.skip_confirm?(args[:yes])
+
+    scope = MatViews::MatViewDefinition.all
+    count = scope.count
+    if count.zero?
+      helpers.logger.info('[mat_views] No mat view definitions found.')
+      next
+    end
+
+    helpers.confirm!("Enqueue DELETE for ALL (#{count}) views, cascade=#{cascade}", skip: skip)
+    scope.find_each { |defn| helpers.enqueue_delete!(defn.id, cascade) }
+    helpers.logger.info("[mat_views] Enqueued #{count} DeleteViewJob(s), cascade=#{cascade}.")
+  end
+end
+# rubocop:enable Metrics/BlockLength

metadata

@@ -0,0 +1,95 @@
+--- !ruby/object:Gem::Specification
+name: mat_views
+version: !ruby/object:Gem::Version
+  version: 0.1.2
+platform: ruby
+authors:
+- Nitesh Purohit
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+description: A mountable Rails engine to track, define, refresh, and monitor Postgres
+  materialized views.
+email:
+- nitesh.purohit.it@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- Rakefile
+- app/assets/stylesheets/mat_views/application.css
+- app/jobs/mat_views/application_job.rb
+- app/jobs/mat_views/create_view_job.rb
+- app/jobs/mat_views/delete_view_job.rb
+- app/jobs/mat_views/refresh_view_job.rb
+- app/models/mat_views/application_record.rb
+- app/models/mat_views/mat_view_definition.rb
+- app/models/mat_views/mat_view_run.rb
+- config/routes.rb
+- lib/generators/mat_views/install/install_generator.rb
+- lib/generators/mat_views/install/templates/create_mat_view_definitions.rb
+- lib/generators/mat_views/install/templates/create_mat_view_runs.rb
+- lib/generators/mat_views/install/templates/mat_views_initializer.rb
+- lib/mat_views.rb
+- lib/mat_views/configuration.rb
+- lib/mat_views/engine.rb
+- lib/mat_views/jobs/adapter.rb
+- lib/mat_views/service_response.rb
+- lib/mat_views/services/base_service.rb
+- lib/mat_views/services/concurrent_refresh.rb
+- lib/mat_views/services/create_view.rb
+- lib/mat_views/services/delete_view.rb
+- lib/mat_views/services/regular_refresh.rb
+- lib/mat_views/services/swap_refresh.rb
+- lib/mat_views/version.rb
+- lib/tasks/helpers.rb
+- lib/tasks/mat_views_tasks.rake
+homepage: https://github.com/Code-Vedas/rails_materialized_views
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/Code-Vedas/rails_materialized_views
+  source_code_uri: https://github.com/Code-Vedas/rails_materialized_views.git
+  changelog_uri: https://github.com/Code-Vedas/rails_materialized_views/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.8
+specification_version: 4
+summary: Manage and refresh PostgreSQL materialized views in Rails
+test_files: []