DBX

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.

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

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, proxy, and custom HTTP headers. Use headers for gateway authentication or tenant routing, for example X-GoModel-User-Path: /dbx-assistant; they are sent for model discovery, connection tests, chat, and Agent requests. 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, 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

ModeBest forTool and execution behavior
AskGenerate, explain, optimize, repair, or translate SQL, and provide advice from existing contextDoes not proactively query the database; final answers should distinguish suggestions from verified results
AgentRequests such as “get the result,” “compare real data,” or “inspect schema first” that require iterative evidenceCan 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 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
  • Table and column notes from the connection's notes file, which take precedence over database comments
  • 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 use read-only SKILL.md rule files 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.

Only each skill's name and description reach the model, as a listing. A skill's body is loaded on demand: when the model decides it needs one it calls the use_skill tool, and only then does DBX read the body from disk and return it. Files a skill ships (references, scripts, templates) are read one by one with read_skill_file. DBX never writes to skill files, and reading a file's content is never permission to run it.

Select skills from the composer Skills entry (or type /skill); selected skills appear as chips above the input and can be removed at any time. Selecting is not exclusive: the user-selected entries are marked in the listing and take priority, but the model may also load an unticked skill from that same listing. With Settings → AI → Allow the AI to use skills automatically turned on (off by default) the listing is sent with every request even when nothing is selected, so the model can pick a skill on its own.

A chip has two states: its default state, and loaded in this conversation. A chip gains the loaded marker once the model has called use_skill for that skill, or once you loaded it yourself. Clicking a chip loads that skill immediately: DBX reads the body there and then and puts it into the conversation, so the following turns answer with it. The loaded state is per conversation — it survives closing and reopening the AI panel, and a new conversation starts over. What DBX remembers after a restart is that the skill was loaded: the body is read from disk again when the next request needs it, so a skill that was deleted or grew past the read limit in the meantime goes back to its unloaded state and says why. While a selected skill has not been loaded yet, a one-time hint above the input offers to load it (each conversation shows that hint once).

Skills are available to DBX's built-in AI only. A CLI provider (Claude Code, Codex, Cursor, OpenCode, Grok, Qoder, CodeBuddy, Pi) receives no listing, no skill body, and no skill tools; its skill selector is disabled with the reason shown, and skills that were already selected stay visible and removable.

Because loading is on demand, nothing is read at send time: a deleted or unreadable file, invalid frontmatter, or a body that is not UTF-8 text now fails when the skill is loaded instead of blocking the send. The one exception is a checked skill that is no longer in the catalog: sending stays blocked, with a banner above the composer naming the failed skill and offering Retry, Refresh, Remove, or Open Settings. Files over the 1 MiB limit, binary files, and paths that leave a skill directory are refused. With no skills selected and the toggle off, 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.

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.

SQL Block Actions

Each SQL block in a reply offers Temp run, Execute, and Apply to editor. All three target the query tab that belongs to the conversation's own connection, database, and schema — the connection the conversation is bound to, never whichever editor happens to be in front.

That tab is created in the background when it does not exist yet, and the action never moves your workspace: an AI action does not switch, select, or open tabs on its own.

Because the result therefore does not always land where you are looking, the block reports its own outcome:

  • The block shows Executing…, then the row count (returned or affected) or the database's error text.
  • When the target tab is not on screen, a notification names that tab and offers View; only clicking View brings it to the front.
  • Requests that never reached the database say why in the block instead: no available connection, an editor tab still busy with another request, or nothing to execute.

Dangerous-SQL, production, parameter, and read-only confirmations keep their own dialogs; those are not repeated in the block or as a notification.

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