full_search 0.3.1 → 0.3.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 866994a5c7f55cea4237fb2edcbf59f1f7c8c32772c6830df737bcbea4a6f1c6
-  data.tar.gz: 5a11ccf1c48abd1050288bbb7107b8ade82132e009ac23ed5803ed153675f535
+  metadata.gz: 8c3e974821a38f57a0d71c6a2ad0260942773836c3404c9b3665bb9cc0a6d305
+  data.tar.gz: 841b5bb5c5086942f47bbf7626455d4a27d4261778dfc845e22d2d5262d0ff41
 SHA512:
-  metadata.gz: 35eb2afacd021899e68eb808b65a6f323db3d66770940471aa94d9c3238e41c409c678ac79d82dc609dcafaf3117d937895fa8effc9a8e665790a8625ef1f231
-  data.tar.gz: 5f1f25fe9e2c268e4f6b95c988ddb7958c34649fcf53aa941d0b19d1b605a5b4345864bb7206b597fc509b9802a110db6c3900a40fe1ab3d3ce1468db28aef85
+  metadata.gz: 88f20b95e78a0de07571c06560df3c9e45ac5927106dc600e6d8f4a9702611ee776d0f2c2edec9c9cfd5a26aacc5e91c727ae156043c46767ca995c4228f37b5
+  data.tar.gz: 8ba992243ac6ae15fb755d0817c75e6f8e41ec1cb4bad856c75cc9b7fe9ee3f760da92b97fcdbd1093677eaf83e93701c1f917ac82f26c650274e3891de74f6f

data/README.md

@@ -6,7 +6,7 @@ SQLite FTS5 full-text search for Rails/ActiveRecord. A lightweight, self-contain
 
 ## Requirements
 
-- Ruby 3.1+
+- Ruby 3.2+
 - Rails 8.0+
 - SQLite 3.34+ (if using typo tolerance)
 
@@ -78,6 +78,10 @@ These two operations are often confused:
 - **Rebuild** (`full_search:rebuild` / `Customer.rebuild!`) — drops and recreates the FTS virtual table. Needed when the DSL changes (fields added/removed, tokenizer changed, etc.). The table is re-created from scratch, backfilled, triggers re-installed, and the index is optimized.
 - **Reindex** (`Customer.reindex!` / `FullSearch::Index.reindex_source_fields!`) — updates existing FTS rows with fresh values from computed `source:` fields only. The table structure is untouched. Database triggers cover regular column changes automatically; only Ruby-evaluated `source:` blocks need an explicit reindex.
 
+### Setup lifecycle
+
+`full_search` evaluates the DSL block and installs callbacks when the model class loads, but it does **not** create the FTS table until Rails `after_initialize` (or until you call `FullSearch.setup!` or `FullSearch::Index.rebuild!` manually). This guarantees that `source:` blocks run against fully-loaded model definitions, avoiding load-order issues where associations or methods defined later in the class body are not yet available.
+
 > **Note on rebuild locking:** The `lock_rebuilds` option prevents concurrent rebuilds
 > within the same process/connection. For multi-process or multi-host deployments,
 > run `full_search:rebuild` from a single deployment step.
@@ -146,6 +150,18 @@ If you're not on Solid Queue, most job frameworks support recurring schedules vi
 
 Every FTS table stores a SHA256 digest of its DSL configuration in the `full_search_index_versions` table. When the DSL changes (e.g., adding a field), the stored hash no longer matches, and `rebuild!` is triggered automatically (if `auto_rebuild_schema` is true) to bring the index in line with the new definition. If `auto_rebuild_schema` is false, queries raise `ConfigChangedError` when the hash doesn't match (or log a warning and fall back if configured with `:log_and_fallback`).
 
