GitHub - Geometrein/surus: Agentic Postgres companion — with the right guardrails to safely point an LLM at your production database. · GitHub
/" data-turbo-transient="true" />
Skip to content
Search or jump to...
Search code, repositories, users, issues, pull requests...
-->
Search
Clear
Search syntax tips
Provide feedback
--><br>We read every piece of feedback, and take your input very seriously.
Include my email address so I can be contacted
Cancel
Submit feedback
Saved searches
Use saved searches to filter your results more quickly
-->
Name
Query
To see all available qualifiers, see our documentation.
Cancel
Create saved search
Sign in
/;ref_cta:Sign up;ref_loc:header logged out"}"<br>Sign up
Appearance settings
Resetting focus
You signed in with another tab or window. Reload to refresh your session.<br>You signed out in another tab or window. Reload to refresh your session.<br>You switched accounts on another tab or window. Reload to refresh your session.
Dismiss alert
{{ message }}
Geometrein
surus
Public
Notifications<br>You must be signed in to change notification settings
Fork
Star
master
BranchesTags
Go to file
CodeOpen more actions menu
Folders and files<br>NameNameLast commit message<br>Last commit date<br>Latest commit
History<br>1 Commit<br>1 Commit
.github/workflows
.github/workflows
backend
backend
frontend
frontend
images
images
scripts
scripts
tests
tests
.gitignore
.gitignore
LICENSE.md
LICENSE.md
Makefile
Makefile
README.md
README.md
pyproject.toml
pyproject.toml
run
run
uv.lock
uv.lock
View all files
Repository files navigation
Surus
Agentic Postgres companion — with the right guardrails to safely point LLMs at your prod DB.
Features ·<br>Quickstart ·<br>Desktop app
Design
Surus is a Postgres companion client with a built-in agent.<br>The design philosophy is built around 3 core principles.
1. Tight Text-to-SQL Loop.<br>The agent runs a loop: draft a query -> run EXPLAIN -> evaluate the plan, iterate. What lands in your editor has already been fitted and optimized to your data and DB performance.
2. Read-only by design. The agent always stays read-only. It runs on a read-only connection pool — writes fail at the database level. You can opt into write mode from the editor to run your own INSERT/UPDATE/DELETE; the agent never touches that pool.
3. Your data stays private by default. The agent reasons over schema, table statistics, and EXPLAIN plans.
The companion can be run as a local web app or a native MacOS app.
Features
IDE
Modern SQL editor with a results grid, CSV export and one-click data visualization
Saved queries organized in git friendly directory structure
Query parameters and selection-only execution
Agent
Tight Text-to-SQL loop that uses query plans and schema stats to optimize queries.
Anthropic and OpenAI providers with configurable prompts, step/token limits and tool timeouts
Three chat modes:
SQL: Turn a plain text request into a performant SQL query
Question: Answer questions about your data in plain text
Teach: Build the query, then walk through every clause and why it's written that way
Schema and stats context is prompt-cached and extension-aware — persistent chat history.
"Explain with AI" helper for EXPLAIN queries and errors.
ERD
Auto generated ERD diagram with pan, zoom, and drag-to-reposition tables
Foreign key highlighting, with hover-to-trace relationships between tables
Filter to related tables only, or search by name and schema
Logs
Full query log tagged by who ran it — you, the agent, or the app
Duration, row count, and errors tracked per query, color-coded by execution speed
Filter by level or free text, with auto-scroll and jump-to-latest
Quickstart
Prerequisites
Python ≥ 3.11 and uv
Node ≥ 20 and npm
Docker — only for the optional demo database
make setup # install backend (uv) + frontend (npm) deps<br>make demo-db # optional: spin up a demo Postgres in Docker<br>make dev # backend :8765 + frontend :5173 → open http://localhost:5173
On first launch:
Add a connection (sidebar +). For the demo DB: host localhost, port 55432, database demo, user/pass postgres.
Set your API key in the chat settings to enable the agent.
The demo database (make demo-db) runs timescale/timescaledb-ha:pg16 — Postgres 16 with TimescaleDB and PostGIS enabled, seeded with sample tables, so you can see the extension-aware introspection work out of the box. Re-running the target is idempotent.
MacOS app
The same UI and backend ship as a native desktop app — a Tauri v2 shell that spawns the backend as a sidecar on 127.0.0.1:8765 and tears it down on exit.
make tauri-dev # native window against the dev backend (hot reload; needs Rust)<br>make app # freeze the backend (PyInstaller) + package Surus.app / .dmg
make app output lands in build/tauri/release/bundle/. The bundle is self-contained — it embeds the frozen Python backend and the built frontend, so it runs without the repo, uv, or a system Python. Builds are currently...