GRESUI — A fast, friendly PostgreSQL client for your desktop

gresui is a app for browsing PostgreSQL databases, built with Deno and React. Tbh there was ai coding in this, code was reviewed. I did this because I found that I had a necessity for a simpler and good looking postgres client without all the visual clutter pgadmin gives. feel free to do what you want with this. I decided to share this because it ended up being useful for me, hopefully also for you.

Install

The easiest way (npm, any OS):

npm install -g gresui

This installs Deno automatically, downloads and builds the app for your OS, and puts gresui on your PATH. Requires Node.js 22+ and internet access; on Linux a package-manager sudo may be needed if the npm global prefix is root-owned.

Newer npm versions (>= 11.6) block install scripts by default — if the install finishes without building, the first gresui run builds it, or install eagerly with:

npm install -g --allow-scripts=gresui gresui

Alternative — the shell installer:

curl -fsSL https://raw.githubusercontent.com/FrancisTCE/gresui/main/scripts/install.sh | sh

After install, run gresui from the terminal. See Prerequisites for required tooling. The installer can optionally add a pre-configured read-only sample database (EMBL-EBI Pfam).

Features

• Connection management with save/delete
• Schema and table browser sidebar
• Data grid with filtering, sorting, and pagination
• SQL editor with syntax highlighting and history
• EXPLAIN support
• Full CRUD operations (insert, update, delete)
• Dark and light themes

Prerequisites

• Deno 2.x
• Node.js 22+ (for frontend tooling)
• Docker (optional, for the test database)

Quick start (dev mode)

# 1. Install frontend dependencies
npm install

# 2. Build the React frontend once
deno task web:build

# 3. Start the dev server with hot-reload
deno task dev

# 4. (Optional) Spin up a local PostgreSQL 17 test database on port 15432
deno task db:up

Building a standalone binary

deno task pkg

Produces ./build/gresui/ with the packaged app.

Running tests

# Start the test database, then run the suite
deno task db:up
deno test -A

Integration tests connect to postgres://postgres:[email protected]:15432/gresui_dev.

Development workflow

main is PR-only: direct pushes to it are rejected. Create a branch, push it, and open a pull request to merge.

After cloning, enable the client-side guard (rejects any push to main):

git config core.hooksPath .githooks

Configuration & data storage

All config — connections, settings, SQL history — lives in a single SQLite database (gresui.db) in the config directory:

| OS | Location | |---------|------------------------------------------------------| | Linux | $XDG_CONFIG_HOME/gresui or ~/.config/gresui | | macOS | ~/Library/Application Support/gresui | | Windows | %APPDATA%\gresui |

GRESUI_CONFIG_DIR overrides the location (used by tests; also handy for portable setups). The directory is created mode 0700 and gresui.db mode 0600. Pre-SQLite connections.json / settings.json / history.json files are imported once on first launch, then removed.

Security

Connection passwords are encrypted at rest with AES-256-GCM under a per-machine random key, decrypted only in-process when the app reads them.

• Key storage: the key lives in the OS keychain where available — macOS Keychain, Linux Secret Service (GNOME/KDE keyring) — otherwise in a 0600 gresui.key file in the config directory (headless Linux, Windows v1).
• Keychain migration: existing file-key installs move the key into the keychain automatically on the next launch with a keychain present; the file is then removed, so config-dir backups stop carrying the key.
• Key loss: if the key can't be found (keychain entry deleted, config dir wiped), stored passwords read as empty — reconnect and re-enter them; the next save re-encrypts.
• Troubleshooting: GRESUI_KEY_SOURCE=file|keychain|auto forces a provider (useful on headless machines or to re-run keychain migration).

What this protects against: exposure of the database file alone (backups, sync tools, file indexing, casual reads). It does not defend against full compromise of the running app or, on Linux, same-user processes — the Secret Service answers the same user without prompting.

Architecture

The backend (main.ts, src/backend/) is a Deno process running a loopback-only HTTP static file server (never exposed beyond 127.0.0.1) and a PostgreSQL driver wrapper (postgres.js). It exposes typed RPC bindings to the webview frontend.

The frontend (web/src/) is a React 19 SPA built with Vite 7, Tailwind CSS 4, and Radix UI primitives. It renders inside a deno desktop webview.

Shared types (shared/types.ts, shared/rpc.ts) define the RPC contract between backend and frontend.

Tech stack

| Backend | Frontend | |-----------------------|-----------------------------------| | Deno | React 19 | | postgres.js | Vite 7 | | deno desktop (webview)| Tailwind CSS 4 | | | Radix UI | | | CodeMirror (SQL editor) | | | TanStack Table / Virtual |

License

MIT — see LICENSE.