Documentation

Getting Started

SequelPG is a native macOS PostgreSQL client written in SwiftUI. The current release is v0.3.1 and requires macOS 14.4 (Sonoma) or later. Download a pre-built .app from the download page or build from source with Xcode 15+.

On first launch the start page lists your saved connections. Add one with the + button, or pick the Appearance submenu under the app menu if you want to preview the light theme before connecting.

Connections

Click + on the start page to add a connection. Profiles are stored in UserDefaults; passwords live in the macOS Keychain (cached in memory after the first read so you aren't re-prompted when switching between tabs).

Test validates the credentials without opening a session. Connect opens a session inside the current tab. The badge dot in the tab bar turns lime once a connection is live.

SSH Tunnels

For databases behind a firewall or bastion, expand the SSH Tunnel section in the connection form. SequelPG shells out to the system ssh binary, allocates a free local port, and tears the tunnel down on disconnect.

Tabs & Windows

Press ⌘T to open a new tab inside the current window — iTerm-style. Each tab carries its own connection, navigator state, and tab content (Structure / Content / Definition / Query). You can connect different profiles in different tabs and switch between them without disconnecting.

The four main tabs at the top of the workspace are bound to ⌘1 (Structure), ⌘2 (Content), ⌘3 (Definition), and ⌘4 (Query). The object-tab strip above them holds per-object workspaces — each opened object remembers its own filters, pagination, sort, and inspector state.

Navigator

The Navigator sidebar shows a hierarchical tree of databases, schemas, and 17 object categories (tables, views, materialized views, functions, procedures, sequences, types, domains, indexes, constraints, triggers, extensions, roles, foreign tables, partitioned tables, casts, and event triggers). Categories adapt to the server version — Procedures only appear on PostgreSQL 11+, for example.

Right-click any node for a context menu — create or drop the underlying object, jump to its Definition, or run the relevant statement directly. Expand a different database in the tree to browse it without closing the current connection.

Structure

The Structure tab shows the schema of the selected object. For tables this includes column name, data type, nullable status, default value, and a type pill indicator (violet for built-ins, mauve for user-defined, amber for JSON/JSONB, cyan for date/time).

Sub-sections below the columns list indexes (with btree / hash / partial / unique tags), constraints (PK, FK, CHECK, UNIQUE), triggers, and partitions when applicable.

Content

The Content tab is a native AppKit grid (DataGridView) with type-aware cell rendering, vertical cell dividers, column sorting, and multi-select. Numeric, money, inet, cidr, macaddr, jsonb, and composite types are decoded from PostgreSQL's binary wire format for accuracy and speed.

Rows are paginated at 50 / 100 / 200 per page. Approximate row counts come from pg_class.reltuples (with a fallback to COUNT(*) when the planner stat is stale). A hard cap of 2000 rows applies to ad-hoc queries to avoid runaway memory.

Editing

Single-click a cell to enter inline edit mode; press ↩ to save or ⎋ to cancel. Long text, JSON, arrays, and booleans get a richer editor in the Inspector panel on the right. Insert row and Delete row live in the bottom toolbar — deletes that violate a foreign key prompt for a cascade option instead of silently failing.

Filtering

Press ⌘F to toggle the filter bar above the grid. Pick a column, an operator (=, ≠, ~, IS NULL, etc.), and a value; SequelPG previews the generated WHERE clause so you can verify the SQL before applying it.

Definition

The Definition tab is a read-only DDL/source viewer for non-table objects — views, materialized views, functions, procedures, sequences, types, and domains. The full CREATE statement is shown with SQL syntax highlighting and selectable for copy-out.

Query

The Query tab is the SQL editor + results pane. Write a statement and press ⌘↩ (or click Run) to execute. Results render in the same AppKit grid as the Content tab, with execution time displayed alongside the row count.

Other toolbar actions: Stop cancels the running statement client-side; Clear resets the editor; Beautify reformats the query; Explain and Analyze hand off to the EXPLAIN visualizer (see below).

A server-side statement_timeout of 10 seconds is set on each session. When a SELECT returns zero rows the grid still renders the column headers — resolved from table metadata — so the result schema is always visible.

SQL Editor

Syntax Highlighting

Keywords, identifiers, strings, comments, numbers, operators, and type names are colored from a single editorial palette that resolves to the dark or light variant based on the current appearance. Highlighting runs on every edit through a custom NSTextStorage tokenizer.

Autocompletion

Suggestions fire after 2 characters and rank JetBrains-style: prefix matches always beat fuzzy matches (typing sele always lands on SELECT, never SECURITY), with case-insensitive fuzzy fallback for partials like usp → user_profile. The top confident match is pre-selected so Tab / ↩ commits without arrow-down.

The popup is context-aware: a lightweight pass over the tokens preceding the cursor figures out the clause and biases the candidate pool. After FROM / JOIN / UPDATE / INSERT INTO it favors tables and views; after SELECT / WHERE / ON / GROUP BY / ORDER BY / SET / RETURNING it favors columns. A qualifier (users.email) restricts columns to that table.

Beautify

Beautify reformats the buffer with proper indentation and line breaks. It also auto-quotes mixed-case identifiers so queries against case-sensitive tables and columns keep working without manual "...".

EXPLAIN Visualizer

Two buttons in the Query toolbar surface PostgreSQL's plan information without leaving the app:

• Explain — runs EXPLAIN (no execution, no impact on production data) and shows the predicted plan.
• Analyze — runs EXPLAIN (ANALYZE, BUFFERS) and shows what actually happened, including row estimates vs. actuals and buffer counters.

Results render in the EXPLAIN tab as a vertical tree of plain-English steps — "Read the whole orders table," "Match rows using a hash table," "Sort by created_at" — with a one-sentence summary, a metrics row (took / returned / loops / cost), and findings chips that flag bad row estimates, dominant time hogs, filter waste, and Nested-Loop-over-Seq-Scan anti-patterns. A right-side detail card exposes the raw PostgreSQL fields (Sort Method, Hash Cond, buffer counters, etc.) for anyone who wants them.

Query History

Toggle the bottom history panel with ⌘⇧Y. Every statement — including the system queries SequelPG runs for introspection — is logged with timestamp, duration, and success indicator. Click a row to copy it back into the editor.

Object Creation

Right-click a category in the Navigator (e.g. Tables, Views) for a Create… action. Sheets are available for:

• Databases and schemas
• Tables and views
• Functions and sequences
• Types and domains
• Indexes (B-tree, hash, partial, unique)

Sheets generate the underlying DDL — you can inspect or edit it before submitting. Drops are available from the same context menu with a confirmation dialog.

Schema Editing

On the Structure tab for a table you can add or drop columns, rename them, change their type, and toggle the NOT NULL flag — each action runs the corresponding ALTER TABLE with the SQL visible in Query History after the fact.

Database Tools

The server.rack button in the toolbar opens a menu of database-level tools:

• Extensions… — install, drop, or upgrade PostgreSQL extensions (pg_trgm, pgcrypto, uuid-ossp, etc.).
• Roles & Privileges… — browse roles, group memberships, and grants.
• Function Library… — a searchable reference of built-in PostgreSQL functions with a Run dialog for ad-hoc invocation.

Inspector

Toggle the right Inspector panel with the toolbar sidebar.right button. Its contents change with context:

• When a table is selected — object name, approximate row count, column count, and a list of indexes / constraints.
• When a row is selected in Content view — every field with its raw value and a type-aware editor (JSON formatter, array editor, boolean toggle, long-text textarea).

Appearance

SequelPG ships a warm-charcoal dark theme and a warm-cream light theme. Pick a mode from the Appearance submenu under the app menu, or open ⌘, Settings for the picker:

• Auto — follow the system Light/Dark setting and switch live when macOS toggles.
• Light — warm cream canvas with a darker phosphor lime accent tuned for legibility on light backgrounds.
• Dark — the original warm charcoal with the bright phosphor-lime accent.

All chrome, the SQL editor, the syntax highlighter, the results grid, and the type pills resolve to the right palette for each mode. Your choice is saved per-user and survives restarts.

Keyboard Shortcuts