+### Query-time auto-rebuild in local environments
+
+By default, the generated initializer also enables `auto_rebuild_on_stale_query` in local environments:
+
+```ruby
+FullSearch.configure do |config|
+  config.auto_rebuild_on_stale_query = Rails.env.local?
+end
+```
+
+When this option is `true`, the first search that detects a stale index automatically calls `FullSearch::Index.rebuild_if_needed!` and then proceeds with the query, so you don't need to restart the server or run a Rake task during iterative development. In production, this defaults to `false`; use `full_search:rebuild` or boot-time `auto_rebuild_schema` instead.
+
 ## Query operators
 
 ```ruby

data/lib/full_search/callbacks.rb

@@ -53,18 +53,22 @@ module FullSearch
       field = dsl.fields.find { |f| f.name == field_name }
       return unless field&.source
 
-      value = record.instance_exec(&field.source)
+      value = FullSearch::Model.evaluate_source(record, field)
       table = qt(FullSearch::Index.fts_table_name(record.class))
       conn = ActiveRecord::Base.connection
       conn.execute(
         "UPDATE #{table} SET #{qc(field.name)} = #{q(value.to_s)} WHERE rowid = #{q(record.id)}"
       )
+    rescue => e
+      raise unless e.message.include?("no such table")
     end
 
     def self.remove_record!(record)
       table = qt(FullSearch::Index.fts_table_name(record.class))
       conn = ActiveRecord::Base.connection
       conn.execute("DELETE FROM #{table} WHERE rowid = #{q(record.id)}")
+    rescue => e
+      raise unless e.message.include?("no such table")
     end
 
     def self.reindex_dependents!(parent_record, dependent_model, field)

data/lib/full_search/config.rb

@@ -2,7 +2,7 @@
 
 module FullSearch
   class Config
-    attr_accessor :auto_rebuild_schema, :stale_query_behavior, :lock_rebuilds, :default_async_reindex, :default_tokenizer
+    attr_accessor :auto_rebuild_schema, :stale_query_behavior, :lock_rebuilds, :default_async_reindex, :default_tokenizer, :auto_rebuild_on_stale_query
 
     def initialize
       @auto_rebuild_schema = false
@@ -10,6 +10,7 @@ module FullSearch
       @lock_rebuilds = true
       @default_async_reindex = true
       @default_tokenizer = "unicode61"
+      @auto_rebuild_on_stale_query = false
     end
   end
 

data/lib/full_search/dsl.rb

@@ -21,46 +21,46 @@ module FullSearch
 
     def field(name, weight: 1, source: nil, reindex_on: nil, async: FullSearch.config.default_async_reindex, as: nil, version: nil)
       unless valid_name?(name)
-        raise InvalidFieldError, "Invalid field name: #{name.inspect}"
+        raise InvalidFieldError, "#{model_class.name}: invalid field name #{name.inspect}"
       end
       if as && !valid_name?(as)
-        raise InvalidFieldError, "Invalid field alias (as): #{as.inspect}"
+        raise InvalidFieldError, "#{model_class.name}: invalid field alias (as): #{as.inspect}"
       end
       str = name.to_s
-      raise InvalidFieldError, "Duplicate field name: #{name.inspect}" if fields.any? { |f| f.name == str }
-      raise InvalidFieldError, "Field name conflicts with filter: #{name.inspect}" if filters.any? { |f| f.name == str }
+      raise InvalidFieldError, "#{model_class.name}: duplicate field name #{name.inspect}" if fields.any? { |f| f.name == str }
+      raise InvalidFieldError, "#{model_class.name}: field name #{name.inspect} conflicts with existing filter" if filters.any? { |f| f.name == str }
       @fields << Field.new(name: str, weight: weight.to_i, source: source, reindex_on: reindex_on&.to_s, async: async, as: as&.to_s, version: version)
     end
 
     def exact_match(name, source: -> { public_send(name) }, version: nil)
       unless valid_name?(name)
-        raise InvalidFieldError, "Invalid exact_match name: #{name.inspect}"
+        raise InvalidFieldError, "#{model_class.name}: invalid exact_match name #{name.inspect}"
       end
       str = name.to_s
-      raise InvalidFieldError, "Duplicate exact_match name: #{name.inspect}" if exact_matches.any? { |e| e.name == str }
+      raise InvalidFieldError, "#{model_class.name}: duplicate exact_match name #{name.inspect}" if exact_matches.any? { |e| e.name == str }
       @exact_matches << ExactMatch.new(name: str, source: source, version: version)
     end
 
     def rank_by(column, direction = :desc)
       unless valid_name?(column)
-        raise InvalidFieldError, "Invalid rank_by column: #{column.inspect}"
+        raise InvalidFieldError, "#{model_class.name}: invalid rank_by column #{column.inspect}"
       end
       dir = direction.to_s.downcase
       unless %w[asc desc].include?(dir)
-        raise InvalidFieldError, "Invalid rank_by direction: #{direction.inspect}. Use :asc or :desc."
+        raise InvalidFieldError, "#{model_class.name}: invalid rank_by direction #{direction.inspect}. Use :asc or :desc."
       end
       str = column.to_s
-      raise InvalidFieldError, "Duplicate rank_by column: #{column.inspect}" if rank_bys.any? { |r| r.column == str }
+      raise InvalidFieldError, "#{model_class.name}: duplicate rank_by column #{column.inspect}" if rank_bys.any? { |r| r.column == str }
       @rank_bys << RankBy.new(column: str, direction: dir.to_sym)
     end
 
     def filter(name, required: false)
       unless valid_name?(name)
-        raise InvalidFieldError, "Invalid filter name: #{name.inspect}"
+        raise InvalidFieldError, "#{model_class.name}: invalid filter name #{name.inspect}"
       end
       str = name.to_s
-      raise InvalidFieldError, "Duplicate filter name: #{name.inspect}" if filters.any? { |f| f.name == str }
-      raise InvalidFieldError, "Filter name conflicts with field: #{name.inspect}" if fields.any? { |f| f.name == str }
+      raise InvalidFieldError, "#{model_class.name}: duplicate filter name #{name.inspect}" if filters.any? { |f| f.name == str }
+      raise InvalidFieldError, "#{model_class.name}: filter name #{name.inspect} conflicts with existing field" if fields.any? { |f| f.name == str }
       @filters << Filter.new(name: str, required: required)
     end
 

data/lib/full_search/index.rb

@@ -14,7 +14,13 @@ end
 module FullSearch
   class Index
     class << self
+      def verified_tables
+        @verified_tables ||= Set.new
+      end
+
       def ensure_table!(model)
+        return if model.respond_to?(:table_name) && verified_tables.include?(model.table_name)
+
         sqlite!(model)
 
         conn = connection
@@ -44,6 +50,8 @@ module FullSearch
 
         store_config_hash!(model)
         ensure_triggers!(model) if model_table_exists?(model)
+
+        verified_tables.add(model.table_name)
       end
 
       def rebuild!(model)
@@ -70,6 +78,7 @@ module FullSearch
           create_triggers!(model)
           optimize!(model)
           store_config_hash!(model, rebuilt_at: Time.current)
+          verified_tables.add(model.table_name)
         end
       end
 
@@ -103,6 +112,7 @@ module FullSearch
       end
 
       def drop!(model)
+        verified_tables.delete(model.table_name)
         sqlite!(model)
         drop_triggers!(model)
         connection.execute("DROP TABLE IF EXISTS #{qt(fts_table_name(model))};")

data/lib/full_search/model.rb

@@ -10,7 +10,6 @@ module FullSearch
           @full_search_dsl ||= FullSearch::Dsl.new(self)
           @full_search_dsl.tokenize(query_or_options[:tokenize]) if query_or_options.is_a?(Hash) && query_or_options.key?(:tokenize)
           @full_search_dsl.instance_eval(&block) if block_given?
-          FullSearch::Index.ensure_table!(self)
           FullSearch::Callbacks.install!(self)
           include InstanceMethods
 
@@ -48,6 +47,16 @@ module FullSearch
       end
     end
 
+    def self.evaluate_source(record, field)
+      if field.source
+        record.instance_exec(&field.source)
+      else
+        record.public_send(field.name)
+      end
+    rescue NameError => e
+      raise e.class, "#{record.class.name}: full_search source block for field #{field.name.inspect} failed: #{e.message}"
+    end
+
     module InstanceMethods
       attr_accessor :full_search_snippet, :full_search_highlight_fields
 
@@ -56,7 +65,7 @@ module FullSearch
         field = dsl.fields.find { |f| f.name == field_name.to_s || f.as == field_name.to_s }
         return nil unless field
 
-        field.source ? instance_exec(&field.source) : public_send(field.name)
+        FullSearch::Model.evaluate_source(self, field)
       end
     end
   end

data/lib/full_search/search.rb

@@ -76,13 +76,18 @@ module FullSearch
       stored = FullSearch::Index.stored_config_hash(model)
       return unless stored
 
-      if stored != dsl.config_hash
-        case FullSearch.config.stale_query_behavior
-        when :raise
-          raise ConfigChangedError, "FTS index for #{model.table_name} is stale; run full_search:rebuild"
-        when :log_and_fallback
-          Rails.logger.warn("[full_search] FTS index for #{model.table_name} is stale; results may be incomplete")
-        end
+      return if stored == dsl.config_hash
+
+      if FullSearch.config.auto_rebuild_on_stale_query
+        FullSearch::Index.rebuild_if_needed!(model)
+        return
+      end
+
+      case FullSearch.config.stale_query_behavior
+      when :raise
+        raise ConfigChangedError, "FTS index for #{model.table_name} is stale; run full_search:rebuild"
+      when :log_and_fallback
+        Rails.logger.warn("[full_search] FTS index for #{model.table_name} is stale; results may be incomplete")
       end
     end
 

data/lib/full_search/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module FullSearch
-  VERSION = "0.3.1"
+  VERSION = "0.3.3"
 end

data/lib/full_search.rb

@@ -47,6 +47,13 @@ module FullSearch
     def optimize!
       models.each { |model| Index.optimize!(model) }
     end
+
+    def setup!
+      models.each do |model|
+        Index.ensure_table!(model)
+        Callbacks.install!(model)
+      end
+    end
   end
 end
 

data/lib/generators/full_search/install/templates/full_search.rb

@@ -3,6 +3,8 @@
 FullSearch.configure do |config|
   config.auto_rebuild_schema = Rails.env.local?
 
+  config.auto_rebuild_on_stale_query = Rails.env.local?
+
   config.stale_query_behavior = Rails.env.production? ? :log_and_fallback : :raise
 
   config.lock_rebuilds = true

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: full_search
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.3.3
 platform: ruby
 authors:
 - Ben D'Angelo
@@ -176,7 +176,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.1.0
+      version: 3.2.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="