If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/elastic/elasticsearch-rails shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• Last commit 7mo ago
• 17 active contributors
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Slowing — last commit 7mo ago
• ⚠ Concentrated ownership — top contributor handles 76% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live elastic/elasticsearch-rails repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/elastic/elasticsearch-rails.

What it runs against: a local clone of elastic/elasticsearch-rails — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in elastic/elasticsearch-rails | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 244 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of elastic/elasticsearch-rails. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/elastic/elasticsearch-rails.git
#   cd elasticsearch-rails
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of elastic/elasticsearch-rails and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "elastic/elasticsearch-rails(\\.git)?\\b" \\
  && ok "origin remote is elastic/elasticsearch-rails" \\
  || miss "origin remote is not elastic/elasticsearch-rails (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "elasticsearch-model/lib/elasticsearch/model.rb" \\
  && ok "elasticsearch-model/lib/elasticsearch/model.rb" \\
  || miss "missing critical file: elasticsearch-model/lib/elasticsearch/model.rb"
test -f "elasticsearch-model/lib/elasticsearch/model/adapters/active_record.rb" \\
  && ok "elasticsearch-model/lib/elasticsearch/model/adapters/active_record.rb" \\
  || miss "missing critical file: elasticsearch-model/lib/elasticsearch/model/adapters/active_record.rb"
test -f "elasticsearch-model/lib/elasticsearch/model/searching.rb" \\
  && ok "elasticsearch-model/lib/elasticsearch/model/searching.rb" \\
  || miss "missing critical file: elasticsearch-model/lib/elasticsearch/model/searching.rb"
test -f "elasticsearch-model/lib/elasticsearch/model/importing.rb" \\
  && ok "elasticsearch-model/lib/elasticsearch/model/importing.rb" \\
  || miss "missing critical file: elasticsearch-model/lib/elasticsearch/model/importing.rb"
test -f "elasticsearch-model/lib/elasticsearch/model/response/records.rb" \\
  && ok "elasticsearch-model/lib/elasticsearch/model/response/records.rb" \\
  || miss "missing critical file: elasticsearch-model/lib/elasticsearch/model/response/records.rb"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 244 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~214d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/elastic/elasticsearch-rails"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

elasticsearch-rails provides Ruby and Rails integrations for Elasticsearch, enabling ActiveRecord/Mongoid models to index, search, and retrieve results through Elasticsearch with minimal boilerplate. It wraps the elasticsearch-ruby client and exposes methods like search(), import(), and mapping() directly on Rails models, handling index lifecycle, callbacks for automatic indexing on model changes, and result serialization back to ORM objects. Monorepo with three independent gems: elasticsearch-model (core ActiveModel adapter, ~565KB Ruby, in elasticsearch-model/lib), elasticsearch-rails (Rails generators and rake tasks), and elasticsearch-persistence (standalone ORM). Each has its own gemspec, tests, and CHANGELOG. Adapters in elasticsearch-model/lib/elasticsearch/model/adapters/ support ActiveRecord, Mongoid, and a default fallback. Examples in elasticsearch-model/examples/ show integration patterns (activerecord_*.rb, mongoid_article.rb, etc).

Rails developers building full-text search, autocomplete, or complex filtering features who want to index ActiveRecord or Mongoid models in Elasticsearch without writing raw Elasticsearch queries or managing index synchronization manually.

Production-ready and actively maintained. The repo has comprehensive CI/CD (tests.yml, jruby.yml, license.yml workflows), covers Ruby 3.0+, maintains version alignment with Elasticsearch 8.x major versions, and publishes to RubyGems. Recent activity visible through gemfiles for multiple Rails versions (6.1, 7.0, 7.1) and explicit compatibility matrix in README.

Low risk for active projects. Dependencies are explicitly managed (elasticsearch-ruby is the core dep), but this is a multi-gem monorepo (elasticsearch-model, elasticsearch-rails, elasticsearch-persistence) so changes in one affect others. No single-maintainer signal visible, and license headers are actively checked via GitHub Actions. Main risk: Elasticsearch version coupling—the gem major version must match your Elasticsearch cluster version (e.g., 8.x gem for ES 8.x server).

