activerecord-searchable 0.1.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 849c4ea5440e942aba0f1f2615df5640b4cb3ee50a22531d66c0e7e9f8d8376c
+  data.tar.gz: 16428cca11f8da34698b8ea9fbd9542b206b06e2e54621358bebe3fd37314263
+SHA512:
+  metadata.gz: 5e86d34575d64f15438a07aeef1254ccd2a187cc4b4b27f3c674cb76960033f9de83e046f52a32ea12e6b2aa48b4b108f0cd631289b28c42583b136053eaf4d3
+  data.tar.gz: c379ffb9f084dbc666d9966523489e86e607c2cdf3996108d6eeeb58761ac49f070b54daceb79bf7b04ba1eaf725550fc379956b609237bb0182bd45fa989be3

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2025 Matt Lins
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,368 @@
+# ActiveRecord::Searchable
+
+Database-native full-text search for Rails 8+ using SQLite FTS5, with zero external dependencies.
+
+## Features
+
+- **Zero Dependencies**: Uses SQLite's built-in FTS5 extension
+- **Rails Native**: Feels like ActiveRecord, works with existing scopes
+- **Automatic Sync**: Search index updates via callbacks, always consistent
+- **Query Sanitization**: Handles invalid FTS syntax gracefully
+- **Highlighting & Snippets**: Built-in support for match highlighting
+- **BM25 Ranking**: Relevance scoring with configurable field weights
+
+## Requirements
+
+- Rails 8.0+ (for `create_virtual_table` support)
+- Ruby 3.2+
+- SQLite 3.8.0+ with FTS5 extension
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "activerecord-searchable"
+```
+
+Run:
+
+```bash
+bundle install
+```
+
+## Quick Start
+
+### 1. Add searchable to your model
+
+```ruby
+class Article < ApplicationRecord
+  include ActiveRecord::Searchable
+
+  searchable do
+    field :title, weight: 2.0  # Title matches ranked 2x higher
+    field :body
+  end
+end
+```
+
+### 2. Generate the migration
+
+```bash
+rails generate searchable:migration Article
+```
+
+This creates:
+
+```ruby
+class CreateArticleSearchIndex < ActiveRecord::Migration[8.0]
+  def change
+    create_virtual_table :article_search_index, :fts5, [
+      "title",
+      "body",
+      "tokenize='porter'"
+    ]
+
+    Article.reindex_all
+  end
+end
+```
+
+### 3. Run the migration
+
+```bash
+rails db:migrate
+```
+
+### 4. Search!
+
+```ruby
+# Basic search
+Article.search("ruby on rails")
+
+# With match highlighting
+results = Article.search("ruby on rails", matches: true)
+results.first.title_highlight  # => "Building with <mark>Ruby on Rails</mark>"
+results.first.body_snippet     # => "...learn <mark>Ruby on Rails</mark>..."
+
+# Chain with other scopes
+Article.published.search("rails").where(author: current_user).limit(10)
+```
+
+## Configuration
+
+### Field Options
+
+```ruby
+searchable do
+  # Basic field
+  field :title
+end
+
+searchable do
+  # Field with weight (for ranking)
+  field :title, weight: 2.0
+  # Field with custom extraction method
+  field :body, via: :searchable_content
+end
+
+searchable do
+  # Multiple fields
+  field :title, weight: 2.0
+  field :body
+  field :author_name, via: :author_full_name
+end
+```
+
+### Custom Content Extraction
+
+Use `via:` to extract content from a method instead of an attribute:
+
+```ruby
+class Message < ApplicationRecord
+  include ActiveRecord::Searchable
+
+  has_rich_text :body
+
+  searchable do
+    field :body, via: :plain_text_body
+  end
+
+  def plain_text_body
+    body.to_plain_text
+  end
+end
+```
+
+### Conditional Indexing
+
+Define a `searchable?` method to control which records get indexed:
+
+```ruby
+class Article < ApplicationRecord
+  include ActiveRecord::Searchable
+
+  searchable do
+    field :title
+    field :body
+  end
+
+  def searchable?
+    published? && body.present?
+  end
+end
+```
+
+## Searching
+
+### Basic Search
+
+```ruby
+Article.search("ruby programming")
+```
+
+Returns an `ActiveRecord::Relation` with matching records, ordered by relevance (BM25).
+
+### Search with Matches
+
+```ruby
+# Smart defaults - first field highlighted, second field snippeted
+results = Article.search("ruby programming", matches: true)
+results.first.title_highlight  # Full content with <mark> tags
+results.first.body_snippet     # ~20 word excerpt with <mark> tags
+
+# Explicit control - specify which fields use highlight vs snippet
+results = Article.search("ruby programming", matches: {
+  highlight: [:title, :tags],
+  snippet: [:body, :comments]
+})
+results.first.title_highlight  # Full title with <mark> tags
+results.first.tags_highlight   # Full tags with <mark> tags
+results.first.body_snippet     # Excerpt of body with <mark> tags
+results.first.comments_snippet # Excerpt of comments with <mark> tags
+
+# Only highlights, no snippets
+results = Article.search("ruby", matches: { highlight: [:title] })
+results.first.title_highlight  # Full title with <mark> tags
+# No snippet columns generated
+
+# No matches
+results = Article.search("ruby")
+# No highlight or snippet columns, just filtered/ranked records
+```
+
+Match columns use different suffixes based on the function:
+- `_highlight` - Full content with `<mark>` tags (SQLite `highlight()` function)
+- `_snippet` - Excerpt (~20 words) with `<mark>` tags (SQLite `snippet()` function)
+
+**Smart defaults** (`matches: true`):
+- First field → `_highlight`
+- Second field → `_snippet`
+- Other fields → no match columns
+
+### Query Sanitization
+
+The gem automatically sanitizes queries to prevent FTS syntax errors:
+
+```ruby
+Article.search('"unbalanced quote')  # Works - quotes removed
+Article.search('test & invalid')     # Works - invalid chars removed
+Article.search('')                   # Returns none (empty relation)
+```
+
+### Chaining Scopes
+
+Search integrates seamlessly with ActiveRecord:
+
+```ruby
+Article.published
+  .search("rails")
+  .where(author: current_user)
+  .order(created_at: :desc)
+  .limit(20)
+```
+
+## Index Management
+
+### Automatic Updates
+
+The search index updates automatically via callbacks:
+
+```ruby
+article = Article.create!(title: "Test", body: "Content")  # Indexed
+article.update!(title: "Updated")                          # Re-indexed
+article.destroy                                            # Removed from index
+```
+
+### Manual Reindexing
+
+Reindex a single record:
+
+```ruby
+article.reindex
+```
+
+Reindex all records:
+
+```ruby
+Article.reindex_all
+```
+
+The `reindex_all` method processes records in batches (1000 at a time by default) to prevent memory issues with large datasets. This is safe for tables with millions of records.
+
+### Custom Reindexing
+
+For advanced needs like background jobs, progress tracking, or custom batch sizes, override `reindex_all`:
+
+```ruby
+class Article < ApplicationRecord
+  include ActiveRecord::Searchable
+
+  searchable do
+    field :title
+    field :body
+  end
+
+  # Queue reindexing jobs in the background
+  def self.reindex_all
+    find_each do |article|
+      ReindexJob.perform_later(article.id)
+    end
+  end
+end
+```
+
+## How It Works
+
+### FTS5 Virtual Tables
+
+The gem creates a virtual table using SQLite's FTS5 extension:
+
+```sql
+CREATE VIRTUAL TABLE article_search_index USING fts5(
+  title,
+  body,
+  tokenize='porter'
+);
+```
+
+### Lifecycle Callbacks
+
+When you include `ActiveRecord::Searchable`, the gem adds callbacks:
+
+- `after_create_commit` → Insert into FTS table
+- `after_update_commit` → Update FTS table (or insert if missing)
+- `after_destroy_commit` → Delete from FTS table
+
+### Search Queries
+
+Search generates SQL like:
+
+```sql
+SELECT articles.*
+FROM articles
+JOIN article_search_index ON articles.id = article_search_index.rowid
+WHERE article_search_index MATCH 'ruby programming'
+ORDER BY bm25(article_search_index, 2.0, 1.0)
+```
+
+With matches:
+
+```sql
+SELECT articles.*,
+  highlight(article_search_index, 0, '<mark>', '</mark>') as title_highlight,
+  snippet(article_search_index, 1, '<mark>', '</mark>', '...', 20) as body_snippet
+FROM articles
+JOIN article_search_index ON articles.id = article_search_index.rowid
+WHERE article_search_index MATCH 'ruby programming'
+ORDER BY bm25(article_search_index, 2.0, 1.0)
+```
+
+## Advanced Usage
+
+### Field Weights & Ranking
+
+Field weights control relevance ranking. Higher weights = higher rank for matches:
+
+```ruby
+searchable do
+  field :title, weight: 3.0   # Title matches rank highest
+  field :summary, weight: 2.0 # Summary matches rank medium
+  field :body, weight: 1.0    # Body matches rank lowest
+end
+```
+
+Uses SQLite's BM25 algorithm for scoring.
+
+### Porter Stemming
+
+The gem uses Porter stemming by default (via `tokenize='porter'`). This means:
+
+- "running" matches "run"
+- "developer" matches "develop"
+- "testing" matches "test"
+
+### Transaction Safety
+
+Index updates happen in `after_commit` callbacks, ensuring the FTS table stays consistent with your data even if transactions roll back.
+
+## Roadmap
+
+- PostgreSQL adapter (using `tsvector` and `tsquery`)
+- MySQL adapter (using `FULLTEXT` indexes)
+- Advanced query syntax support (FTS5 operators: AND, OR, NOT, prefix matching)
+- Multi-language support
+
+## Credits
+
+Inspired by [37signals ONCE products](https://once.com):
+- [Campfire](https://once.com/campfire) - Team chat
+- [Writebook](https://once.com/writebook) - Publishing platform
+
+## Contributing
+
+Bug reports and pull requests welcome on GitHub.
+
+## License
+
+MIT License. See MIT-LICENSE for details.

data/Rakefile

@@ -0,0 +1,11 @@
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+  t.verbose = true
+end
+
+task default: :test

data/lib/activerecord/searchable/adapter.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  module Searchable
+    class Adapter
+      def self.for(connection)
+        case connection.adapter_name
+        when /sqlite/i
+          Adapters::SQLite.new(connection)
+        else
+          raise NotImplementedError,
+            "Search not supported for #{connection.adapter_name}. " \
+            "Currently only SQLite with FTS5 is supported."
+        end
+      end
+
+      # Abstract methods - must be implemented by subclasses
+      def join_clause(config)
+        raise NotImplementedError, "#{self.class} must implement ##{__method__}"
+      end
+
+      def where_clause(config)
+        raise NotImplementedError, "#{self.class} must implement ##{__method__}"
+      end
+
+      def select_clause_for_highlights(config)
+        raise NotImplementedError, "#{self.class} must implement ##{__method__}"
+      end
+
+      def ranking_order_clause(config)
+        raise NotImplementedError, "#{self.class} must implement ##{__method__}"
+      end
+
+      def insert_sql(config, record_id, values)
+        raise NotImplementedError, "#{self.class} must implement ##{__method__}"
+      end
+
+      def update_sql(config, record_id, values)
+        raise NotImplementedError, "#{self.class} must implement ##{__method__}"
+      end
+
+      def delete_sql(config, record_id)
+        raise NotImplementedError, "#{self.class} must implement ##{__method__}"
+      end
+    end
+  end
+end

data/lib/activerecord/searchable/adapters/sqlite.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  module Searchable
+    module Adapters
+      class SQLite < Adapter
+        # Number of words to include in snippet output (context around match)
+        SNIPPET_WORD_COUNT = 20
+
+        # HTML tags used to mark highlighted matches in search results
+        HIGHLIGHT_START_TAG = "<mark>"
+        HIGHLIGHT_END_TAG = "</mark>"
+
+        attr_reader :connection
+
+        def initialize(connection)
+          @connection = connection
+        end
+
+        def join_clause(config)
+          table = config.model_class.table_name
+          search_table = config.search_table_name
+          "JOIN #{search_table} ON #{table}.id = #{search_table}.rowid"
+        end
+
+        def where_clause(config)
+          "#{config.search_table_name} MATCH ?"
+        end
+
+        def select_clause_for_matches(config, matches)
+          clauses = []
+
+          matches[:highlight].each do |field_name|
+            clause = build_match_clause(config, field_name, :highlight)
+            clauses << clause if clause
+          end
+
+          matches[:snippet].each do |field_name|
+            clause = build_match_clause(config, field_name, :snippet)
+            clauses << clause if clause
+          end
+
+          clauses
+        end
+
+        def ranking_order_clause(config)
+          weights = config.weights.join(", ")
+          Arel.sql("bm25(#{config.search_table_name}, #{weights})")
+        end
+
+        def insert_sql(config, record_id, values)
+          columns = ["rowid", *config.field_names].join(", ")
+          placeholders = (["?"] * (values.length + 1)).join(", ")
+          [
+            "INSERT INTO #{config.search_table_name}(#{columns}) VALUES (#{placeholders})",
+            record_id,
+            *values
+          ]
+        end
+
+        def update_sql(config, record_id, values)
+          set_clause = config.field_names.map { |name| "#{name} = ?" }.join(", ")
+          [
+            "UPDATE #{config.search_table_name} SET #{set_clause} WHERE rowid = ?",
+            *values,
+            record_id
+          ]
+        end
+
+        def delete_sql(config, record_id)
+          [
+            "DELETE FROM #{config.search_table_name} WHERE rowid = ?",
+            record_id
+          ]
+        end
+
+        def execute_with_result(connection, sql_array, model_class)
+          connection.execute(model_class.sanitize_sql(sql_array))
+          connection.raw_connection.changes.positive?
+        end
+
+        private
+
+        def build_match_clause(config, field_name, function_type)
+          field_index = config.fields.index { |f| f.name == field_name }
+          return nil unless field_index
+
+          case function_type
+          when :highlight
+            args = "#{config.search_table_name}, #{field_index}, '#{HIGHLIGHT_START_TAG}', '#{HIGHLIGHT_END_TAG}'"
+            "highlight(#{args}) as #{field_name}_highlight"
+          when :snippet
+            args = "#{config.search_table_name}, #{field_index}, '#{HIGHLIGHT_START_TAG}', '#{HIGHLIGHT_END_TAG}', '...', #{SNIPPET_WORD_COUNT}"
+            "snippet(#{args}) as #{field_name}_snippet"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/activerecord/searchable/configuration.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  module Searchable
+    class Configuration
+      attr_reader :fields, :model_class
+
+      def initialize(model_class)
+        @model_class = model_class
+        @fields = []
+      end
+
+      def field(name, weight: 1.0, via: nil)
+        @fields << Field.new(name: name, weight: weight, via: via)
+      end
+
+      def search_table_name
+        "#{model_class.table_name.singularize}_search_index"
+      end
+
+      def field_names
+        fields.map(&:name)
+      end
+
+      def weights
+        fields.map(&:weight)
+      end
+
+      def extract_content(record, field)
+        method_name = field.via || field.name
+        value = record.public_send(method_name)
+        value.to_s
+      rescue NoMethodError => e
+        raise ArgumentError, "Cannot extract content for field '#{field.name}': #{e.message}"
+      end
+    end
+  end
+end

data/lib/activerecord/searchable/field.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  module Searchable
+    Field = Data.define(:name, :weight, :via) do
+      def initialize(name:, weight: 1.0, via: nil)
+        super(name: name, weight: weight, via: via)
+      end
+    end
+  end
+end

data/lib/activerecord/searchable/index_manager.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  module Searchable
+    class IndexManager
+      attr_reader :model_class, :config, :adapter
+
+      def initialize(model_class, config, adapter)
+        @model_class = model_class
+        @config = config
+        @adapter = adapter
+      end
+
+      def create(record)
+        validate_schema!
+        values = extract_values(record)
+        sql = adapter.insert_sql(config, record.id, values)
+        execute_sql(sql)
+      end
+
+      def update(record)
+        validate_schema!
+        values = extract_values(record)
+        sql = adapter.update_sql(config, record.id, values)
+
+        # Atomic upsert pattern: Try UPDATE first (common case), fall back to INSERT if needed.
+        # This is more efficient than INSERT OR REPLACE, which would always do DELETE+INSERT.
+        # The transaction ensures no other process can INSERT between our UPDATE and INSERT attempts,
+        # preventing race conditions while maintaining optimal performance for the update-heavy path.
+        model_class.transaction do
+          updated = execute_sql(sql)
+          create(record) unless updated
+        end
+      end
+
+      def delete(record)
+        sql = adapter.delete_sql(config, record.id)
+        execute_sql(sql)
+      end
+
+      def reindex_all
+        model_class.find_each(&:reindex)
+      end
+
+      private
+
+      def validate_schema!
+        expected_fields = config.field_names.map(&:to_s)
+        actual_fields = get_table_columns
+
+        return if expected_fields.sort == actual_fields.sort
+
+        raise SchemaError, build_schema_error_message(expected_fields, actual_fields)
+      end
+
+      def get_table_columns
+        # Query SQLite's PRAGMA table_info to get column names from the FTS virtual table
+        result = model_class.connection.execute(
+          "PRAGMA table_info(#{config.search_table_name})"
+        )
+        result.map { |row| row["name"] }
+      rescue ActiveRecord::StatementInvalid
+        # Table doesn't exist yet
+        []
+      end
+
+      def build_schema_error_message(expected, actual)
+        <<~MSG.strip
+          FTS table schema mismatch detected for #{config.search_table_name}.
+
+          Expected fields: #{expected.join(', ')}
+          Actual fields: #{actual.join(', ')}
+
+          FTS5 virtual tables cannot be altered. To fix this:
+
+          1. Generate a migration to drop the old table:
+             rails generate migration Drop#{config.search_table_name.camelize}
+
+          2. Edit the migration to drop the table:
+             def change
+               drop_table :#{config.search_table_name}
+             end
+
+          3. Run the migration:
+             rails db:migrate
+
+          4. Regenerate the search table with updated fields:
+             rails generate searchable:migration #{model_class.name}
+             rails db:migrate
+        MSG
+      end
+
+      def extract_values(record)
+        config.fields.map do |field|
+          config.extract_content(record, field)
+        end
+      end
+
+      def execute_sql(sql)
+        adapter.execute_with_result(
+          model_class.connection,
+          sql,
+          model_class
+        )
+      end
+    end
+  end
+end

data/lib/activerecord/searchable/query_builder.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  module Searchable
+    class QueryBuilder
+      attr_reader :model_class, :config, :adapter
+
+      def initialize(model_class, config, adapter)
+        @model_class = model_class
+        @config = config
+        @adapter = adapter
+      end
+
+      def build_search_scope(relation, terms, matches: false)
+        sanitized_terms = sanitize_query(terms)
+
+        return relation.none if sanitized_terms.nil?
+
+        scope = relation
+          .joins(adapter.join_clause(config))
+          .where(adapter.where_clause(config), sanitized_terms)
+
+        # Only set select clause when we need extra columns for highlighting/snippets
+        # This allows ActiveRecord's .count to work correctly (it generates COUNT(*))
+        scope = scope.select(select_clause(matches)) if select_clause(matches)
+
+        scope.order(adapter.ranking_order_clause(config))
+      end
+
+      def sanitize_query(terms)
+        terms = terms.to_s
+        terms = remove_invalid_characters(terms)
+        terms = remove_unbalanced_quotes(terms)
+        terms = terms.strip.gsub(/\s+/, " ")  # Normalize whitespace
+        terms.presence
+      end
+
+      private
+
+      def parse_matches(matches)
+        case matches
+        when true
+          # Smart defaults: first field highlight, second field snippet
+          {
+            highlight: [config.fields[0]&.name].compact,
+            snippet: [config.fields[1]&.name].compact
+          }
+        when Hash
+          highlight_fields = Array(matches[:highlight])
+          snippet_fields = Array(matches[:snippet])
+
+          # Validate all fields exist
+          all_fields = highlight_fields + snippet_fields
+          valid_field_names = config.fields.map(&:name)
+          invalid_fields = all_fields - valid_field_names
+
+          if invalid_fields.any?
+            raise ArgumentError, "Invalid field names: #{invalid_fields.join(', ')}"
+          end
+
+          {
+            highlight: highlight_fields,
+            snippet: snippet_fields
+          }
+        when false, nil
+          nil
+        else
+          raise ArgumentError, "matches must be true, false, nil, or a Hash"
+        end
+      end
+
+      def select_clause(matches)
+        parsed_matches = parse_matches(matches)
+
+        if parsed_matches
+          [
+            "#{model_class.table_name}.*",
+            *adapter.select_clause_for_matches(config, parsed_matches)
+          ]
+        else
+          # Return nil to let ActiveRecord use default select behavior
+          # This allows .count to work correctly (generates COUNT(*) instead of COUNT(table.*))
+          nil
+        end
+      end
+
+      def remove_invalid_characters(terms)
+        # Allow only word characters (\w = letters, digits, underscore) and double quotes
+        # This prevents FTS5 syntax errors from special characters while preserving phrase searches
+        terms.gsub(/[^\w"]/, " ")
+      end
+
+      def remove_unbalanced_quotes(terms)
+        if terms.count('"').even?
+          terms
+        else
+          terms.gsub('"', " ")
+        end
+      end
+    end
+  end
+end

data/lib/activerecord/searchable/searchable.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  module Searchable
+    extend ActiveSupport::Concern
+
+    included do
+      # Validate Rails version
+      if defined?(Rails) && Rails.respond_to?(:version) && Rails.version < "8.0"
+        raise "activerecord-searchable requires Rails 8.0+ for create_virtual_table support"
+      end
+
+      class_attribute :search_configuration, default: Configuration.new(self)
+
+      after_create_commit  :create_in_search_index, if: :should_index?
+      after_update_commit  :update_in_search_index, if: :should_index?
+      after_destroy_commit :remove_from_search_index
+    end
+
+    class_methods do
+      def searchable(&block)
+        config = Configuration.new(self)
+        config.instance_eval(&block)
+        self.search_configuration = config
+
+        if config.fields.empty?
+          raise "No searchable fields configured. Add fields in the searchable block for #{name}"
+        end
+      end
+
+      def search(terms, matches: false)
+        QueryBuilder.new(self, search_configuration, adapter)
+          .build_search_scope(all, terms, matches: matches)
+      end
+
+      def reindex_all
+        all.find_each(&:reindex)
+      end
+
+      private
+
+      def adapter
+        @adapter ||= Adapter.for(connection)
+      end
+    end
+
+    def reindex
+      if should_index?
+        update_in_search_index
+      else
+        remove_from_search_index
+      end
+    end
+
+    private
+
+    def should_index?
+      return true unless respond_to?(:searchable?)
+      searchable?
+    end
+
+    def create_in_search_index
+      index_manager.create(self)
+    end
+
+    def update_in_search_index
+      index_manager.update(self)
+    end
+
+    def remove_from_search_index
+      index_manager.delete(self)
+    end
+
+    def index_manager
+      IndexManager.new(self.class, self.class.search_configuration, adapter)
+    end
+
+    def adapter
+      self.class.send(:adapter)
+    end
+  end
+end

data/lib/activerecord/searchable/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  module Searchable
+    VERSION = "0.1.2"
+  end
+end

data/lib/activerecord-searchable.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "active_record"
+require "active_support/concern"
+
+require_relative "activerecord/searchable/version"
+require_relative "activerecord/searchable/field"
+require_relative "activerecord/searchable/configuration"
+require_relative "activerecord/searchable/adapter"
+require_relative "activerecord/searchable/adapters/sqlite"
+require_relative "activerecord/searchable/query_builder"
+require_relative "activerecord/searchable/index_manager"
+require_relative "activerecord/searchable/searchable"
+
+module ActiveRecord
+  module Searchable
+    class SchemaError < StandardError; end
+  end
+end
+
+# Auto-include not enabled by default - users must explicitly include
+# This gives them control over which models get search functionality

data/lib/generators/searchable/USAGE

@@ -0,0 +1,20 @@
+Description:
+    Generates a migration to create the FTS5 virtual table for a searchable model.
+    Reads the searchable configuration from the model to determine which fields to index.
+
+Example:
+    rails generate searchable:migration Article
+
+    This will create:
+        db/migrate/YYYYMMDDHHMMSS_create_article_search_index.rb
+
+    The model must already have a searchable block defined:
+
+        class Article < ApplicationRecord
+          include ActiveRecord::Searchable
+
+          searchable do
+            field :title, weight: 2.0
+            field :body
+          end
+        end

data/lib/generators/searchable/migration_generator.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+require 'rails/generators/active_record'
+
+module Searchable
+  module Generators
+    class MigrationGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path('templates', __dir__)
+
+      argument :model_name, type: :string, required: true
+
+      def create_migration_file
+        validate_model_name!
+        validate_rails_version!
+        validate_model_exists!
+        validate_searchable_config!
+
+        migration_template(
+          "migration.rb.tt",
+          "db/migrate/create_#{search_table_name}.rb",
+          migration_version: migration_version
+        )
+      end
+
+      private
+
+      def model_class
+        @model_class ||= model_name.camelize.constantize
+      end
+
+      def search_config
+        @search_config ||= model_class.search_configuration
+      end
+
+      def search_table_name
+        search_config.search_table_name
+      end
+
+      def field_names
+        search_config.field_names
+      end
+
+      def migration_class_name
+        search_table_name.camelize
+      end
+
+      def migration_version
+        "[#{ActiveRecord::VERSION::MAJOR}.#{ActiveRecord::VERSION::MINOR}]"
+      end
+
+      def validate_model_name!
+        unless model_name.match?(/\A[A-Z][a-zA-Z0-9_]*\z/)
+          raise Thor::Error, "Invalid model name: #{model_name}. Must be a valid Ruby class name (e.g., Article, BlogPost)."
+        end
+      end
+
+      def validate_rails_version!
+        if Rails.version < "8.0"
+          raise "activerecord-searchable requires Rails 8.0+ for create_virtual_table support. " \
+                "Current version: #{Rails.version}"
+        end
+      end
+
+      def validate_model_exists!
+        model_name.camelize.constantize
+      rescue NameError
+        raise "Model #{model_name.camelize} not found. Please create the model first."
+      end
+
+      def validate_searchable_config!
+        unless model_class.respond_to?(:search_configuration)
+          output_example_config
+          raise Thor::Error, "No searchable configuration found in #{model_class.name}"
+        end
+
+        if search_config.fields.empty?
+          say "Error: No fields defined in searchable block for #{model_class.name}", :red
+          raise Thor::Error, "Cannot generate migration without searchable fields"
+        end
+      end
+
+      def output_example_config
+        say "\nNo searchable configuration found in #{model_class.name}.", :red
+        say "\nAdd this to app/models/#{model_name.underscore}.rb:\n", :yellow
+        say <<~RUBY
+
+            include ActiveRecord::Searchable
+
+            searchable do
+              field :title, weight: 2.0
+              field :body
+            end
+        RUBY
+        say "\nThen run this generator again.\n", :yellow
+      end
+    end
+  end
+end

data/lib/generators/searchable/templates/migration.rb.tt

@@ -0,0 +1,16 @@
+class Create<%= migration_class_name %> < ActiveRecord::Migration<%= migration_version %>
+  def up
+    create_virtual_table :<%= search_table_name %>, :fts5, [
+<% field_names.each do |field| -%>
+      "<%= field %>",
+<% end -%>
+      "tokenize='porter'"
+    ]
+
+    <%= model_name.camelize %>.reindex_all
+  end
+
+  def down
+    drop_table :<%= search_table_name %>
+  end
+end

metadata

@@ -0,0 +1,145 @@
+--- !ruby/object:Gem::Specification
+name: activerecord-searchable
+version: !ruby/object:Gem::Version
+  version: 0.1.2
+platform: ruby
+authors:
+- Matt Lins
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.1'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+description: Add full-text search to Active Record models using SQLite FTS5, with
+  zero external dependencies
+email:
+- mattlins@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- lib/activerecord-searchable.rb
+- lib/activerecord/searchable/adapter.rb
+- lib/activerecord/searchable/adapters/sqlite.rb
+- lib/activerecord/searchable/configuration.rb
+- lib/activerecord/searchable/field.rb
+- lib/activerecord/searchable/index_manager.rb
+- lib/activerecord/searchable/query_builder.rb
+- lib/activerecord/searchable/searchable.rb
+- lib/activerecord/searchable/version.rb
+- lib/generators/searchable/USAGE
+- lib/generators/searchable/migration_generator.rb
+- lib/generators/searchable/templates/migration.rb.tt
+homepage: https://github.com/mattlins/activerecord-searchable
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/mattlins/activerecord-searchable
+  source_code_uri: https://github.com/mattlins/activerecord-searchable
+  changelog_uri: https://github.com/mattlins/activerecord-searchable/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.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Database-native full-text search for Rails 8+
+test_files: []