rails-query
Run read-only database queries against Ruby on Rails 8.2+ app's database via rails query — ActiveRecord or SQL, schema/model introspection,
Open source Open in the app JSON README (API)
About
Run read-only database queries against Ruby on Rails 8.2+ app's database via rails query — ActiveRecord or SQL, schema/model introspection, EXPLAIN, pagination, and remote execution via Kamal.
Details
- Kind
- Plugins
- Topic
- Databases
- Publisher
- lewispb
- Origin
- marketplace
- Category
- ferramentas
- Stars
- 25
- Forks
- 1
- Last push
- 2026-04-23T14:56:22Z
- Repository state
- ativo
- License
- MIT
- Added
- 2026-08-30 01:48:58
- Updated
- 2026-08-30 01:48:58
- Origin id
lewispb/rails-query-skill/rails-query
README
# rails-query
A Claude Code plugin that teaches Claude to answer data questions about a Rails 8.2+ application using the [`rails query`](https://github.com/rails/rails/pull/57156) 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:
```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`:
```yaml
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](https://github.com/rails/rails/pull/57156) — the PR that added `rails query` to Rails 8.2. Read this for the full design, rationale, and command surface.
- [Kamal `app` commands](https://kamal-deploy.org/docs/commands/app/) — 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