Actively maintained against Elasticsearch 8.x; gemfiles confirm support for Rails 6.1, 7.0, 7.1. CI runs Ruby tests and JRuby tests on each commit. License header compliance is enforced. No specific breaking changes visible in file list, suggesting incremental maintenance mode with compatibility focus.

git clone https://github.com/elastic/elasticsearch-rails.git
cd elasticsearch-rails/elasticsearch-model
bundle install
bundle exec rake test

Daily commands: No single dev server; this is a library gem. Run tests with bundle exec rake test in elasticsearch-model/. Examples in elasticsearch-model/examples/ are runnable scripts (e.g., ruby activerecord_article.rb) assuming an Elasticsearch server is running locally on port 9200.

• elasticsearch-model/lib/elasticsearch/model.rb — Main entry point that loads all integrations and DSL—every contributor must understand this to grasp how ActiveModel/Record integration is bootstrapped.
• elasticsearch-model/lib/elasticsearch/model/adapters/active_record.rb — Core ActiveRecord adapter that bridges Rails models to Elasticsearch—critical for understanding how persistence and indexing work.
• elasticsearch-model/lib/elasticsearch/model/searching.rb — Search DSL and query execution layer—essential for understanding how .search() method works and query parsing.
• elasticsearch-model/lib/elasticsearch/model/importing.rb — Bulk import and indexing mechanism—required reading for understanding how data gets synced to Elasticsearch.
• elasticsearch-model/lib/elasticsearch/model/response/records.rb — Result wrapping that converts ES responses back to Rails model instances—critical for understanding the query-to-object mapping.
• elasticsearch-model/lib/elasticsearch/model/callbacks.rb — ActiveRecord hook integration for automatic indexing on model changes—essential for understanding data synchronization patterns.
• elasticsearch-model/lib/elasticsearch/model/indexing.rb — Low-level indexing and mapping definition—required for understanding how schema and serialization are configured.

Add search functionality to an existing Rails model

1. Include Elasticsearch::Model in your Rails model class (elasticsearch-model/examples/activerecord_article.rb)
2. Define index mapping and serialization in the model using the mapping DSL (elasticsearch-model/lib/elasticsearch/model/indexing.rb)
3. Run bulk import to index existing records using Article.import (elasticsearch-model/lib/elasticsearch/model/importing.rb)
4. Use Article.search() method to query Elasticsearch with automatic callback indexing (elasticsearch-model/lib/elasticsearch/model/searching.rb)

Create a custom search with aggregations and pagination

1. Call model.search() with query DSL block syntax (elasticsearch-model/lib/elasticsearch/model/searching.rb)
2. Access aggregations from the response using .aggregations property (elasticsearch-model/lib/elasticsearch/model/response/aggregations.rb)
3. Chain .page() for Kaminari or .paginate() for WillPaginate pagination (elasticsearch-model/lib/elasticsearch/model/response/pagination/kaminari.rb)
4. Results are automatically wrapped as model instances via ActiveRecord adapter (elasticsearch-model/lib/elasticsearch/model/response/records.rb)

Support a new ORM beyond ActiveRecord/Mongoid

1. Create new adapter inheriting from Elasticsearch::Model::Adapter in adapters/ directory (elasticsearch-model/lib/elasticsearch/model/adapter.rb)
2. Implement find(), records_mixin(), and other required interface methods (elasticsearch-model/lib/elasticsearch/model/adapters/default.rb)
3. Register adapter in the adapter registry and add to model integration (elasticsearch-model/lib/elasticsearch/model/adapters/multiple.rb)
4. Add comprehensive tests alongside existing ActiveRecord/Mongoid specs (elasticsearch-model/spec/elasticsearch/model/adapter_spec.rb)

Customize index mapping and serialization per model

