Search⌘K
CLI › Documentation › Chat With Your Database

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.

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

/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

Tips:

  • Use a read-only database user
  • If you have multiple databases, mention which one you want to connect to
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
blackbox
/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.

> show the top 10 products by total revenue last quarter
> list users who signed up in the last 30 days
> summarize orders by status and sort by count
Step 4: Refine and iterate

You can keep asking follow-up questions without reconnecting.

> break that down by country
> only include customers with more than 5 orders

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

Examples by database

PostgreSQL

Configure once:

/db configure

Then ask:

> find the top 5 customers by lifetime value

One-off (no saved config):

> find the top 5 customers by lifetime value
MySQL
/db configure
> list products with low inventory and their suppliers

One-off:

> 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:

> 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.

> connect to mongodb using mongodb://readonly_user:password@db.example.com:27017 and use the database named ecommerce
Redis
/db configure
> list keys that match user:* and show 10 examples
> 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