rails-query

rails-query

A Claude Code plugin that teaches Claude to answer data questions about a Rails 8.2+ application using the rails query command — locally or against a deployed environment via Kamal.

What it does

When you ask Claude something like:

• "How many active users do we have?"
• "Show me the orders table structure."
• "What models reference accounts?"
• "Explain the query plan for this scope."

…Claude reaches for rails query instead of opening a console, SSHing to a server, or writing a one-off script. Queries are structured (JSON output), read-only by construction (writes blocked at the connection level), and safe to run against production with a read replica.

The skill covers:

• Both paths — local (bin/rails query) and remote via Kamal (bin/kamal query -d <env>)
• All four input modes — ActiveRecord expressions, raw SQL (--sql), schema/model introspection (schema, models), and EXPLAIN plans
• Pagination — how to page through large results, and why you shouldn't add your own LIMIT
• The Kamal quoting rule — the one gotcha that bites when your SQL has parens or stars, and the reliable fix

Installation

This repository is both the plugin and a single-plugin marketplace, so you can install it directly without waiting for Anthropic marketplace approval.

From your shell:

claude plugin marketplace add lewispb/rails-query-skill
claude plugin install rails-query@rails-query-skill

Or equivalently, from inside an interactive Claude Code session:

/plugin marketplace add lewispb/rails-query-skill
/plugin install rails-query@rails-query-skill
/reload-plugins

The first command registers this repo as a marketplace; the second installs the plugin. In-session, /reload-plugins picks it up without restarting. The plugin will also be submitted to the official Anthropic marketplace — once approved, a shorter claude plugin install rails-query@claude-plugins-official will work too.

Requirements

• Rails 8.2+ (the app you're querying). Earlier versions don't ship the rails query command.

• jq on your PATH if you want the skill's suggested extraction patterns to work (jq '.rows[0][0]').

• For remote use: Kamal with an alias added to config/deploy.yml:

  aliases:
    query: 'app exec -q --reuse -p -r console "rails query"'
  

  Your console role should be configured with read-replica DB access. See the skill body for the reasoning behind each flag.

How triggering works

The skill is described broadly so Claude invokes it whenever a task would naturally be solved by querying a Rails database — not just when the user types /rails-query:rails-query. Try:

"How many users registered last week?"

"What's in the mailboxes table?"

"Explain this query: Post.published.limit(100)"

Further reading

• rails/rails#57156 — the PR that added rails query to Rails 8.2. Read this for the full design, rationale, and command surface.
• Kamal app commands — for wiring bin/kamal query to rails query on deployed environments.

Contributing

Issues and PRs welcome at https://github.com/lewispb/rails-query-skill.

License

MIT