Getting Started

Quickstart

From zero to running your first query in minutes. This guide covers the three things you'll do every day: install pgen, connect to a Postgres database, and write SQL.

Prerequisites

You need a Postgres database to connect to - local, cloud, or via SSH tunnel. If you don't have one, we'll spin up a local one in step 2.

1. Install pgen

pgen ships as a single-file download for macOS and Windows. No installer, no background services, no account required.

# Download and drag pgen to Applications
curl -LO https://pgendb.com/download/pgen.dmg
open pgen.dmg

2. Connect to a database

Launch pgen. The first thing you'll see is the connection wizard.

screenshot

Connection wizard · first launch

The connection wizard supports URL strings, individual fields, and SSH tunnels.

1
Click 'New connection'
Use ⌘+N on Mac or Ctrl+N on Windows as a shortcut.
2
Paste a connection string - or fill fields by hand
The fastest way is to paste a full URL. pgen parses it and fills in the rest:
bash
```
postgresql://user:password@localhost:5432/mydb
```
3
Test and save
Hit Test - pgen attempts a real connection and shows the server version on success. Then Save to keep it in your sidebar.

No database yet?

Run docker run -e POSTGRES_PASSWORD=pg -p 5432:5432 postgres for a throwaway local instance. Then connect with postgresql://postgres:pg@localhost:5432/postgres.

3. Write your first query

Press ⌘+T to open a new SQL tab. pgen opens with autocomplete live - start typing and it reads your catalog, not just keywords:

query.sql

1
2
3
4
5
6
7
8
9
10
11
12
-- pgen autocompletes table & column names from your live schema
SELECT
  u.id,
  u.email,
  COUNT(o.id) AS order_count,
  SUM(o.total) AS lifetime_value
FROM users u
LEFT JOIN orders o ON o.user_id = u.id
WHERE u.created_at > '2026-01-01'
GROUP BY u.id, u.email
ORDER BY lifetime_value DESC
LIMIT 25;

Run the query with ⌘+↵. Results appear below in a virtualized grid - 400k rows scroll at 60fps, and you can edit cells inline.

Tab shortcuts

⌘+T new tab · ⌘+W close tab · Ctrl+Tab next · Ctrl+Shift+Tab previous. On macOS, ⌘+⌥+→ and ⌘+⌥+← also cycle tabs.

4. Turn on the AI assistant (optional)

The AI assistant is bring-your-own-key. pgen never proxies your data through our servers - prompts go directly from your machine to the provider you choose.

Keys are stored in your OS keychain

API keys never leave your machine. They're stored in macOS Keychain or Windows Credential Manager - the same place your Wi-Fi passwords live.

1
Open Settings → AI Assistant
Use ⌘+, and pick the AI tab.
2
Choose a provider
Supported out of the box: Anthropic (Claude), OpenAI (GPT), Google (Gemini), Ollama for local models, and a Custom option for any OpenAI-compatible endpoint (LM Studio, vLLM, Groq, Together, your own gateway).
3
Paste your key and test
pgen runs a small test completion to confirm the key works. After that, ⌘+I opens the AI side panel in any SQL tab.