# Querying The Database

> Query the local or production database from the CLI via the `agent:db` artisan command. Activates when the user asks to inspect, count, look up, or run a query against the database; asks 'how many X', 'what's in prod', 'check the prod DB', 'query the database'; or mentions production data, the prod database, or running SQL.

- Skill: `whisper-money/querying-the-database` (Agent Skill)
- Install (CLI): `npx skillmds@latest add whisper-money/querying-the-database`
- Raw SKILL.md: https://api.skillmd.com/api/skills/whisper-money/querying-the-database/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Data & Analytics
- Author: whisper-money (https://skillmd.com/u/whisper-money)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/whisper-money/querying-the-database

---


# Querying the Database

## When to Apply

Activate this skill whenever you need to read data from the database to answer a
question — especially anything about **production** data. Prefer this command over
the `tinker`, `database-query`, or `database-schema` Boost tools when the user asks
about prod, since those default to the local connection.

## The `agent:db` command

Runs a query (`SELECT`, `SHOW`, `DESCRIBE`, `DELETE`, etc.) and prints the result.

```bash
php artisan agent:db "<query>"
```

### Options

- `--format=json` (default) — pretty-printed JSON, best for parsing the result yourself.
- `--format=table` — classic console table, best when showing the result to the user.
- `--prod` — run against the **production** database (the `prod` connection backed by
  `PROD_DB_URL`). Without this flag the query runs against the local DB.

  `PROD_DB_URL` holds a MySQL user with **read-only grants**, so any write —
  `INSERT`, `UPDATE`, `DELETE`, DDL — fails with an access-denied error from the
  server. That is deliberate, and it is the only thing enforcing read-only: the
  command itself hands the query straight to PDO. If a prod write fails, the
  guardrail is working; run it against the local connection, or ship it as a
  migration or a release command. Never work around it.

### Examples

```bash
# Local, JSON (default)
php artisan agent:db "select id, email from users limit 5"

# Local, human-readable table
php artisan agent:db --format=table "select count(*) as total from transactions"

# Production
php artisan agent:db --prod "select count(*) from users"
php artisan agent:db --prod --format=table "select status, count(*) from subscriptions group by status"
```

## Guidelines

- **`--prod` is read-only by credentials, not by convention** (see above), but it is still live customer data. Only run prod queries the
  user explicitly asked for, keep them scoped (add `LIMIT`, filter by id), and never
  dump large or sensitive datasets unprompted. This app is privacy-first.
- Use `--format=json` when you need to read the values to continue working; use
  `--format=table` when presenting results back to the user.
- Inspect schema first with `database-schema` (local) when you're unsure of column
  names before writing a query.