full_search 0.3.4 → 0.3.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ed7b0998cc6d4014ab815a6152ba07562da34c98b3cca3aa3886e63fb45acc5b
-  data.tar.gz: f29430f7ac4d5a3175e1eb46c803aa3a9b9ce68e3e930f2f75ecfd8ad03242d7
+  metadata.gz: 01b6db287587e57e3bc4f7226eff10257303eadf30c6a6a64e53be1e2e52afb5
+  data.tar.gz: 01ec5e01cf2d479245338c5a7ab23f778a9f953c78c7a0a1ab4f428a4472c98c
 SHA512:
-  metadata.gz: cce0189e77ec25883ad52dae321dea4f99cb8f1f245f331b5cdeb94f6c3554c675e84b0214e4036ca1c01fc53f22e41594324729d39688c8e48d0bcd791356f3
-  data.tar.gz: a9d3f31295d082892dc5cf797f2d38a9cb8151629f9e6d2c0ac0ad1b8dcfeb5e732b740fb91d138d0b3a7f1db513c72c36aa61a1410d2b052bd57bda0790c5dd
+  metadata.gz: 6a3bd6143a47be3e7abd89df28506f247ee562205372ee9b5bedf6064d463413e212b7bca67dffb3e980531963e55984750adfed5504cf70b7e0dc7fa250185b
+  data.tar.gz: 3b793c3bfd872cf1a247a18c030ade28433d16d40bc71438d35dc79be2cd306d15ec79f0afc371c0866ef9feeca8d3292ed9f8af35c9bb6c572b8073be88a12b

data/README.md

@@ -45,6 +45,27 @@ end
 Customer.search("sam", filters: { account_id: 1 }).page(params[:page])
 ```
 
+### Field aliasing with `as:`
+
+Use `as:` to give a field a different column name in the FTS table. This is useful when
+the model's accessor name differs from the desired search index key — for example, storing
+a computed value (last 8 chars of VIN) in a shorter or semantically-named column:
+
+```ruby
+class Vehicle < ApplicationRecord
+  full_search do
+    field :vin_last8, weight: 2, source: -> { vin&.last(8)&.upcase }, as: :vin
+    field :make, weight: 4
+    field :model, weight: 4
+    filter :account_id, required: true
+    highlight
+  end
+end
+```
+
+The FTS table stores the value under `vin` (not `vin_last8`). Search results highlight
+keyed as `vin`, and the `full_search_text_for(:vin)` lookup works as expected.
+
 ## Features
 
 - Declarative `full_search` DSL with `search` / `full_search` query methods
@@ -104,6 +125,22 @@ These two operations are often confused:
 > within the same process/connection. For multi-process or multi-host deployments,
 > run `full_search:rebuild` from a single deployment step.
 
+### First-deploy setup
+
+After `db:prepare` creates your application tables, FTS virtual tables like `customers_fts` do not yet exist. Run `full_search:prepare` to create them:
+
+```bash
+bin/rails full_search:prepare
+```
+
+For Docker-based deployments, add this to your entrypoint script after `db:prepare:with_data`:
+
+```bash
+./bin/rails full_search:prepare
+```
+
+The `full_search:prepare` task is idempotent — it only creates missing tables and installs triggers. It will not drop or rebuild existing indexes, making it safe to run on every deploy.
+
 ### Auto-rebuild on app load
 
 When `auto_rebuild_schema` is enabled (default in the generated initializer), the railtie hooks into Rails `after_initialize` and:
@@ -141,6 +178,7 @@ bin/rails full_search:reset
 
 | Task | Description |
 |------|-------------|
+| `full_search:prepare` | Idempotent setup — creates missing FTS tables and triggers without dropping existing ones. Safe to run on every deploy. Add to your Docker entrypoint after `db:prepare:with_data` for first-deploy automation. |
 | `full_search:rebuild` | Drops and recreates the FTS virtual table only when the DSL config hash has changed (safe for production). Pass model names to target specific tables. |
 | `full_search:reset` | Force a full rebuild — drops and recreates all FTS tables regardless of config hash. Use when data may be out of sync. |
 | `full_search:optimize` | Run FTS5 [`optimize`](https://www.sqlite.org/fts5.html#the_optimize_command) to merge b-tree segments. Useful after bulk updates. |
@@ -202,6 +240,17 @@ 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.
 
+### Missing table error
+
+When the FTS table does not exist and a search is attempted, `full_search` raises `MissingTableError` with a clear message:
+
+```
+FullSearch::MissingTableError: FTS table `customers_fts` does not exist.
+Run `bin/rails full_search:prepare` to create it.
+```
+
+This mirrors how Rails handles missing database tables — you see the error, run the task, and move on. Add `full_search:prepare` to your deploy pipeline or Docker entrypoint after `db:prepare:with_data` to prevent the error in production.
+
 ## Query operators
 
 ```ruby

