Documentation

Install

Homebrew (recommended):

brew install --cask senzalldev/tap/pouncesql

Upgrade later with brew upgrade --cask pouncesql.

Direct download: grab the latest .dmg from the releases page, open it, and drag PounceSQL into Applications. The app is Developer-ID signed and notarized, so it opens without a Gatekeeper prompt.

Requirements: macOS 13+ (Apple Silicon).

First run

Launch PounceSQL and click + Add in the left panel to connect your first database. The Add connection wizard has a tab for each engine — pick the one you need. Once connected, databases appear in the tree on the left; expand them to browse schemas, tables, and columns.

Azure SQL

Azure SQL uses your Azure CLI session — no passwords are stored.

1. Install the CLI: brew install azure-cli
2. Sign in: az login (or click the account chip in the title bar).
3. In the wizard's Azure SQL tab, browse your subscriptions → servers → databases and pick one to pin.

SQL Server (2017–2025+)

Connect to local or domain-joined SQL Server. In the wizard's SQL Server tab, enter the server (host, host:1433, or host\instance) and choose an authentication mode:

• SQL Server login — username + password.
• Windows / domain (NTLM) — DOMAIN\user + password. Works from a Mac that isn't domain-joined.
• Kerberos (SSO — no password) — click Get Kerberos ticket to run kinit; your password is entered at the OS prompt and never stored in PounceSQL. Requires an MSSQLSvc SPN registered for the server.

Pin the whole server to browse every database it hosts, or add a single database directly.

PostgreSQL

In the PostgreSQL tab, enter the server (host or host:5432), your role, and password, then pick an SSL mode (Prefer / Require / Disable). Click Connect & List Databases to pin the whole server (browse every database) or add one database directly.

SQLite

In the SQLite tab, click Browse… and pick a .db / .sqlite file. No server or login is needed — PounceSQL opens the file and lists its tables.

Browsing & queries

• Expand a database to see tables and views; expand a table to see its columns (primary keys and nullability marked).
• Double-click a table to preview its rows.
• Right-click a table for actions — Select Top N, Row Count, Describe Schema, List Columns, Show Indexes — each generated in the correct dialect for the engine (LIMIT vs TOP, etc.).
• Filter box searches databases and tables, including databases nested under a server.
• Run queries with F5 or ⌘↵. Results appear in the grid below; multiple query tabs are supported.

AI assistant

Open the AI panel (the robot icon in the title bar, or the panel on the right) and ask in plain English. The assistant is grounded in the schema you're connected to, writes SQL in the correct dialect for the engine, and can inspect tables and run read-only queries itself to answer — then render the result as a diagram, chart, table or KPI cards.

• Quick model switcher — the model icon next to New chat lists every configured model across all providers; pick one and it switches live. The status bar shows the active model.
• Run just a selection — highlight part of the editor and F5 runs only that; otherwise the whole editor runs.
• Per-message usage — token counts appear under each answer; session totals, top model and estimated spend are on the About page.

AI providers

Configure providers in Settings → AI Provider. Each provider remembers its own endpoint, model and key, so you can swap freely and everything is kept. Endpoint URLs are shown (and editable) with sensible defaults.

• OpenAI and Anthropic — direct API key, with native tool-calling for both. Pick from a model dropdown (Claude Sonnet/Haiku/Opus, GPT-4o, …) or type any model id.
• Ollama (local / LAN) — see below.
• AI API gateway — see below.

Google (Gemini) is intentionally not offered — its tool-calling is unreliable for the agentic schema/query workflow PounceSQL uses.

Local models (Ollama)

Run models entirely on your own machine or network — your data never leaves it, which is ideal for sensitive or PHI work. In Settings → AI Provider → Direct → Ollama (Local / LAN):

1. Set the endpoint to your Ollama server — http://localhost:11434, a LAN address, or a Tailscale IP (http://100.x.x.x:11434) if the machine isn't on your local network.
2. Click Load models to populate the dropdown from the server's /api/tags, and pick one.

Use an instruct model for tool-calling (e.g. qwen2.5:14b-instruct, llama3.1:8b). Coder-only and Gemma variants don't emit structured tool calls, so they can't drive the schema/query workflow.

AI gateway (bring your own)

PounceSQL works with an OAuth2 (client-credentials) AI gateway that exposes a model-discovery endpoint and an OpenAI-compatible chat endpoint. In Settings → AI API GW, paste or import the credentials JSON, then Test Gateway & Discover Models. Secrets are stored only in the encrypted local settings file. The model dropdown shows each model's cost per 1k tokens and a PHI-cleared badge from discovery, and PounceSQL routes each model by its native format (OpenAI-style models to /chat/completions, Claude models to the Anthropic /messages endpoint).

Implementing your own gateway needs three things:

1. An OAuth2 token endpoint (client-credentials grant).
2. A discovery endpoint returning { "models": [ … ] }, where each model has id, api_format (openai/anthropic), optional phi_allowed + cost + context_window.
3. An OpenAI-compatible /chat/completions (and, for Claude models, an Anthropic-format /messages) endpoint that accepts the bearer token + an X-Api-Key header.

Diagrams, charts & rich output

Ask the assistant to visualize and it renders the result inline:

• Diagrams — “diagram this schema” produces a Mermaid ER diagram (it reads real keys first); it can also draw flowcharts, sequence, gantt and more.
• Charts — “chart sales by month” runs the query and renders a bar/line/pie chart (Chart.js), themed to match the app.
• Heatmaps, KPI metric cards, and sortable result grids with one-click CSV / JSON export.
• Full Markdown (tables, lists), syntax-highlighted code with Copy / Use-in-editor, and LaTeX for formulas.
• Any diagram or chart can be saved as PNG.

Chat history

Your last 50 conversations are saved automatically on your machine. The clock icon in the AI header opens the history viewer — browse, reload, or delete a chat, and export any conversation as Markdown. Nothing is sent anywhere.

MCP server

PounceSQL runs a local Model Context Protocol server so agents like Claude Code can drive it. In Settings → MCP Server you'll find the SSE endpoint (http://127.0.0.1:7457/sse) and a one-line command to add it:

claude mcp add --transport sse pouncesql http://127.0.0.1:7457/sse

Agents can then list databases, run queries, browse schema, and read logs — and you watch the actions happen live in the app. Writes are blocked unless you enable them in Settings → Tools.

Themes & fonts

Settings → Themes offers a dozen editor themes (One Dark, Dracula, Monokai, Nord, Tokyo Night, Light, and more). Settings → Fonts lets you choose separate fonts for the interface and the editor, and set independent sizes for the editor, the tree/lists, the results grid, and the UI. Quick A− / A+ buttons in the tree header adjust the list size on the fly.

Security & PHI

• All secrets — connection passwords, API keys (including per-provider keys), gateway credentials — are stored only in an encrypted local settings file (AES-256-GCM); the key lives in your login keychain. They're never displayed in the UI (fields show a “saved” marker) and never sent anywhere but the provider.
• The AI assistant and MCP server are read-only by default — writes (INSERT/UPDATE/DELETE/DDL) require explicitly enabling them in Settings → Tools.
• Azure SQL uses your az login session; Kerberos uses a ticket — neither stores a password.
• PHI: for gateway models, a PHI OK / NO PHI pill reflects the selected model's clearance from discovery. For maximum control, run a local Ollama model so data never leaves your machine.
• Connection errors and logs are scrubbed of embedded passwords before they can reach the UI or MCP.