# Use DBGorilla from the command line

You can use DBGorilla from a terminal with **mcporter**, a small open-source command-line tool for
MCP servers.  It suits shell scripts, scheduled jobs and CI, quick checks without opening an AI
tool, and AI tools that cannot add an MCP connector.  Nothing is installed inside your databases, and no
AI assistant is required.

<video class="loop" data-loop muted loop playsinline preload="none" poster="/docs/loops/mcporter-command-line.jpg" aria-label="Short silent loop: a terminal installs mcporter, adds DBGorilla's read-only set of tools, signs in, lists one database and shows three open recommendations.">
  <source src="/docs/loops/mcporter-command-line.webm" type="video/webm" />
  Short silent loop: a terminal installs mcporter, adds DBGorilla's read-only set of tools, signs in, lists one database and shows three open recommendations.
</video>

It uses DBGorilla's **read-only set of tools** at `https://app.dbgorilla.com/mcp/readonly`.  That set
leaves out the tools that create, change, or delete things in DBGorilla.  A few tools in it still run
work against a database on your behalf, such as an EXPLAIN plan, so treat it as a set of reading tools.
It does not guarantee that nothing can change.

The output below is trimmed example output from a demo workspace.  Your names and IDs will differ.

To connect an AI tool instead, see [Connect an MCP client by hand](/docs/integrations/mcp-client/).

## Turn it on

### Install

You need Node.js 20 or newer.

```bash
npm install -g mcporter
mcporter --version
```
```
0.9.0
```

### Add DBGorilla

mcporter keeps its settings in `config/mcporter.json` **under the folder you run it from**.  Create one
folder and always run mcporter from there.

```bash
mkdir ~/dbgorilla-cli && cd ~/dbgorilla-cli
mcporter config add dbgorilla --url https://app.dbgorilla.com/mcp/readonly
```
```
Added 'dbgorilla' to /home/you/dbgorilla-cli/config/mcporter.json
```

Then choose one of two ways to sign in.  Each person uses their own DBGorilla account.

### Option A: sign in through the browser (OAuth)

```bash
mcporter auth dbgorilla
```

A browser opens on the DBGorilla sign-in page.  It says "mcporter (dbgorilla) is requesting access to
DBGorilla on your behalf."  Sign in the way you normally do: with your organization, username and
password, or with Google or GitHub.  The browser then shows "Authorization successful.  You can return to the CLI." and
the terminal prints:

```
[mcporter] Authorization complete. 40 tools available.
```

If no browser opens, for example over SSH, the terminal prints a line starting `If the browser did
not open, visit https://app.dbgorilla.com/mcp/authorize?...`.  Open that link on the same machine.  It
sends you back to a local address (`127.0.0.1`), so it must be the machine running mcporter.

### Option B: an MCP API key

Use this for a server or script where a browser is not practical.

To get your key in DBGorilla:

1.  Click your name in the sidebar to open the user menu.
2.  Choose **Profile**.
3.  Open the **MCP Access** tab.
4.  Under **Bearer token**, use **Copy to clipboard**.  **Regenerate API Key** replaces the key and
   **Delete API Key** removes it.

Treat the key like a password.  It acts as you.

Keep the key out of the file by putting it in an environment variable. mcporter fills in `${DBGORILLA_API_KEY}`
when it runs:

```bash
export DBGORILLA_API_KEY='paste-your-key-here'
mcporter config add dbgorilla --url https://app.dbgorilla.com/mcp/readonly \
  --header 'Authorization=Bearer ${DBGORILLA_API_KEY}'
```

The single quotes matter.  They keep the key itself out of `config/mcporter.json`.

## Check it works

List the tools:

```bash
mcporter list dbgorilla
```
```
dbgorilla
  function discover_components(): object;
  function get_topology_overview(component_id: string): object;
  function list_topology_snapshots(component_id: string, limit?: number): object;
  ...
```

Add `--schema` to see every parameter for every tool.

Plain `mcporter list`, without the server name, reports an HTTP 405 SSE error for DBGorilla,
even though every call works.  The DBGorilla server answers a plain GET request with 405, which
the MCP specification allows, and mcporter reports that as an error.  Use `mcporter list dbgorilla`.

## List your databases

```bash
mcporter call dbgorilla.discover_components
```
```
{
  "result": [
    {
      "component_id": "9bc21246-e089-5391-ad14-5d21d77197d8",
      "name": "Storefront",
      "component_type": "postgres",
      "version": "16.15 (Debian 16.15-1.pgdg13+2)",
      "hosting": "Self-hosted"
    }
  ]
}
```