1. Use mapping DSL block in model to define field types and analyzers (elasticsearch-model/lib/elasticsearch/model/indexing.rb)
2. Override as_indexed_json method to control document serialization (elasticsearch-model/lib/elasticsearch/model/serializing.rb)
3. Use callbacks in model to sync nested associations to Elasticsearch (elasticsearch-model/lib/elasticsearch/model/callbacks.rb)
4. Test custom mapping with spec/elasticsearch/model/adapters/active_record/ patterns (elasticsearch-model/spec/elasticsearch/model/adapters/active_record/serialization_spec.rb)

• Ruby gem with ActiveModel/Record integration — Provides seamless Elasticsearch integration directly into existing Rails applications without requiring separate query layer or data pipeline.
• elasticsearch-ruby client dependency — Leverages official Elasticsearch Ruby client for all API communication, ensuring API compatibility and maintenance by Elastic.
• Module-based mixin pattern — Allows developers to opt-in to Elasticsearch features on any model class without inheritance, maintaining flexibility and minimal coupling.
• Adapter pattern for multi-ORM support — Abstracts ORM differences (ActiveRecord, Mongoid, etc.) allowing single DSL and search logic to work across multiple database systems.
• Lazy-loaded proxy pattern for queries — Enables chainable query DSL that only executes when results are actually needed, integrating smoothly with Rails' Relation pattern.

• Search results are wrapped as model instances via database lookups rather than ES-only responses

  • Why: Ensures users always get full model objects with all associations and validations, maintaining Rails conventions.
  • Consequence: Additional database round-trip required after search; slower for large result sets but necessary for full ORM integration.

• Callbacks handle automatic indexing on model save/destroy

  • Why: Keeps index and database in sync transparently without explicit sync code.
  • Consequence: Tight coupling between model layer and Elasticsearch; slow writes in high-write workloads; can cause cascading failures if ES is unavailable.

• undefined

  • Why: undefined
  • Consequence: undefined

Elasticsearch must be running on localhost:9200 (or configured via ELASTICSEARCH_URL env var) for examples and tests to pass. The gem version must match your Elasticsearch server major version (8.x gem with 8.x ES). ActiveRecord adapter requires valid database connection for lazy-loading. Indexing is not automatic on first include Elasticsearch::Model—must call Article.import to index existing records. Response objects are lazy; enumerating them triggers database queries if you ask for full objects, not just hits.

• Adapter Pattern — elasticsearch-rails abstracts different ORMs (ActiveRecord, Mongoid, DataMapper) behind adapters (elasticsearch-model/lib/elasticsearch/model/adapters/) so the same Elasticsearch::Model mixin works across frameworks without ORM-specific code in the core.
• Lazy Loading & N+1 Query Prevention — The Response class wraps Elasticsearch hits and defers database lookups until you access record attributes; understanding when .records vs .hits triggers queries is critical to avoid N+1 bugs in search results.
• ActiveSupport Callbacks — elasticsearch-model/lib/elasticsearch/model/callbacks.rb hooks into Rails' after_create, after_update, after_destroy callbacks to auto-sync the Elasticsearch index; understanding callback ordering prevents silent index stale-ness.
• Bulk Indexing — The importing.rb module uses Elasticsearch's bulk API to index thousands of records efficiently; naive per-record indexing would be orders of magnitude slower, so this pattern is essential knowledge for production use.
• Mapping & Schema Inference — elasticsearch-model infers Elasticsearch field mappings (data types, analyzers) from model attributes via the mapping DSL; incorrect mappings break full-text search or aggregations, so understanding how indexing.rb defines and applies mappings is crucial.
• Enumerable Protocol — Response objects inherit from Enumerable, so users can call .map, .select, .each on search results, but the implementation trades memory for lazy evaluation—understanding when results are fetched prevents surprises.
• Repository Pattern — elasticsearch-persistence (sibling gem) implements a pure repository pattern for non-ORM Ruby objects; understanding how it differs from the Model mixin pattern helps you choose the right tool (Model for Rails apps, Persistence for standalone systems).

