AI Assistant

The AI Assistant combines the active database, schema, SQL, errors, result preview, and explicitly mentioned objects into context for SQL generation, explanation, optimization, error repair, and data analysis.

Ask mode produces suggestions. Agent mode can call query tools when the user explicitly requests real data. Any model output can be wrong. Review the target, fields, filters, parameters, and affected scope before executing SQL.

Model Integrations

API Providers

DBX includes presets for:

Claude
OpenAI
Gemini
DeepSeek
Qwen
MiniMax
Ollama
OpenAI Compatible
Anthropic Compatible
Custom

Compatible and custom configurations can set the endpoint, model, API style, authentication method, proxy, and context window. API styles include OpenAI-style completions, the Responses API, and Anthropic Messages. When supported, DBX discovers models and filters out endpoints that are not suitable for assistant or Agent use.

Local CLI Agents

Desktop can also invoke locally installed and authenticated:

Claude Code CLI
Codex CLI
Pi Coding Agent

You can configure the executable path and additional environment variables. CLI Agents run on the Desktop computer and access the active database through DBX-scoped MCP tools. Docker/Web hides these local CLI providers because the server cannot assume the browser computer has the commands installed.

Add a Configuration

Open AI Settings

Add a named AI configuration in editor settings. Multiple endpoints or credentials can be saved for the same provider.

Choose Provider and Model

Use a preset, compatible API, custom endpoint, or local CLI. Models are discovered from the provider or CLI when possible and can otherwise be entered manually. Manually entered models are saved with the current configuration and remain selectable when a compatible provider does not expose model discovery or discovery fails.

Configure Authentication and Reasoning

API modes accept an API key, auth method, endpoint, and proxy. Supported models expose effort, reasoning, or thinking controls based on provider capabilities rather than one universal setting.

Test and Save

The test reports success, latency, effective model, and categorized failures such as authentication, rate limit, timeout, or missing model.

API keys, CLI environment variables, and custom endpoints may be sensitive. Do not share configuration screenshots, exports, or debug logs with untrusted parties.

Ask and Agent

Mode	Best for	Tool and execution behavior
Ask	Generate, explain, optimize, repair, or translate SQL, and provide advice from existing context	Does not proactively query the database; final answers should distinguish suggestions from verified results
Agent	Requests such as “get the result,” “compare real data,” or “inspect schema first” that require iterative evidence	Can list tables, read columns, sample data, and run read-only queries; writes require exact confirmation

Agent should execute a query only when the original request explicitly asks for real data or results. A request to “write a query” should return SQL without running it, even in Agent mode.

Agent Turns and Retries

Maximum Agent turns defaults to 30 and can be set from 5 to 500. It bounds model, tool, and repair-loop iterations
Maximum API retries defaults to 2 and can be set from 0 to 10 for rate limits, timeouts, and transient network errors. Claude Code, Codex, and Pi CLI providers do not use this API retry setting
The Agent stops when it reaches the turn limit, is cancelled, loses the connection, or is rejected by tool policy, while retaining completed steps and errors

Increasing the turn limit raises latency, database reads, and model cost. Prefer clear prompts, explicit table mentions, and narrower scope before raising the limit.

Schema, Table, and SQL File Context

AI context can include:

Database type, connection name, database, and schema
Current or selected editor SQL and the latest error
Tables, columns, indexes, foreign keys, and limited sample rows
A bounded preview of the current result
Selected prompt templates
Referenced saved SQL file content

Type @ in the prompt to search tables and saved SQL files:

@users prioritizes metadata for users
@public.orders selects a schema-qualified table
Multiple tables or SQL files can be selected together

Large schemas are truncated. Explicit mentions are more reliable than asking the model to guess among every object, and they reduce tokens and metadata requests.

Global Instructions and Prompt Templates

Settings can store:

Global instructions injected into every request, such as naming rules, time zone, soft-delete conventions, or production constraints
Prompt templates for reusable scenarios, such as “PostgreSQL-compatible SQL only” or “include index recommendations in every analysis”

Multiple templates can be active at once. DBX snapshots the selected templates and global instructions when the request is sent, so later edits do not alter an already running task.

Templates enter model context. Do not put passwords, tokens, or unnecessary business data in them. Keep rules concise and non-conflicting because models may not resolve contradictory instructions as expected.

Writes and Production Safety

AI Agent execution boundaries are enforced by the backend, not only by prompting:

Read-only tools can be called as needed
Non-read-only SQL must first be shown as an explicit proposal
User confirmation binds authorization to the same connection, same database, and exact SQL text
Authorization applies only to the next run and never becomes a permanent write grant
AI Agents cannot receive write or DDL authorization for production databases; they can only return SQL for manual review in DBX

Connection read-only protection, production protection, and database credentials remain upper bounds. A target change, SQL change, empty confirmation, or failed backend risk classification voids the grant.

AI Agent never receives “write from now on” permission and cannot bypass MCP policy, connection read-only protection, or database privileges. See Production Safety for the complete boundary.

Reasoning Effort and Thinking

Providers expose different mechanisms: enumerated effort, reasoning levels, boolean thinking, integer budgets, or free-text options. DBX shows controls from the active model capability and remembers the selection per configuration and model.

Use provider default or lower effort for simple generation and explanation
Increase effort for multi-table reasoning, difficult optimization, or error diagnosis
Higher effort usually increases latency and cost without guaranteeing correctness

Do not assume one UI label has identical semantics across providers.

Conversations, History, and Export

Use ↑ and ↓ to navigate prompt history
Conversations can be saved with connection and database context
Final AI analysis messages can be exported as Markdown with connection name and timestamp
Markdown export contains the final answer only; internal reasoning and Agent steps are not appended

Exports can still contain table names, SQL, result snippets, and business data. Review and redact them before sharing.

Common Tasks

Generate SQL

Using @orders and @customers, generate a top-10 customer revenue query for the last 30 days. Return SQL only and do not execute it.

Explicitly saying “do not execute” clarifies intent. Review date functions, schema qualification, join keys, null handling, and row limits.

Analyze Real Data

Query daily order counts from @orders for the last seven days, run the read-only query, and explain unusual spikes.

This is appropriate for Agent mode because it explicitly requests real results.

Repair an Error

Provide the failed SQL, database error, and related tables. AI can inspect columns and dialect context, but version-specific behavior, privileges, locks, and execution plans still require human verification.

Privacy and Troubleshooting

Cloud providers receive the prompt, schema summary, SQL, and bounded result context sent to the model; their privacy terms apply
Ollama and local CLI can run locally, but the model process or CLI plugins may still have their own network and logging behavior
Proxies, compatible endpoints, and custom gateways may log request content
For connection-test failures, check endpoint, auth method, model name, proxy, and API-style compatibility
When Agent repeatedly fails, reduce context, mention exact tables, narrow the task, and inspect tool errors instead of only increasing the turn limit