> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blackbox.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Chat With Your Database

> Use BLACKBOX CLI to connect to your database and ask questions in plain English. Database tools run read-only queries and keep the connection active during your session for quick follow-ups.

## Supported databases

* PostgreSQL
* MySQL
* MongoDB
* Redis

## Setup

Configuring DB credentials following the steps below, allow you to securely store the credentials in `DB_CONNECTION_URI` environment variable and it is not directly exposed to the model context.

##### Option A (recommended): configure once per machine

Run the interactive DB configuration to save your connection URI and reuse it across sessions.

```text theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
/db configure
```

The wizard will:

* Ask you to pick a database type
* Prompt for a connection URI (input is hidden)
* Save it as `DB_CONNECTION_URI` and apply it to the current session

<Tip>
  Tips:

  * Use a read-only database user
  * If you have multiple databases, mention which one you want to connect to
</Tip>

##### Option B: Configure on request

If you miss to configure prior to the request, the model would automatically invoke the configuration screen during DB analysing requests.

## Step-by-step usage

##### Step 1: Start a session

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
blackbox
```

##### Step 2: Configure your DB connection (optional, but recommended)

```text theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
/db configure
```

if you skip this step, you can configure during the session when model invokes the configuraiton workflow automatically.

##### Step 3: Ask questions (read-only)

BLACKBOX CLI will connect (if needed), inspect schema, and translate your request into safe read-only queries.

```text theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
> show the top 10 products by total revenue last quarter
```

```text theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
> list users who signed up in the last 30 days
```

```text theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
> summarize orders by status and sort by count
```

##### Step 4: Refine and iterate

You can keep asking follow-up questions without reconnecting.

```text theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
> break that down by country
```

```text theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
> only include customers with more than 5 orders
```

<Note>
  The connection stays active in the current session. Start a new session (or re-run `/db configure`) if you need to switch databases.
</Note>

## Examples by database

##### PostgreSQL

Configure once:

```text theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
/db configure
```

Then ask:

```text theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
> find the top 5 customers by lifetime value
```

One-off (no saved config):

```text theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
> find the top 5 customers by lifetime value
```

##### MySQL

```text theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
/db configure
```

```text theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
> list products with low inventory and their suppliers
```

One-off:

```text theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
> list products with low inventory and their suppliers. connect to mysql using mysql://readonly_user:password@db.example.com:3306/store
```

##### MongoDB

If your MongoDB URI includes a database name (path), it can connect directly:

```text theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
> connect to mongodb using mongodb://readonly_user:password@db.example.com:27017/ecommerce and show the collections
```

If you omit the DB name in the URI, include it in your request when asked.

```text theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
> connect to mongodb using mongodb://readonly_user:password@db.example.com:27017 and use the database named ecommerce
```

##### Redis

```text theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
/db configure
```

```text theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
> list keys that match user:* and show 10 examples
```

```text theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
> connect to redis and get the value of user:123
```

## Best practices

* Be specific about the data you want and the time range
* Ask for a quick schema overview if you are unsure of table or field names
* Start broad, then narrow down with follow-up prompts
* Use a dedicated read-only database account for safety

## Troubleshooting

* "DB\_CONNECTION\_URI is not configured": run `/db configure`, then retry your request
* Connection errors: verify host, port, username, password, and database name
* Permission errors: confirm the account has read access to the tables/collections
* Unexpected results: ask to show the exact query that was run, then refine your request