smriti 0.5.0

data/lib/smriti/services/create_view.rb

@@ -0,0 +1,173 @@
+# 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 Smriti
+  module Services
+    ##
+    # Service responsible for creating PostgreSQL materialised 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.
+    #
+    # Options:
+    # - `force:` (Boolean, default: false) → drop and recreate if the view already exists
+    # - `row_count_strategy:` (Symbol, default: :none) → one of `:estimated`, `:exact`, or `:none or nil` to control row count reporting
+    #
+    # Returns a {Smriti::ServiceResponse}
+    #
+    # @see Smriti::Services::RegularRefresh
+    # @see Smriti::Services::ConcurrentRefresh
+    #
+    # @example Create a new matview (no force)
+    #   svc = Smriti::Services::CreateView.new(defn, **options)
+    #   response = svc.call
+    #   response.status # => :created or :skipped
+    #
+    # @example Force recreate an existing matview
+    #   svc = Smriti::Services::CreateView.new(defn, force: true)
+    #   svc.call
+    #
+    # @example via job, this is the typical usage and will create a run record in the DB
+    #   Smriti::Jobs::Adapter.enqueue(Smriti::Services::CreateViewJob, definition.id, **options)
+    #
+    class CreateView < BaseService
+      ##
+      # Whether to force recreation (drop+create if exists).
+      #
+      # @return [Boolean]
+      attr_reader :force
+
+      ##
+      # @param definition [Smriti::MatViewDefinition]
+      # @param force [Boolean] Whether to drop+recreate an existing matview.
+      # @param row_count_strategy [Symbol, nil] one of `:estimated`, `:exact`, or `nil` (default: `:estimated`)
+      #
+      # Supports optional row count strategies:
+      # - `:estimated` → approximate, using `pg_class.reltuples`
+      # - `:exact` → accurate, using `COUNT(*)`
+      # - `nil` → skip row count
+      def initialize(definition, force: false, row_count_strategy: :estimated)
+        super(definition, row_count_strategy: row_count_strategy)
+        @force = force
+        # Transactions are disabled if unique_index_columns are present because
+        # PostgreSQL does not allow creating a UNIQUE INDEX CONCURRENTLY inside a transaction block.
+        # If a unique index is required (for concurrent refresh), we must avoid wrapping the operation in a transaction.
+        @use_transaction = definition.unique_index_columns.none?
+      end
+
+      private
+
+      ##
+      # Execute the create operation.
+      #
+      # - Validates name, SQL, and concurrent-index requirements.
+      # - Handles existing view: skipped (default) or drop+recreate (`force: true`).
+      # - Creates the materialised view WITH DATA.
+      # - Creates a UNIQUE index if refresh strategy is concurrent.
+      #
+      # @api private
+      #
+      # @return [Smriti::ServiceResponse]
+      #   - `status: :created or :skipped` on success, with `response` containing:
+      #     - `view` - the qualified view name
+      #     - `row_count_before` - if requested and available
+      #     - `row_count_after` - if requested and available
+      #   - `status: :error` with `error` on failure, with `error` containing:
+      #     - serlialized exception class, message, and backtrace in a hash
+      def _run
+        sql = create_with_data_sql
+        self.response = { view: "#{schema}.#{rel}", sql: [sql] }
+        # If exists, either skipped or drop+recreate
+        existed = handle_existing
+        return existed if existed.is_a?(Smriti::ServiceResponse)
+
+        response[:row_count_before] = UNKNOWN_ROW_COUNT
+        conn.execute(sql)
+        response[:row_count_after] = fetch_rows_count
+
+        # For concurrent strategy, ensure the unique index so future
+        # REFRESH MATERIALIZED VIEW CONCURRENTLY is allowed.
+        response.merge!(ensure_unique_index_if_needed)
+
+        ok(:created)
+      end
+
+      ##
+      # Validation step (invoked by BaseService#call before execution).
+      # Empty for this service as no other preparation is needed.
+      #
+      # @api private
+      #
+      # @return [void]
+      #
+      def prepare; end
+
+      ##
+      # Assign the request parameters.
+      # Called by {#call} before {#prepare}.
+      #
+      # @api private
+      # @return [void]
+      #
+      def assign_request
+        self.request = { row_count_strategy: row_count_strategy, force: }
+      end
+
+      ##
+      # Handle existing matview: return skipped if not forcing, or drop if forcing.
+      #
+      # @api private
+      # @return [Smriti::ServiceResponse, nil]
+      #
+      def handle_existing
+        return nil unless view_exists?
+
+        return ok(:skipped) unless force
+
+        drop_view
+        nil
+      end
+
+      ##
+      # SQL for `CREATE MATERIALIZED VIEW ... WITH DATA`.
+      # @api private
+      # @return [String]
+      #
+      def create_with_data_sql
+        <<~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 { |col| quote_column_name(col) }.join(', ')})
+        SQL
+        { created_indexes: [idx_name], row_count_before: UNKNOWN_ROW_COUNT, row_count_after: fetch_rows_count }
+      end
+    end
+  end
+end

