AI Assistant

The AI Assistant combines the connection, database, and schema bound to the current conversation with editor SQL, errors, result preview, and explicitly mentioned objects into context for SQL generation, explanation, optimization, error repair, and data analysis. Each conversation keeps its own binding, so conversations on different connections never share a target.

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, context window, and extra HTTP headers. 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

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

Ask and Agent

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 editor SQL and the latest error, once the open editor is on the conversation's own connection and database — plus any editor selection you explicitly sent over
• 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

Send an Editor Selection to AI

Select text in the SQL editor and choose Send to AI from the context menu (or its shortcut). The selection appears as a removable chip above the prompt, and the input box stays empty and focused for your own question. The selection travels as data, not as an instruction: an -- ignore previous instructions comment inside it is never treated as a command.

The conversation target comes from the editor tab the selection was taken in:

• Same connection, database, and schema as the current conversation — the conversation is reused
• A different namespace — a new conversation is opened and bound to that tab; an existing conversation's binding is never rewritten
• The tab's connection was deleted — the chat stays unbound and says so, and you pick a connection before sending

A single selection is capped at 12,000 characters; anything beyond that is truncated and the chip is marked as truncated. Fix with AI under a query error follows the same rules.

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 can also be marked as the default for one or more database types (star icon next to a template in Settings → AI). When the AI panel opens on a connection of that database type — or after switching to a different connection, database, or schema — the matching defaults are applied automatically, subject to the same total content limit as manual selection. When no defaults are configured for the current database type, a newly opened panel restores the templates last used with that database type; sending with no templates selected clears that remembered selection. Switching connection, database, or schema applies only explicit defaults — with none configured, the selection starts empty rather than restored. Manual deselection always wins until the next panel open or namespace switch.

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.

Skills (SKILL.md)

Desktop can attach read-only SKILL.md rule files to a request as supplementary instructions. Skills are always discovered in ~/.agents/skills; Settings → AI can additionally enable one custom directory. Each directory is validated independently, same names are kept side by side and labeled by source (Default directory / Custom directory), and custom-directory skills sort first.

Select skills from the composer Skills entry (or type /skill) and remove them from the chips above the input. The selection lives for the lifetime of one open AI panel — conversation switches and new conversations keep it; closing the panel or restarting DBX clears it. Nothing is persisted, and DBX never writes to skill files.

Skill bodies are read only when a request is sent, directly from disk, and validated then: file deleted or unreadable, invalid frontmatter, non-UTF-8 content, over the 1 MiB per-file limit, or a symlink escaping its root blocks the send with a banner above the composer naming the failed skill and offering Retry, Refresh, Remove, or Open Settings. With no skills selected, prompts are byte-for-byte identical to the pre-feature behavior. Web ships this feature unsupported.

Plugin Tools

In Agent mode with an API provider, the assistant can also call tools contributed by installed plugins — for example run a command over SSH, read container logs, or inspect Kafka consumer lag — and combine them with database tools in one answer.

1. Plugin tools are opt-in per plugin: open Plugin Center → Installed, select the plugin, and turn on the Built-in AI tools switch — until then the assistant cannot call the plugin's tools. Use Show tools to list what the assistant would get and which tools need approval. Switch it off to exclude a plugin (the choice persists).
2. Open the plugin connection the assistant should use (for example the SSH server). Tools only run against connections that are open.
3. Ask in Agent mode. Tools the plugin declares read-only run directly; any other call pauses the run and shows the exact arguments with Allow once / Deny. Unanswered requests are denied after five minutes, and Stop cancels a pending request.

When bound to a plugin connection, the assistant shows the plugin logo and hides the database/schema selectors. It skips database metadata loading and offers only the time utility and enabled plugin tools in Agent mode.

Tool output is sent to your AI model like query results. Turn the Built-in AI tools switch off for plugins whose data should not reach the model. Turning it off also blocks subsequent calls from a run already in progress. CLI agent providers do not receive plugin tools.

Writes and Production Safety

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

1. Read-only tools can be called as needed
2. Non-read-only SQL must first be shown as an explicit proposal
3. User confirmation binds authorization to the same connection, same database, and exact SQL text
4. Authorization applies only to the next run and never becomes a permanent write grant
5. 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.

Redis connections use a read-only command tool instead of SQL. The assistant can run commands DBX classifies as read-only (SCAN, GET, TYPE, TTL, HGET, …) and answer from their results. Commands that write or that are blocked (SET, DEL, EXPIRE, EVAL, KEYS, CONFIG, …) are never executed by the agent: it returns the command as a fenced code block for you to run in the Redis console, which asks for confirmation first. SELECT is not available either — the logical database is chosen with the tool's db argument.

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
• Each conversation is saved with its own connection, database, and schema binding, and restores it when reopened
• 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

Related Features