full_search 0.3.5 → 0.3.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b3b466311e2305f90987a48ff58cee59f4c81af6e960b5fcd2fe09cf845b985b
-  data.tar.gz: 1d355e22aa06d280d984d7da1df90e57a8ca4a5f5676b7870424f2b048c051ba
+  metadata.gz: 01b6db287587e57e3bc4f7226eff10257303eadf30c6a6a64e53be1e2e52afb5
+  data.tar.gz: 01ec5e01cf2d479245338c5a7ab23f778a9f953c78c7a0a1ab4f428a4472c98c
 SHA512:
-  metadata.gz: 9489ff8c9bf04c59b6380cd1810871a39a947421754379ac6fb1c1cb36cbf7850a753d0a7354e25f38b591aeae63cbb05cd7d8c0f187bb84ba6ef191aba19755
-  data.tar.gz: a23ce1270f3ac088b02774a43178fb277811e7df65a7d518f3fde4b8899cfb2db3f07164c72ea75ec26bb3b8ed9ef29b94d05aa53009ef1f82dd9d1bb4d14f79
+  metadata.gz: 6a3bd6143a47be3e7abd89df28506f247ee562205372ee9b5bedf6064d463413e212b7bca67dffb3e980531963e55984750adfed5504cf70b7e0dc7fa250185b
+  data.tar.gz: 3b793c3bfd872cf1a247a18c030ade28433d16d40bc71438d35dc79be2cd306d15ec79f0afc371c0866ef9feeca8d3292ed9f8af35c9bb6c572b8073be88a12b

data/README.md

@@ -125,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:
@@ -162,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. |
@@ -223,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/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

@@ -174,6 +174,10 @@ module FullSearch
         row&.[]("config_hash")
       end
 
+      def missing_table?(model)
+        !table_exists?(model)
+      end
+
       private
 
       def connection

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.5"
+  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.5
+  version: 0.3.6
 platform: ruby
 authors:
 - Ben D'Angelo