Skip to main content

​
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:[email protected]:3306/store

​
MongoDB

If your MongoDB URI includes a database name (path), it can connect directly: 
> connect to mongodb using mongodb://readonly_user:[email protected]: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:[email protected]: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