data/lib/smriti/services/delete_view.rb

@@ -0,0 +1,111 @@
+# 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 Smriti
+  module Services
+    ##
+    # Service that safely drops a PostgreSQL materialised view.
+    #
+    # Options:
+    # - `cascade:` (Boolean, default: false) → drop with CASCADE instead of RESTRICT
+    # - `row_count_strategy:` (Symbol, default: :none) → one of `:estimated`, `:exact`, or `:none or nil` to control row count reporting
+    #
+    # Returns a {Smriti::ServiceResponse}
+    #
+    # @see Smriti::DeleteViewJob
+    # @see Smriti::MatViewRun
+    #
+    # @example Drop a view if it exists
+    #   svc = Smriti::Services::DeleteView.new(defn, **options)
+    #   svc.call
+    #
+    # @example Force drop with CASCADE
+    #   Smriti::Services::DeleteView.new(defn, cascade: true).call
+    #
+    # @example via job, this is the typical usage and will create a run record in the DB
+    #   Smriti::Jobs::Adapter.enqueue(Smriti::Services::DeleteViewJob, definition.id, **options)
+    #
+    class DeleteView < BaseService
+      ##
+      # Whether to cascade the drop (default: false).
+      #
+      # @return [Boolean]
+      attr_reader :cascade
+
+      ##
+      # @param definition [Smriti::MatViewDefinition]
+      # @param cascade [Boolean] drop with CASCADE instead of RESTRICT
+      # @param row_count_strategy [Symbol, nil] one of `:estimated`, `:exact`, or `nil` (default: `:estimated`)
+      def initialize(definition, cascade: false, row_count_strategy: :estimated)
+        super(definition, row_count_strategy: row_count_strategy)
+        @cascade = cascade ? true : false
+      end
+
+      private
+
+      ##
+      # Run the drop operation.
+      #
+      # Steps:
+      # - Validate name format
+      # - return :skipped if absent
+      # - Execute DROP MATERIALIZED VIEW.
+      #
+      # @api private
+      #
+      # @return [Smriti::ServiceResponse]
+      #   - `status: :deleted or :skipped` on success, with `response` containing:
+      #     - `view` - the qualified view name
+      #     - `row_count_before` - if requested and available
+      #     - `row_count_after` - if requested and available
+      #   - `status: :error` with `error` on failure, with `error` containing:
+      #     - serlialized exception class, message, and backtrace in a hash
+      def _run
+        self.response = { view: "#{schema}.#{rel}", sql: [drop_sql] }
+
+        return ok(:skipped) unless view_exists?
+
+        response[:row_count_before] = fetch_rows_count
+        conn.execute(drop_sql)
+        response[:row_count_after] = UNKNOWN_ROW_COUNT # view is gone
+        ok(:deleted)
+      end
+
+      ##
+      # Assign the request parameters.
+      # Called by {#call} before {#prepare}.
+      # Sets `concurrent: true` in the request hash.
+      #
+      # @api private
+      # @return [void]
+      #
+      def assign_request
+        self.request = { row_count_strategy: row_count_strategy, cascade: cascade }
+      end
+
+      ##
+      # Validation step (invoked by BaseService#call before execution).
+      # Empty for this service as no other preparation is needed.
+      #
+      # @api private
+      #
+      # @return [void]
+      def prepare; end
+
+      ##
+      # Build the SQL DROP statement.
+      #
+      # @api private
+      # @return [String]
+      #
+      def drop_sql
+        drop_mode = cascade ? ' CASCADE' : ' RESTRICT'
+        %(DROP MATERIALIZED VIEW IF EXISTS #{qualified_rel}#{drop_mode})
+      end
+    end
+  end
+end

data/lib/smriti/services/regular_refresh.rb

@@ -0,0 +1,90 @@
+# 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 Smriti
+  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.
+    #
+    # Options:
+    # - `row_count_strategy:` (Symbol, default: :none) → one of `:estimated`, `:exact`, or `:none or nil` to control row count reporting
+    #
+    # Returns a {Smriti::ServiceResponse}
+    #
+    # @see Smriti::Services::ConcurrentRefresh
+    # @see Smriti::Services::SwapRefresh
+    #
+    # @example Direct usage
+    #   svc = Smriti::Services::RegularRefresh.new(definition, **options)
+    #   response = svc.call
+    #   response.success? # => true/false
+    #
+    # @example via job, this is the typical usage and will create a run record in the DB
+    #   When definition.refresh_strategy == "concurrent"
+    #   Smriti::Jobs::Adapter.enqueue(Smriti::Services::RegularRefresh, definition.id, **options)
+    #
+    class RegularRefresh < BaseService
+      private
+
+      ##
+      # Perform the refresh.
+      #
+      # Steps:
+      # - Validate name & existence.
+      # - Run `REFRESH MATERIALIZED VIEW`.
+      # - Optionally compute row count.
+      #
+      # @return [Smriti::ServiceResponse]
+      #   - `status: :updated` on success, with `response` containing:
+      #     - `view` - the qualified view name
+      #     - `row_count_before` - if requested and available
+      #     - `row_count_after` - if requested and available
+      #   - `status: :error` with `error` on failure, with `error` containing:
+      #     - serlialized exception class, message, and backtrace in a hash
+      #
+      def _run
+        sql = "REFRESH MATERIALIZED VIEW #{qualified_rel}"
+
+        self.response = { view: "#{schema}.#{rel}", sql: [sql] }
+
+        response[:row_count_before] = fetch_rows_count
+        conn.execute(sql)
+        response[:row_count_after] = fetch_rows_count
+
+        ok(:updated)
+      end
+
+      ##
+      # Validation step (invoked by BaseService#call before execution).
+      # Ensures view exists.
+      #
+      # @api private
+      #
+      # @return [void]
+      #
+      def prepare
+        raise_err "Materialized view #{schema}.#{rel} does not exist" unless view_exists?
+
+        nil
+      end
+
+      ##
+      # Assign the request parameters.
+      # Called by {#call} before {#prepare}.
+      #
+      # @api private
+      # @return [void]
+      #
+      def assign_request
+        self.request = { row_count_strategy: row_count_strategy }
+      end
+    end
+  end
+end

data/lib/smriti/services/swap_refresh.rb

@@ -0,0 +1,181 @@
+# 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 Smriti
+  module Services
+    ##
+    # Service that performs a **swap-style refresh** of a materialised view.
+    #
+    # Instead of locking the existing view, this strategy builds a new
+    # temporary materialised 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).
+    #
+    # Options:
+    # - `row_count_strategy:` (Symbol, default: :none) → one of `:estimated`, `:exact`, or `:none or nil` to control row count reporting
+    #
+    # Returns a {Smriti::ServiceResponse}
+    #
+    # @see Smriti::Services::ConcurrentRefresh
+    # @see Smriti::Services::RegularRefresh
+    #
+    # @example Direct usage
+    #   svc = Smriti::Services::SwapRefresh.new(definition, **options)
+    #   response = svc.call
+    #   response.success? # => true/false
+    #
+    # @example via job, this is the typical usage and will create a run record in the DB
+    #   When definition.refresh_strategy == "concurrent"
+    #   Smriti::Jobs::Adapter.enqueue(Smriti::Services::SwapRefresh, definition.id, **options)
+    #
+    class SwapRefresh < BaseService
+      private
+
+      ##
+      # Execute the swap refresh.
+      #
+      # @return [Smriti::ServiceResponse]
+      #   - `status: :updated` on success, with `response` containing:
+      #     - `view` - the qualified view name
+      #     - `row_count_before` - if requested and available
+      #     - `row_count_after` - if requested and available
+      #   - `status: :error` with `error` on failure, with `error` containing:
+      #     - serlialized exception class, message, and backtrace in a hash
+      #
+      def _run
+        self.response = { view: "#{schema}.#{rel}" }
+
+        response[:row_count_before] = fetch_rows_count
+        response[:sql] = swap_view
+        response[:row_count_after] = fetch_rows_count
+
+        ok(:updated)
+      end
+
+      ##
+      # Validation step (invoked by BaseService#call before execution).
+      # Ensures view exists.
+      #
+      # @api private
+      #
+      # @return [void]
+      #
+      def prepare
+        raise_err "Materialized view #{schema}.#{rel} does not exist" unless view_exists?
+
+        nil
+      end
+
+      ##
+      # Assign the request parameters.
+      # Called by {#call} before {#prepare}.
+      #
+      # @api private
+      # @return [void]
+      #
+      def assign_request
+        self.request = { row_count_strategy: row_count_strategy, swap: true }
+      end
+
+      ##
+      # Perform rename/drop/index recreation in a transaction.
+      #
+      # @api private
+      # @return [Array<String>] SQL steps executed
+      def swap_view
+        conn.execute(create_temp_view_sql)
+        steps = [
+          move_current_to_old_sql,
+          move_temp_to_current_sql,
+          drop_old_view_sql,
+          recreate_declared_unique_indexes_sql
+        ].compact
+        conn.transaction do
+          steps.each { |step| conn.execute(step) }
+        end
+
+        # prepend the create step
+        steps.unshift(create_temp_view_sql)
+        steps
+      end
+
+      def create_temp_view_sql
+        @create_temp_view_sql ||= %(CREATE MATERIALIZED VIEW #{q_tmp} AS #{definition.sql} WITH DATA)
+      end
+
+      def move_current_to_old_sql
+        %(ALTER MATERIALIZED VIEW #{qualified_rel} RENAME TO #{conn.quote_column_name(old_rel)})
+      end
+
+      def move_temp_to_current_sql
+        %(ALTER MATERIALIZED VIEW #{q_tmp} RENAME TO #{conn.quote_column_name(rel)})
+      end
+
+      def drop_old_view_sql
+        %(DROP MATERIALIZED VIEW #{q_old})
+      end
+
+      ##
+      # Quote the temporary materialised 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 materialised 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
+      # @return [String] SQL statements to execute
+      def recreate_declared_unique_indexes_sql
+        cols = Array(definition.unique_index_columns).map(&:to_s).reject(&:empty?)
+        return nil if cols.empty?
+
+        quoted_cols = cols.map { |col| conn.quote_column_name(col) }.join(', ')
+        idx_name    = conn.quote_column_name("#{rel}_uniq_#{cols.join('_')}")
+        q_rel       = conn.quote_table_name("#{schema}.#{rel}")
+
+        %(CREATE UNIQUE INDEX #{idx_name} ON #{q_rel} (#{quoted_cols}))
+      end
+    end
+  end
+end

data/lib/smriti/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 Smriti
+  ##
+  # Defines the version of the Smriti 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.5.0'
+end

data/lib/smriti.rb

@@ -0,0 +1,64 @@
+# 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 'ext/exception'
+require 'smriti/version'
+require 'smriti/engine'
+require 'smriti/helpers/ui_test_ids'
+require 'smriti/configuration'
+require 'smriti/jobs/adapter'
+require 'smriti/service_response'
+require 'smriti/services/base_service'
+require 'smriti/services/create_view'
+require 'smriti/services/regular_refresh'
+require 'smriti/services/concurrent_refresh'
+require 'smriti/services/swap_refresh'
+require 'smriti/services/delete_view'
+require 'smriti/services/check_matview_exists'
+require 'smriti/admin/auth_bridge'
+require 'smriti/admin/default_auth'
+
+##
+# Smriti is a Rails engine that provides first-class support for
+# PostgreSQL materialised views in Rails applications.
+#
+# Features include:
+# - Declarative definitions for materialised 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:
+#   Smriti.configure do |config|
+#     config.job_queue = :low_priority
+#     config.job_adapter = :sidekiq
+#   end
+#
+# Once mounted, Rails apps can leverage Smriti services and jobs
+# to manage materialised views consistently.
+module Smriti
+  class << self
+    # Global configuration for Smriti
+    # @return [Smriti::Configuration]
+    attr_accessor :configuration
+
+    # Configure Smriti via block.
+    #
+    # Example:
+    #   Smriti.configure do |config|
+    #     config.job_adapter = :sidekiq
+    #     config.job_queue   = :materialised
+    #   end
+    def configure
+      @configuration ||= Configuration.new
+      yield(configuration)
+
+      configuration.admin_ui[:row_count_strategy] ||= :none
+    end
+  end
+end