Class: FullSearch::Index

Inherits:

Object

• Object
• FullSearch::Index

Defined in:

lib/full_search/index.rb

Class Method Summary

• .create_triggers!(model) ⇒ Object
• .drop!(model) ⇒ Object
• .drop_fts_table_safely!(table_name) ⇒ Object

  Drops an FTS5 virtual table, recovering from corruption where a bare DROP TABLE IF EXISTS raises "invalid fts5 file format" because the shadow tables were tampered with out-of-band.

• .drop_shadow_tables!(table_name) ⇒ Object

  FTS5 stores its index data in a fixed set of shadow tables named

  _content, _data, _idx, _docsize and _config.

  .drop_triggers!(model) ⇒ Object

  .ensure_table!(model) ⇒ Object

  .fts_table_name(model) ⇒ Object

  .healthy?(model) ⇒ Boolean

  .missing_table?(model) ⇒ Boolean

  .optimize!(model) ⇒ Object

  .rebuild!(model) ⇒ Object

  .rebuild_if_needed!(model) ⇒ Object

  .reindex_source_fields!(model) ⇒ Object

  .sqlite!(model) ⇒ Object

  .sqlite?(model = nil) ⇒ Boolean

  .stored_config_hash(model) ⇒ Object

  .trigram_table_exists?(model) ⇒ Boolean

  .trigram_table_name(model) ⇒ Object

  .trigram_table_needed?(model) ⇒ Boolean

  .truncate!(model) ⇒ Object

  .upsert_source_row!(model, rowid, values) ⇒ Object

  .verified_tables ⇒ Object

  Class Method Details

  .create_triggers!(model) ⇒ Object

  # File 'lib/full_search/index.rb', line 141
  
  def create_triggers!(model)
    connection.execute(insert_trigger_sql(model))
    connection.execute(delete_trigger_sql(model))
    connection.execute(update_trigger_sql(model))
    if model.full_search_dsl.soft_delete_column
      connection.execute(soft_delete_removal_trigger_sql(model))
    end
    if trigram_table_needed?(model)
      connection.execute(insert_trigram_trigger_sql(model))
      connection.execute(delete_trigram_trigger_sql(model))
      connection.execute(update_trigram_trigger_sql(model))
    end
  end

  .drop!(model) ⇒ Object

  # File 'lib/full_search/index.rb', line 179
  
  def drop!(model)
    IndexCache.clear!
    verified_tables.delete(model.table_name)
    sqlite!(model)
    drop_triggers!(model)
    drop_fts_table_safely!(fts_table_name(model))
    drop_fts_table_safely!(trigram_table_name(model))
  end

  .drop_fts_table_safely!(table_name) ⇒ Object

  Drops an FTS5 virtual table, recovering from corruption where a bare DROP TABLE IF EXISTS raises "invalid fts5 file format" because the shadow tables were tampered with out-of-band. When that happens we drop the shadow tables directly, then drop the (now-empty) virtual table wrapper, so the caller can recreate a clean index.

  # File 'lib/full_search/index.rb', line 192
  
  def drop_fts_table_safely!(table_name)
    connection.execute("DROP TABLE IF EXISTS #{qt(table_name)};")
  rescue ActiveRecord::StatementInvalid => e
    raise unless e.message.match?(/fts5: corruption|invalid fts5 file format|malformed database schema/i)
  
    drop_shadow_tables!(table_name)
    connection.execute("DROP TABLE IF EXISTS #{qt(table_name)};")
  end

  .drop_shadow_tables!(table_name) ⇒ Object

  FTS5 stores its index data in a fixed set of shadow tables named

  _content, _data, _idx, _docsize and _config. Dropping these lets SQLite recover a virtual table that is otherwise undroppable due to internal corruption.

  # File 'lib/full_search/index.rb', line 205
  
  def drop_shadow_tables!(table_name)
    %w[content data idx docsize config].each do |suffix|
      shadow = "#{table_name}_#{suffix}"
      connection.execute("DROP TABLE IF EXISTS #{qt(shadow)};")
    end
  end

  .drop_triggers!(model) ⇒ Object

  # File 'lib/full_search/index.rb', line 155
  
  def drop_triggers!(model)
    (trigger_names(model) + trigram_trigger_names(model)).each do |name|
      connection.execute("DROP TRIGGER IF EXISTS #{qt(name)};")
    end
  end

  .ensure_table!(model) ⇒ Object

  # File 'lib/full_search/index.rb', line 21
  
  def ensure_table!(model)
    return if model.respond_to?(:table_name) && verified_tables.include?(model.table_name)
  
    sqlite!(model)
  
    conn = connection
    dsl = model.full_search_dsl
    return unless dsl
  
    create_metadata_table!
  
    if table_exists?(model) && !healthy?(model)
      rebuild!(model)
    end
  
    fts_was_created = false
    unless table_exists?(model)
      conn.execute(create_virtual_table_sql(model))
      fts_was_created = true
    end
  
    trigram_was_created = false
    if trigram_table_needed?(model) && !trigram_table_exists?(model)
      FullSearch::Typo.warn_unsupported!(model) unless FullSearch::Typo.supported?(model)
      conn.execute(create_trigram_virtual_table_sql(model))
      trigram_was_created = true
    end
  
    if fts_was_created || trigram_was_created
      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
  
    ensure_triggers!(model) if model_table_exists?(model)
  
    verified_tables.add(model.table_name)
  end

  .fts_table_name(model) ⇒ Object

  # File 'lib/full_search/index.rb', line 212
  
  def fts_table_name(model)
    "#{model.table_name}_fts"
  end

  .healthy?(model) ⇒ Boolean

  Returns:

  • (Boolean)

  # File 'lib/full_search/index.rb', line 248
  
  def healthy?(model)
    return false unless table_exists?(model)
  
    connection.execute("SELECT count(*) FROM #{qt(fts_table_name(model))}")
    true
  rescue ActiveRecord::StatementInvalid => e
    raise unless e.message.match?(/fts5: corruption|invalid fts5 file format|malformed database schema/i)
  
    false
  end

  .missing_table?(model) ⇒ Boolean

  Returns:

  • (Boolean)

  # File 'lib/full_search/index.rb', line 244
  
  def missing_table?(model)
    !table_exists?(model)
  end

  .optimize!(model) ⇒ Object

  # File 'lib/full_search/index.rb', line 111
  
  def optimize!(model)
    FullSearch::Instrumentation.instrument("optimize", model: model.name) do
      sqlite!(model)
      connection.execute("INSERT INTO #{qt(fts_table_name(model))}(#{qt(fts_table_name(model))}) VALUES('optimize');")
    end
  end

  .rebuild!(model) ⇒ Object

  # File 'lib/full_search/index.rb', line 61
  
  def rebuild!(model)
    IndexCache.clear!
    sqlite!(model)
  
    dsl = model.full_search_dsl
    return unless dsl
    conn = connection
  
    create_metadata_table!
  
    with_rebuild_lock(model) do
      FullSearch::Instrumentation.instrument("rebuild", model: model.name) do
        drop_triggers!(model)
        drop_fts_table_safely!(fts_table_name(model))
        drop_fts_table_safely!(trigram_table_name(model))
        conn.execute(create_virtual_table_sql(model))
        if trigram_table_needed?(model)
          FullSearch::Typo.warn_unsupported!(model) unless FullSearch::Typo.supported?(model)
          conn.execute(create_trigram_virtual_table_sql(model))
        end
        conn.execute(backfill_sql(model))
        conn.execute(backfill_trigram_sql(model)) if trigram_table_needed?(model)
        reindex_source_fields!(model) if dsl.fields.any?(&:source)
        create_triggers!(model)
        optimize!(model)
        store_config_hash!(model, rebuilt_at: Time.current)
        verified_tables.add(model.table_name)
      end
    end
  end

  .rebuild_if_needed!(model) ⇒ Object

  # File 'lib/full_search/index.rb', line 92
  
  def rebuild_if_needed!(model)
    IndexCache.clear!
    sqlite!(model)
  
    dsl = model.full_search_dsl
    return false unless dsl
  
    create_metadata_table!
    ensure_table!(model)
  
    stored = stored_config_hash(model)
    if stored && stored == dsl.config_hash
      false
    else
      rebuild!(model)
      true
    end
  end

  .reindex_source_fields!(model) ⇒ Object

  # File 'lib/full_search/index.rb', line 118
  
  def reindex_source_fields!(model)
    dsl = model.full_search_dsl
    return unless dsl
  
    source_fields = dsl.fields.select(&:source)
    return if source_fields.empty?
  
    model.find_each(batch_size: 500) do |record|
      pairs = source_fields.to_h { |f| [column_name(f), FullSearch::Model.evaluate_source(record, f).to_s] }
      next if pairs.empty?
      upsert_source_row!(model, record.id, pairs)
    end
  end

  .sqlite!(model) ⇒ Object

  Raises:

  • (UnsupportedDatabaseError)

  # File 'lib/full_search/index.rb', line 230
  
  def sqlite!(model)
    adapter = model ? model.connection.adapter_name : connection.adapter_name
    raise UnsupportedDatabaseError, "full_search requires SQLite, but #{adapter} is configured" unless sqlite?(model)
  end

  .sqlite?(model = nil) ⇒ Boolean

  Returns:

  • (Boolean)

  # File 'lib/full_search/index.rb', line 220
  
  def sqlite?(model = nil)
    if model
      model.connection.adapter_name.downcase.include?("sqlite")
    else
      connection.adapter_name.downcase.include?("sqlite")
    end
  rescue ActiveRecord::ConnectionNotEstablished, NoMethodError
    connection.adapter_name.downcase.include?("sqlite")
  end

  .stored_config_hash(model) ⇒ Object

  # File 'lib/full_search/index.rb', line 235
  
  def stored_config_hash(model)
    IndexCache.fetch("stored_config_hash:#{model.table_name}") do
      row = connection.execute(
        "SELECT config_hash FROM full_search_index_versions WHERE table_name=#{q(model.table_name)}"
      ).first
      row&.[]("config_hash")
    end
  end

  .trigram_table_exists?(model) ⇒ Boolean

  Returns:

  • (Boolean)

  # File 'lib/full_search/index.rb', line 263
  
  def trigram_table_exists?(model)
    connection.execute(
      "SELECT name FROM sqlite_master WHERE type='table' AND name=#{q(trigram_table_name(model))} LIMIT 1"
    ).any?
  end

  .trigram_table_name(model) ⇒ Object

  # File 'lib/full_search/index.rb', line 216
  
  def trigram_table_name(model)
    "#{fts_table_name(model)}_trigram"
  end

  .trigram_table_needed?(model) ⇒ Boolean

  Returns:

  • (Boolean)

  # File 'lib/full_search/index.rb', line 259
  
  def trigram_table_needed?(model)
    model.full_search_dsl&.typo_tolerance? && model.full_search_dsl.tokenize != "trigram"
  end

  .truncate!(model) ⇒ Object

  # File 'lib/full_search/index.rb', line 161
  
  def truncate!(model)
    IndexCache.clear!
    sqlite!(model)
    dsl = model.full_search_dsl
    return unless dsl
    return unless table_exists?(model)
  
    conn = connection
    begin
      conn.execute("DELETE FROM #{qt(fts_table_name(model))};")
      conn.execute("DELETE FROM #{qt(trigram_table_name(model))};") if trigram_table_needed?(model) && trigram_table_exists?(model)
    rescue ActiveRecord::StatementInvalid => e
      raise unless e.message.match?(/fts5: corruption|invalid fts5 file format|malformed database schema/i)
  
      rebuild!(model)
    end
  end

  .upsert_source_row!(model, rowid, values) ⇒ Object

  # File 'lib/full_search/index.rb', line 132
  
  def upsert_source_row!(model, rowid, values)
    table = qt(fts_table_name(model))
    sets = values.map { |name, value| "#{qc(name)} = #{q(value)}" }.join(", ")
  
    connection.execute(<<~SQL)
      UPDATE #{table} SET #{sets} WHERE rowid = #{q(rowid)};
    SQL
  end

  .verified_tables ⇒ Object

  # File 'lib/full_search/index.rb', line 17
  
  def verified_tables
    @verified_tables ||= Set.new
  end

  Generated on Thu Jul 30 21:14:19 2026 by yard 0.9.45 (ruby-4.0.2).