> ## Documentation Index
> Fetch the complete documentation index at: https://ngquct-feat-ai-sql-walkthroughs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# AI Assistant
> Built-in AI for SQL: chat with tool calling, inline suggestions, explain, optimize, and fix-error across 13 providers.
# AI Assistant
Built-in AI for writing, explaining, optimizing, and fixing SQL. One active provider drives every AI feature: chat, inline suggestions, editor actions, and fix-error. Provider keys stay in the macOS Keychain.
## Configure a Provider
Open **Settings** (`Cmd+,`) > **AI**. The **Enable AI Features** toggle at the top gates the whole tab; turning it off also hides the per-connection AI policy in the connection form.
1. Click **Add Provider...** and pick a type: GitHub Copilot, ChatGPT, Cursor, Claude, OpenAI, OpenRouter, OpenCode Zen, Gemini, xAI, Ollama, llama.cpp, MLX, or a custom OpenAI-compatible endpoint.
2. Enter the API key, or sign in for Copilot, ChatGPT, Cursor, and xAI.
3. Enter a model name, or pick one from the fetched list.
4. Click **Test Connection**.
The **Active Provider** picker at the top selects which provider handles AI requests. For reasoning models (Claude, OpenAI, xAI, ChatGPT), the provider detail sheet adds a per-model reasoning effort picker. Reasoning replies render their thinking in a collapsible **Reasoning** block above the answer.
Provider notes:
* **GitHub Copilot**: signs in with GitHub's device flow. Tool calls go through Copilot's tool bridge and the same approval flow as other providers.
* **ChatGPT**: sign in with your ChatGPT account to use the Codex quota from Plus, Pro, Business, and Enterprise plans, no API key. **Import from Codex CLI** reuses an existing Codex login. Unofficial interface; may change.
* **Cursor**: paste an API key from the Cursor dashboard, or leave it blank and click **Sign in with Cursor** (needs the Cursor CLI installed). Cursor runs as an agent, not a chat-completions endpoint. It cannot call TablePro's database tools, so Edit and Agent modes do not run queries through it.
* **xAI**: paste an API key, or click **Sign in with xAI** to use a SuperGrok or X Premium+ subscription. Sign-in opens a Grok Build consent screen; this path is unofficial and may change. Preset models: Grok 4.5 and Grok 4.3.
* **Ollama, llama.cpp, MLX**: local providers, no API key. Each preset fills in its default endpoint (`http://localhost:11434` for Ollama, `http://localhost:8080` for `llama-server` and `mlx_lm.server`); edit it if you moved the host or port. Start the server first, then **Test Connection** and pick a model from the fetched list. llama.cpp and MLX speak the OpenAI-compatible API; for tool calling, start `llama-server` with `--jinja`. For any other OpenAI-compatible server, use the custom endpoint.
## Chat
Open the inspector (`Cmd+Option+I` or the toolbar inspector button) and switch the segmented control at the top from **Details** to **AI Chat**. There is no dedicated chat shortcut or menu item.
Type a question and press Return. Code blocks have **Copy** and **Insert** buttons; Insert fills the current query tab if it is empty, otherwise opens a new tab. Token counts show below each response. Failed responses show **Retry**, successful ones **Regenerate**, and **Stop** cancels a streaming reply.
Conversations auto-save and auto-title from your first message. The clock icon in the inspector header opens recent conversations; the pencil-and-square icon starts a new one. Editing a previously sent message puts its text and context attachments back in the composer and removes that turn and everything after it; send to re-run.
If the provider supports images (Claude, OpenAI, xAI), paste or drag images into the composer. They appear as thumbnail chips and are sent with your message.
### Chat Modes (Ask / Edit / Agent)
The mode picker in the composer footer controls which tools the AI can call. The mode is an app-level setting: it persists across chats and restarts, and fresh installs start in **Ask**.
| Mode | Tools available | When to use |
| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| **Ask** | Read-only schema lookups: `list_connections`, `get_connection_status`, `list_databases`, `list_schemas`, `list_tables`, `describe_table`, `get_table_ddl`. | Questions, exploration, drafting queries you run yourself. |
| **Edit** | All Ask tools, plus `execute_query` for `SELECT`, `INSERT`, `UPDATE`, `DELETE`. Destructive DDL (`DROP`, `TRUNCATE`, `ALTER...DROP`) stays blocked. | Letting the AI run the queries it proposes. |
| **Agent** | All tools, plus `confirm_destructive_operation` for destructive DDL. Runs tools in a loop, up to 10 round trips per turn. | Multi-step migrations and schema changes. |
Mode and [safe mode](/features/safe-mode) are independent gates. Agent mode does not bypass safe mode.
### Tool Calling
In Edit and Agent modes, each tool call appears as a card in the reply. Read-only tools run immediately. Write tools show three buttons:
* **Run**: approve this single call.
* **Always for this connection**: approve and whitelist the tool for this connection. Whitelists are per-tool and per-connection, and sync with the connection via iCloud.
* **Cancel**: reject the call. The model gets an error result and continues.
If the connection's safe-mode level is **Silent**, write tools auto-approve. If it is **Read Only**, they auto-deny. Destructive operations are the exception: `confirm_destructive_operation` always requires a per-call click. Silent mode does not auto-approve it, and **Always for this connection** is refused for it. The tool also requires the model to pass the verbatim phrase `I understand this is irreversible`.
Provider support for tool calling: every provider except Cursor. Ollama, llama.cpp, MLX, and custom endpoints depend on the model.
### Attach Context with `@`
Type `@` in the composer to open a picker at the caret: **Schema**, a specific **Table**, **Current Query**, **Query Results**, or a **Saved Query** ([favorites](/features/favorites)). Up/Down navigates, Return or Tab inserts, Escape dismisses. The `@` button in the composer footer offers the same items minus saved queries.
Attached items show as chips. Saved query chips resolve at send time, so the AI sees the query's current SQL.
### Slash Commands
Type `/` to run a command: **`/explain`**, **`/optimize`**, and **`/fix`** act on the active query; **`/help`** lists commands. Add your own under **Settings** > **AI** > **Custom Slash Commands**. Templates substitute `{{query}}`, `{{schema}}`, `{{database}}`, and `{{body}}` (text typed after the command) at send time.
### Model Picker
The cpu icon next to the mode picker lists every configured provider and its models. Your pick overrides the active provider for this chat panel and stays until you pick something else; it does not reset between turns.
## Per-Connection AI Rules
Pin plain-text context to a connection so the AI sees it on every turn: open the connection's edit form and pick **AI Rules** in the sidebar. Use it for facts the schema cannot show, like `Always filter orders by deleted_at IS NULL` or `Never select users.ssn`. The text is appended to the system prompt and syncs with the connection via iCloud.
## Inline Suggestions
Toggle **Enable inline suggestions while typing** in the AI tab (off by default). After you pause typing, the active provider suggests a completion rendered as ghost text at the cursor. Press `Tab` to accept, `Escape` to dismiss; typing anything else also dismisses it.
The pause length is the **Debounce** setting next to the toggle: 500 ms by default, adjustable from 100 to 3000 ms. With Copilot active, suggestions come from Copilot's inline-completion model; any other provider serves them through chat completions.
## Editor Actions
Right-click SQL in the editor for **Explain with AI** (`Cmd+L`) and **Optimize with AI** (`Cmd+Option+L`). Rebind them under **Settings** > **Keyboard** in the **Editor & Query** category.
## Fix with AI
When a query fails, the inline error banner above the results shows a **Fix with AI** button. It opens chat with the failed query and error pre-filled.
## SQL Walkthroughs
Explain, Optimize, and Fix answer with a walkthrough in the chat panel instead of plain text, so you can review the change before trusting it:
* **Before/after diff.** Optimize and Fix show a diff between your query and the AI's version. Switch between **Unified** and **Split** with the toggle in the walkthrough header. Explain shows the query with the steps anchored to it.
* **Numbered steps.** Each step has a one-line reason and an importance tag (**Critical**, **Change**, or **Context**). Expand a step to see the exact lines it refers to, and **Show in diff** scrolls to and highlights them.
* **Ask about a step.** Use **Ask about this change** on any step to send a follow-up question that stays anchored to that step.
* **Apply to Editor.** When the AI rewrote your query, **Apply to Editor** replaces the editor content after you confirm. Nothing is applied automatically.
The AI writes the steps and the rewritten query; TablePro computes the diff itself, so the diff always reflects the real change. If a model returns plain prose instead, the response renders as normal text.
## Context
Under **Settings** > **AI** > **Context**:
| Setting | Default |
| ----------------------- | ------- |
| Include database schema | On |
| Include current query | On |
| Include query results | Off |
| Max schema tables | 20 |
## Privacy
Set a per-connection AI policy in the connection form's **Advanced** tab: **Use Default**, **Always Allow**, **Ask Each Time**, or **Never**. The app-wide default is **Ask Each Time**. **Never** also blocks external AI tool calls against the connection.
External clients (Raycast, Claude Desktop, and other MCP clients) reach the same tools through the [External API](/external-api/index), capped by the connection's **External Clients** level and the token's scope; see [Tokens](/external-api/tokens).