Copy the `component_id`.  Every other call needs it.  The examples set it once:

```bash
C=9bc21246-e089-5391-ad14-5d21d77197d8
```

`list_databases` is a different tool: it lists databases DBGorilla hosts for you.  For your own
databases, use `discover_components`.

## Read open recommendations

```bash
mcporter call dbgorilla.list_recommendations component_id=$C status_filter=open limit=3
```
```
#5  priority=medium    risk=low     category=query_improvement  status=open  title=Move inventory pacing delays outside the complete transaction
#4  priority=critical  risk=medium  category=security           status=open  title=Separate API runtime credentials from storefront_app superuser and migration credentials
#3  priority=critical  risk=low     category=security           status=open  title=Fix confirmed SQL injection in storefront.fn_find_products before performance work

Not all results shown, next page available by calling list_recommendations with the same inputs along with next_cursor=...
```

If a result prints as escaped JSON instead of text, add `--output text` to the command.

Filters: `priority_filter` (low, medium, high, critical), `risk_filter`, `category_filter`,
`status_filter` (open, complete, ignored, closed).

Read one in full:

```bash
mcporter call dbgorilla.view_recommendation component_id=$C number=5
```
```
#5  priority=medium  risk=low  category=query_improvement  status=open  version=1  created_at=2026-11-07T09:15:33Z

# Move inventory pacing delays outside the complete transaction

## Recommended change
In the external inventory-writing SQL/script workflow for database `storefront`, remove the deliberate
database sleep from the transaction responsible for the observed blocking session `13567`. If pacing is
required, perform it only **after the entire inventory/order transaction has committed** ...
```

## Check one query's performance

First, list the top queries over a time window.  Times are UTC. `dimension` can be `total_duration`,
`avg_duration`, `invocations`, `rows`, `shared_blks_read` and more
(`mcporter call dbgorilla.discover_workloads component_id=$C` lists them all).

```bash
mcporter call dbgorilla.get_top_workload component_id=$C dimension=total_duration \
  start=2026-11-07T00:00:00Z end=2026-11-07T15:57:45Z limit=3
```
```
Top workload ranked by total_duration (3):
  | # | total_duration (ms) | invocations | avg_duration (ms) | user           | fingerprint      |
  |---|---|---|---|---|---|
  | 1 | 1705691             | 17295       | 98.6234           | storefront_app | 44fc11468e033234 |
  | 2 | 396130              | 10133       | 39.0931           | storefront_app | 9024d46808bd1a0d |
  | 3 | 227169              | 33840       | 6.71303           | storefront_app | a93b7f3312b4c328 |
```

If you get `No workload items found`, the window has no data.  Move it closer to now.

Then view one query's details using its `fingerprint`:

```bash
mcporter call dbgorilla.investigate_workload component_id=$C fingerprint=44fc11468e033234 \
  start=2026-11-07T00:00:00Z end=2026-11-07T15:57:45Z
```
```
Workload fingerprint=44fc11468e033234:
  description: SELECT date_trunc($2, placed_at)::date AS month, count(*), COALESCE(sum(total_cents), $3)
               FROM storefront.orders WHERE EXTRACT($4 FROM placed_at) = $1 GROUP BY 1 ORDER BY sum(total_cents) DESC
  invocations=17295
  avg_duration=98.6234 ms
  total_duration=1705691 ms
  rows=121065 total
  shared_blks_hit=15886192 total
  shared_blks_read=0 total
  trend (14 buckets of 3600s ...):
    | bucket               | invocations | avg_duration (ms) | total_duration (ms) | ...
    | 2026-11-07T02:00:00Z | 203         | 98.0274           | 19899.6             | ...
    | 2026-11-07T03:00:00Z | 1347        | 104.361           | 140575              | ...
    ...
```

## Sign out

```bash
mcporter config logout dbgorilla
```
```
Cleared cached credentials for 'dbgorilla'
```

This clears the saved sign-in for Option A.  Do not use `mcporter auth dbgorilla --reset` to sign
out: it clears the sign-in and then immediately opens a new one.  For Option B, delete the key in
**Profile > MCP Access > Delete API Key**, and run `unset DBGORILLA_API_KEY`.

## Related

- [Connect an MCP client by hand](/docs/integrations/mcp-client/)
- [MCP server](/docs/reference/mcp-tools/), including [the read-only set of tools](/docs/reference/mcp-tools/#the-read-only-set-of-tools)