Documentation

Install

Homebrew (recommended):

brew trust pounceapps/tap
brew install --cask pounceapps/tap/pouncesql

Homebrew 6.0+ requires trusting a third-party tap once before it will install from it; brew trust records that. 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), then choose an Authentication mode:

• Password — your role + password, with an SSL mode (Prefer / Require / Disable). Best for local, LAN, Tailscale, or a Postgres you run yourself.
• AWS IAM — connect to AWS RDS/Aurora with your AWS login instead of a password (see below).

Click Connect & List Databases to pin the whole server (browse every database) or add one database directly.

AWS RDS & Aurora — sign in with AWS (IAM)

PounceSQL can authenticate to Amazon RDS/Aurora PostgreSQL using your AWS login — no database password. On each connect it mints a short-lived token from your AWS session and connects over TLS validated against Amazon's RDS certificate authority (bundled in the app). It's the AWS analog of the Azure az login flow.

Each time you connect

1. Sign in to AWS in a terminal — whichever your account uses: aws sso login (SSO, most work accounts) or aws configure (access keys).
2. In the PostgreSQL tab, set Authentication to AWS IAM, enter the RDS/Aurora endpoint and the database user; the Region fills in from the endpoint. Leave the password blank.
3. If you're already signed in via the CLI you don't need the Sign in to AWS button (that only starts a new SSO session) — just click Connect & List Databases.

One-time setup (database admin)

1. Enable IAM DB authentication on the instance (RDS → Modify).
2. Grant the database role permission to use IAM: GRANT rds_iam TO your_db_user;. Note this makes that role IAM-only (no more password), so prefer a dedicated user over the master.
3. Attach an IAM policy allowing rds-db:connect to your AWS user/role, scoped to that database user and the instance's Resource ID (arn:aws:rds-db:REGION:ACCOUNT:dbuser:db-XXXX/your_db_user).
4. Make the instance reachable: allow your IP on port 5432 in the security group, and ensure it's reachable from your network.
5. IAM policy changes can take a minute or two to take effect.

Troubleshooting: password authentication failed means the role isn't set for IAM yet; PAM authentication failed means the IAM path is active but the token was rejected (missing rds-db:connect, or still propagating); a timeout is the network path (security group / public access).

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.

Sync between Macs (1Password)

PounceSQL can carry your setup to another Mac through a 1Password vault you choose. It syncs AI provider settings and keys, your theme, and your fonts and sizes. It does not sync databases, connections, hosts, or query history — those stay on the machine you added them on.

Setup

1. Install the 1Password CLI:

   brew install 1password-cli

2. In the 1Password app, turn on Settings → Developer → Integrate with 1Password CLI.
3. In PounceSQL, open Settings → Sync and click Connect. 1Password asks you to authorize the connection once — if you don't see the prompt, check behind other windows.
4. Pick the vault to use (or create one in 1Password first, e.g. a Pounce vault). The choice is remembered on this Mac.

Push & pull

Push saves a snapshot of this Mac's AI settings, theme, and fonts into the vault. Pull reads the snapshot and shows a side-by-side list — one row per item, marked add, override, unchanged, or local only — and you tick which rows to apply. Nothing is written locally until you confirm, and pulling never deletes settings you have here.

Secrets are masked in the preview (only the last few characters show) and are stored encrypted in 1Password. Each app writes one item, named Pounce — PounceSQL. Turn on Share AI settings to keep AI keys in a single shared Pounce — AI item instead, so PounceSQL, PounceTERM, and PouncePad read the same keys.

The panel shows a Last synced line, and reminds you to push or pull when this Mac has fallen behind.

Reset sync

Reset sync… forgets this Mac's vault choice and the Share-AI toggle — nothing in 1Password is touched. The same dialog optionally deletes this app's item from the vault. It never deletes the vault itself, other apps' items, or the shared Pounce — AI item.

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.