• elastic/elasticsearch-ruby — The underlying Elasticsearch client library that elasticsearch-rails wraps; required dependency providing the HTTP transport and query DSL
• rails/rails — ActiveRecord and ActiveModel are the target ORM frameworks; understanding Rails conventions is essential for using this gem
• mongodb/mongoid — Alternative ORM supported by elasticsearch-model via adapters/mongoid.rb; users migrating from ActiveRecord to Mongoid leverage the same Elasticsearch integration
• elastic/kibana — Complementary Elastic Stack tool for visualizing and exploring indices created/managed by elasticsearch-rails
• ankane/searchkick — Competing gem that also provides Rails-to-Elasticsearch integration with higher-level sugar (intelligent defaults, facets) but less control; users choose based on customization needs

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive test coverage for Mongoid adapter edge cases

The repo has adapters for ActiveRecord and Mongoid, but the test suite appears heavily weighted toward ActiveRecord (evident from elasticsearch-model/spec/elasticsearch/model/adapters/active_record/). Mongoid adapter (elasticsearch-model/lib/elasticsearch/model/adapters/mongoid.rb) likely lacks equivalent test coverage for association handling, callbacks, and importing behavior.

• [ ] Create elasticsearch-model/spec/elasticsearch/model/adapters/mongoid/ directory structure mirroring active_record tests
• [ ] Add mongoid_spec.rb for basic adapter functionality (similar to active_record_spec.rb pattern)
• [ ] Add mongoid/associations_spec.rb to test Mongoid association indexing behavior
• [ ] Add mongoid/importing_spec.rb to test bulk import with Mongoid documents
• [ ] Add mongoid/callbacks_spec.rb to verify after_save/after_destroy indexing hooks work correctly

Add GitHub Actions workflow for Ruby 3.1+ and latest Elasticsearch versions

The repo has workflows for JRuby and general tests (elasticsearch-rails/.github/workflows/), but there's no explicit workflow targeting recent Ruby versions (3.1, 3.2, 3.3) or recent Elasticsearch versions (8.x). This would catch compatibility regressions early.

• [ ] Create .github/workflows/compatibility.yml with matrix strategy for Ruby 3.1, 3.2, 3.3
• [ ] Add matrix for Elasticsearch versions 8.0+ using Docker container or testcontainers
• [ ] Configure gemfile matrix to test against elasticsearch-model/gemfiles/8.0.gemfile and newer
• [ ] Ensure tests run against ActiveRecord 7.x+ which may have breaking changes
• [ ] Add step to fail on deprecation warnings to catch early migration issues

Implement missing adapters test suite for Multiple adapter and Repository pattern

The file structure shows elasticsearch-model/lib/elasticsearch/model/adapters/multiple.rb and elasticsearch-model/lib/elasticsearch/model/multimodel.rb which support querying across multiple model types, but there's no evident test file (elasticsearch-model/spec/elasticsearch/model/adapters/multiple_spec.rb) for this complex feature.

• [ ] Create elasticsearch-model/spec/elasticsearch/model/adapters/multiple_spec.rb
• [ ] Add tests for MultiModel.search() across different model types (e.g., Article + Comment)
• [ ] Test result aggregation and record instantiation from mixed model types
• [ ] Add tests for pagination with multiple models to verify proper result counting
• [ ] Add tests for mapping conflicts when multiple models have different field definitions
• [ ] Create elasticsearch-model/spec/elasticsearch/model/multimodel_spec.rb if separate from multiple_spec.rb

• Add integration tests for Rails 8.0 in .github/workflows/tests.yml—the gemfiles/ directory has 6.1, 7.0, 7.1 but not 8.0, suggesting Rails 8 compatibility may not be explicitly tested yet.
• Document the adapter lifecycle in elasticsearch-model/README.md or elasticsearch-model/lib/elasticsearch/model/adapter.rb—the Adapter and #client() pattern is used but not clearly explained in visible comments, making it hard for new contributors to add custom adapters (e.g., for Sequel).
• Add a concurrency/thread-safety test for callbacks in elasticsearch-model/test/ covering edge cases like Sidekiq workers calling Model#index_document simultaneously—callbacks.rb uses ActiveSupport callbacks which may have race conditions with bulk imports.

