Getting Started · Article 01

Quickstart - five minutes to your first query.

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 - Windows is coming soon. No background services, no account required.

bash

# 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 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 that stays smooth on large result sets, 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 the macOS Keychain - 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.