data/lib/full_search/callbacks.rb

@@ -66,7 +66,7 @@ module FullSearch
       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)}"
+        "UPDATE #{table} SET #{qc(field.as || field.name)} = #{q(value.to_s)} WHERE rowid = #{q(record.id)}"
       )
     rescue => e
       raise unless e.message.include?("no such table")

data/lib/full_search/config.rb

@@ -3,8 +3,8 @@
 module FullSearch
   class Config
     attr_accessor :auto_rebuild_schema, :stale_query_behavior, :lock_rebuilds,
-                  :default_async_reindex, :default_async_source_reindex,
-                  :default_tokenizer, :auto_rebuild_on_stale_query
+      :default_async_reindex, :default_async_source_reindex,
+      :default_tokenizer, :auto_rebuild_on_stale_query
 
     def initialize
       @auto_rebuild_schema = false

data/lib/full_search/dsl.rb

@@ -20,9 +20,9 @@ module FullSearch
     end
 
     def field(name, weight: 1, source: nil, reindex_on: nil,
-              async: FullSearch.config.default_async_reindex,
-              async_source: FullSearch.config.default_async_source_reindex,
-              as: nil, version: nil)
+      async: FullSearch.config.default_async_reindex,
+      async_source: FullSearch.config.default_async_source_reindex,
+      as: nil, version: nil)
       unless valid_name?(name)
         raise InvalidFieldError, "#{model_class.name}: invalid field name #{name.inspect}"
       end

data/lib/full_search/errors.rb

@@ -8,5 +8,6 @@ module FullSearch
   class InvalidFieldError < Error; end
   class NotConfiguredError < Error; end
   class UnsupportedDatabaseError < Error; end
+  class MissingTableError < Error; end
   class InvalidQueryError < Error; end
 end

data/lib/full_search/index.rb

@@ -46,9 +46,9 @@ module FullSearch
           conn.execute(backfill_sql(model)) if fts_was_created
           conn.execute(backfill_trigram_sql(model)) if trigram_was_created
           reindex_source_fields!(model) if dsl.fields.any?(&:source)
+          store_config_hash!(model)
         end
 
-        store_config_hash!(model)
         ensure_triggers!(model) if model_table_exists?(model)
 
         verified_tables.add(model.table_name)
@@ -174,6 +174,10 @@ module FullSearch
         row&.[]("config_hash")
       end
 
+      def missing_table?(model)
+        !table_exists?(model)
+      end
+
       private
 
       def connection
@@ -188,6 +192,10 @@ module FullSearch
         connection.quote_table_name(name)
       end
 
+      def column_name(col)
+        (col.respond_to?(:as) && col.as) ? col.as : col.name
+      end
+
       def qc(name)
         connection.quote_column_name(name)
       end
@@ -223,7 +231,7 @@ module FullSearch
       def create_virtual_table_sql(model)
         dsl = model.full_search_dsl
         columns = (dsl.fields + dsl.filters.map { |f| FilterColumnPlaceholder.new(name: f.name) } + extra_columns(model))
-        column_list = columns.map { |c| (c.respond_to?(:unindexed?) && c.unindexed?) ? "#{qc(c.name)} UNINDEXED" : qc(c.name) }.join(", ")
+        column_list = columns.map { |c| (c.respond_to?(:unindexed?) && c.unindexed?) ? "#{qc(column_name(c))} UNINDEXED" : qc(column_name(c)) }.join(", ")
 
         "CREATE VIRTUAL TABLE #{qt(fts_table_name(model))} USING fts5(#{column_list}, tokenize='#{dsl.tokenize}');"
       end
