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.
Option A (recommended): configure once per machine
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
Step 2: Configure your DB connection (optional, but recommended)
/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