Help Center
Everything you need to get started and troubleshoot SQLAgent.
Database Guides
Setup, security, permissions, and troubleshooting for each database engine.
Error Reference
Complete list of error messages with explanations and fixes.
General
Can I save connections?
Yes. After connecting, your connection is automatically saved in the connection manager. Credentials are stored locally on your Mac — they never leave your machine. Saved connections appear as chips on the connection form for quick reconnection. For SQLite, recently opened databases are also shown with file path, status, and relative timestamps.
Does SQLAgent support SSL/TLS?
Yes. You can enable SSL in the connection form with optional client certificate authentication (CA cert, client cert, client key). Available on both MySQL and PostgreSQL. See the MySQL or PostgreSQL guide for details.
What is the security banner on the connection form?
Before you connect, SQLAgent shows a security & permissions banner tailored to each database engine. It summarizes your connection's encryption status, authentication method, and permission model. See each engine's guide for details.
Features
SQL Editor
Write and run SQL queries with syntax highlighting, auto-completion, and query history. Access it from the sidebar or with the keyboard shortcut.
Import & Export
Export tables as SQL dumps or CSV files. Import SQL files to run migrations or restore backups. Available from the Database menu or the sidebar.
AI SQL Assistant (Free)
Describe what you want in plain English and let AI generate the SQL for you. Supports multi-turn refinement. Free for all users — bring your own API key. Supports Anthropic Claude, OpenAI GPT, xAI Grok, Ollama (local, free), and OpenRouter.
Database Analytics (Pro)
Get an overview of your database: table sizes, row counts, index usage, and storage stats. Useful for monitoring and optimization.
Performance
Why does SQLAgent feel instant?
SQLAgent uses aggressive caching and memoization throughout the stack. Column schemas are cached per table — switching back to a previously viewed table loads instantly from memory. Number, date, and byte formatters are allocated once as static properties, never recreated during renders. Saved connection profiles are decoded from storage once and served from an in-memory cache on subsequent reads.
How does D1 minimize API calls?
When fetching table row counts, SQLAgent batches all counts into a single UNION ALL query instead of making individual API calls per table. This reduces network round-trips from N+1 to just 2 (one for the table list, one for all counts). Column schemas are also cached, so revisiting a table never re-fetches metadata.
Does SQLAgent use polling or timers?
No. The menu bar icon and UI updates use Swift's Observation framework to react to state changes, instead of polling on a timer. This means zero CPU usage when nothing is changing, and instant updates when something does.
Troubleshooting
"SQLAgent.app is damaged and can't be opened"
This is a macOS Gatekeeper warning. Open System Settings → Privacy & Security and click Open Anyway next to the SQLAgent message. Alternatively, right-click the app and select Open.
Connection timeout or refused
Check that your database server is running and accessible from your network. Verify the host, port, and credentials. If you're behind a firewall, make sure the port is open. For cloud databases, check that your IP is whitelisted.
SSL handshake errors
Make sure your certificates are in PEM format. The CA certificate, client certificate, and client key must all be valid and match. Try toggling Verify server certificate if connecting to a self-signed server.
App not showing in menu bar
SQLAgent always shows a menu bar icon. If it disappears, the app may have crashed. Relaunch it from your Applications folder. If the icon appears but looks wrong, run lsregister -f /Applications/SQLAgent.app in Terminal to refresh the icon cache.
Why Mac Only?
SQLAgent is currently available only on macOS. This is a deliberate choice, not a limitation.
We wanted to build a real Mac app — not a wrapped web page, not an Electron shell. SQLAgent is built entirely with Swift, SwiftUI, and Cocoa frameworks. That means native performance, native text editing, Keychain integration, system notifications, Finder integration, haptic feedback — all the things that make a Mac app feel like a Mac app.
We do this partly for the craft, partly for the culture. There's value in exploring what Apple's frameworks can do and pushing them to their full potential. The result is an app that launches instantly, uses ~50 MB of memory, and fits naturally into the macOS ecosystem.
The origin story
SQLAgent was built for us first. Originally, it was created to replace Adminer for our own daily workflow — managing Cloudflare D1 databases during app development. The core routine was simple: connect to a database, check configuration in a core_data_config table, run a few queries, and move on. We needed something fast, reliable, and native for that weekly routine.
The best features of SQLAgent grew out of that daily use. Keyboard shortcuts were added to speed up the queries we ran every day. The AI assistant was added because writing SQL by hand for routine checks felt unnecessary. Export and import were added because we kept needing them. Every feature exists because we needed it ourselves.
That's why SQLAgent feels opinionated — it was built by database users, for database users, on the platform we use every day.
The daily routine — under 10 seconds
Here's the exact workflow SQLAgent was built for. What takes a minute in other database clients takes less than 10 seconds in SQLAgent:
Launch the app — ~100ms startup. No splash screen, no loading spinner.
Connect — saved profiles reconnect near-instantly on local databases.
Click the database — table list loads immediately.
⌘F — open search. Type core + Enter — results appear instantly.
↓ arrow down to select the table — Enter to open it.
⌘F again — type e.g. url. The search automatically detects the value type and searches only in compatible columns.
Done. Results are on screen. The whole thing took seconds, not minutes.
When a view has multiple search fields (like the table view), ← and → arrow keys switch between them — so you never need to reach for the mouse.
This is what native performance means in practice. Not benchmarks — time saved on your daily routine.