@@ -244,7 +252,7 @@ module FullSearch
         where_clause = dsl.conditional_index? ? " WHERE (#{dsl.index_if_sql})" : ""
 
         <<~SQL
-          INSERT INTO #{qt(fts_table_name(model))}(rowid, #{cols.map { |c| qc(c.name) }.join(", ")})
+          INSERT INTO #{qt(fts_table_name(model))}(rowid, #{cols.map { |c| qc(column_name(c)) }.join(", ")})
           SELECT #{qt(model.table_name)}.id, #{select} FROM #{qt(model.table_name)}#{where_clause};
         SQL
       end
@@ -369,7 +377,7 @@ module FullSearch
       def create_trigram_virtual_table_sql(model)
         dsl = model.full_search_dsl
         columns = (dsl.fields + dsl.filters.map { |f| FilterColumnPlaceholder.new(name: f.name) } + extra_columns(model))
-        column_list = columns.map { |c| (c.respond_to?(:unindexed?) && c.unindexed?) ? "#{qc(c.name)} UNINDEXED" : qc(c.name) }.join(", ")
+        column_list = columns.map { |c| (c.respond_to?(:unindexed?) && c.unindexed?) ? "#{qc(column_name(c))} UNINDEXED" : qc(column_name(c)) }.join(", ")
 
         "CREATE VIRTUAL TABLE #{qt(trigram_table_name(model))} USING fts5(#{column_list}, tokenize='trigram');"
       end
@@ -390,7 +398,7 @@ module FullSearch
         where_clause = dsl.conditional_index? ? " WHERE (#{dsl.index_if_sql})" : ""
 
         <<~SQL
-          INSERT INTO #{qt(trigram_table_name(model))}(rowid, #{cols.map { |c| qc(c.name) }.join(", ")})
+          INSERT INTO #{qt(trigram_table_name(model))}(rowid, #{cols.map { |c| qc(column_name(c)) }.join(", ")})
           SELECT #{qt(model.table_name)}.id, #{select} FROM #{qt(model.table_name)}#{where_clause};
         SQL
       end
@@ -469,7 +477,7 @@ module FullSearch
       end
 
       def col_names(cols)
-        cols.map { |c| qc(c.name) }.join(", ")
+        cols.map { |c| qc(column_name(c)) }.join(", ")
       end
 
       def column_ref(col, prefix:)

data/lib/full_search/search.rb

@@ -78,7 +78,15 @@ module FullSearch
     end
 
     def check_stale_config!
-      stored = FullSearch::Index.stored_config_hash(model)
+      if FullSearch::Index.missing_table?(model)
+        raise MissingTableError, "FTS table `#{FullSearch::Index.fts_table_name(model)}` does not exist. Run `bin/rails full_search:prepare` to create it."
+      end
+
+      stored = begin
+        FullSearch::Index.stored_config_hash(model)
+      rescue StandardError
+        nil
+      end
       return unless stored
 
       return if stored == dsl.config_hash

data/lib/full_search/version.rb

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

data/lib/tasks/full_search.rake

@@ -17,6 +17,29 @@ def resolve_full_search_models(args)
 end
 
 namespace :full_search do
+  desc "Create full_search FTS tables and triggers if missing (idempotent, safe for first deploy)"
+  task :prepare, [:models] => :environment do |_t, args|
+    Rails.application.eager_load!
+
+    models = if args[:models]
+      args[:models].split(",").map do |name|
+        klass = begin
+          name.singularize.camelize.constantize
+        rescue NameError, LoadError
+          FullSearch.models.find { |m| m.table_name == name }
+        end
+        klass
+      end.compact
+    else
+      FullSearch.models
+    end
+
+    FullSearch.setup!
+    models.each do |model|
+      puts "Prepared #{FullSearch::Index.fts_table_name(model)}"
+    end
+  end
+
   desc "Rebuild indexes when DSL has changed (checks config hash; safe for production)"
   task :rebuild, [:models] => :environment do |_t, args|
     Rails.application.eager_load!

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: full_search
 version: !ruby/object:Gem::Version
-  version: 0.3.4
+  version: 0.3.6
 platform: ruby
 authors:
 - Ben D'Angelo