The elasticsearch-rails codebase appears to be a well-structured ORM integration library with moderate security concerns. Primary risks include potential query injection vulnerabilities in the searching module, serialization safety issues, and inconsistent validation across multiple adapter implementations. The library lacks visible explicit authentication/authorization mechanisms and error handling safeguards. The codebase follows standard Ruby/Rails patterns but would benefit from enhanced input validation, secure error handling, and comprehensive security documentation. No hardcoded secrets or credentials were identified in the file structure. No critical infrastructure misconfigurations are apparent from the visible structure.

• Medium · Potential Elasticsearch Query Injection — elasticsearch-model/lib/elasticsearch/model/searching.rb. The codebase includes a searching module (elasticsearch-model/lib/elasticsearch/model/searching.rb) that constructs Elasticsearch queries. Without explicit validation in the visible code structure, there's a risk of query injection if user input is directly passed to search parameters without proper sanitization or parameterization. Fix: Implement strict input validation and use Elasticsearch's query DSL parameterization features. Avoid string concatenation for query building. Use whitelisting for search fields and operators.
• Medium · Potential Serialization Vulnerabilities — elasticsearch-model/lib/elasticsearch/model/serializing.rb. The serializing module (elasticsearch-model/lib/elasticsearch/model/serializing.rb) handles data serialization for Elasticsearch indexing. Improper serialization of untrusted data could lead to code execution or data exposure vulnerabilities, particularly if using unsafe deserialization methods. Fix: Use safe serialization methods (JSON only, avoid YAML/Marshal for untrusted data). Implement schema validation for all serialized data. Review any custom serialization logic for unsafe operations.
• Medium · Missing Input Validation in Multiple Adapters — elasticsearch-model/lib/elasticsearch/model/adapters/. The codebase supports multiple ORM adapters (ActiveRecord, Mongoid, etc.) across elasticsearch-model/lib/elasticsearch/model/adapters/. Each adapter may have different validation patterns, potentially leading to inconsistent security posture across different data sources. Fix: Implement consistent input validation across all adapters. Create a centralized validation layer that all adapters use. Add integration tests to verify security properties across different adapter implementations.
• Low · No Visible API Authentication/Authorization — elasticsearch-model/lib/elasticsearch/model/client.rb. The file structure shows integration modules but no explicit authentication or authorization mechanisms are visible in the analyzed files. This could pose a risk if the integration is used in contexts where Elasticsearch access control is important. Fix: Implement or document proper authentication mechanisms for Elasticsearch client connections. Support SSL/TLS certificate validation. Use credentials management best practices (avoid hardcoding credentials in code). Consider implementing role-based access control at the application level.
• Low · Potential Information Disclosure in Error Handling — elasticsearch-model/lib/elasticsearch/model/. No explicit error handling strategy is visible in the file structure. Elasticsearch error responses may contain sensitive information about index structure, data content, or system configuration if not properly handled. Fix: Implement comprehensive error handling that sanitizes Elasticsearch error messages before exposing them to end users. Log detailed errors securely server-side while returning generic error messages to clients. Implement proper logging and monitoring.
• Low · No Visible CSRF Protection in Rails Integration — elasticsearch-model/lib/elasticsearch/model/ext/active_record.rb. While this is primarily a backend integration library, there's no visible implementation of CSRF protection mechanisms if used in Rails controllers that accept user input for search queries. Fix: Document CSRF protection requirements for Rails applications using this gem. Ensure all HTTP endpoints that modify Elasticsearch state (reindexing, mapping changes) are protected with Rails' CSRF tokens. Implement strong parameter whitelisting.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.