Documentation

Getting Started

SequelPG is a native macOS PostgreSQL client written in SwiftUI. The current release is v0.3.6 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 Connection validates the credentials without opening a session. Connect opens a session in the current window; the window title changes to the connection name and the subtitle to the database you’re in.

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

Every connection is its own window. Press ⌘T to open the next one as a native macOS window tab of the current window (or ⌘N for a separate window); the system tab bar handles reordering, tearing a tab off, and merging windows. Each window carries its own connection, navigator state, and workspace, and closing it disconnects its session.

The mode switcher in the toolbar — Structure, Content, Definition, Query, Diagram — is bound to ⌘1 through ⌘5. Selecting another object in the navigator keeps the current mode (the first object you open switches to Structure or Definition). The object-tab strip above the workspace holds per-object workspaces — each opened object remembers its own filters, pagination, sort, and inspector state; right-click a tab to close the others.

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, run a function or procedure, or issue VACUUM / ANALYZE / TRUNCATE / REFRESH directly. Expand a different database in the tree to browse it without closing the current connection, or double-click it to switch. The filter field at the bottom of the sidebar narrows the tree to matching objects; the + menu next to it creates databases, schemas, and tables, and the options menu toggles the advanced object categories.

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. For tables, double-click a column’s name, type, or default to edit it in place, use the checkbox to toggle NOT NULL, and the + / − buttons in the bottom bar to add or drop columns.

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

Double-click a cell to open its editor — a plain field for text, and richer editors for long text, JSON, arrays, and booleans; press ⌘↩ to save or ⎋ to cancel. The same editors are available from the Inspector on the right. Insert row (+ in the bottom bar) opens a form listing every column with its type, NOT NULL, default, and identity status and flags the required ones; empty fields fall back to the column default. Delete row (−, or the Delete key) prompts for a cascade option when a foreign key would be violated instead of silently failing.

Filtering

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

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 syntax palette that resolves to the dark or light variant based on the current appearance. Highlighting runs on every edit through a custom NSTextStorage tokenizer. The editor font — SF Mono, JetBrains Mono, or Menlo, 10 to 20 pt — is set in Settings → Editor and applies live to the editor and the Definition view.

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. In DDL, the object a statement acts on outranks keywords — typing DROP SCHEMA … ranks your schema names above VACUUM.

The popup is a purpose-built, JetBrains-style panel rather than the native macOS list: each row carries a kind chip (keyword, table, column, schema, function), the characters you’ve typed are bolded in the accent color, and a type detail sits on the right. ↑ / ↓ move through the list, and you can click a row to accept it; accepting leaves the caret at the end of the inserted text with nothing selected. Prefer to type without interruptions? Turn off “Suggest completions while typing” in ⌘, Settings → SQL Editor — the popup then only appears when you ask for it with ⎋ or ⌃Space.

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 Inspector with the toolbar button or ⌥⌘I. It is a native inspector column, resizable like any other; 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 — the standard macOS light appearance.
• Dark — the standard macOS dark appearance.

Window chrome uses the system’s semantic colors and respects the accent color chosen in System Settings; with the “multicolor” accent you get SequelPG’s own lime. 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