Getting Started

Table of contents

System Requirements

  • macOS 26 (Tahoe) or later
  • A PostgreSQL server (local or remote) to connect to

Installation 

brew tap NeodymiumPhish/pharos && brew install --cask pharos

Download from GitHub Releases

  1. Go to the Pharos Releases page
  2. Download the DMG for your Mac’s architecture (Apple Silicon or Intel)
  3. Open the DMG and drag Pharos to your Applications folder
  4. Launch Pharos from Applications or Spotlight

Build from Source

  1. Clone the repository: 
    git clone https://github.com/NeodymiumPhish/Pharos.git
cd Pharos
  2. Build the Rust core library: 
    cd pharos-core
cargo build --release
cd ..
  3. Open the Xcode project and build (Cmd+B), then run (Cmd+R)

Building from source requires Xcode and a Rust toolchain installed via rustup.

The Main Window

The Pharos window has three panes:

  • Sidebar (left, toggle with Cmd+Ctrl+S) — one panel with three navigators, switched by the grouped selector in the window toolbar above it, level with the window buttons (or from View > Navigators, Cmd+Opt+1 to Cmd+Opt+3). Pressing the icon that is already selected hides the sidebar; pressing it again brings it back. The three navigators are: Library (with a scope bar for Sessions, your saved tabs with their results, and History, your workspaces and past queries), Files (the DuckDB databases and data files you opened; see DuckDB), and Database Navigator (the schema browser). Query variables and tags have their own windows: Window > Variable Manager and Window > Tag Manager, also the two buttons at the right of the window toolbar. A Filter field along the BOTTOM of the sidebar narrows whichever list is showing — Cmd+Opt+J puts the caret in it, and each list remembers its own filter text. A + pull-down sits beside the field in Sessions (New Session, New Folder).
  • Content area (center) — the query editor with its header row, above the results area (grid, chart or plan) and its action bar. Each editor tab is a stack of query cards, one statement per card.
  • Inspector (right, toggle with Cmd+Opt+I) — row details, selection statistics, and schema object details. Collapsed by default.

Connections are chosen per editor tab from the Connection pop-up button at the start of the editor’s header row (the tab’s context row) — there is no global connection selector. Every editor tab is a native macOS window tab: the window title is the tab’s name, and the subtitle under it reads “connection · schema”. See Tab Management.

Creating Your First Connection

  1. Press Cmd+Shift+N or choose File > Manage Connections… to open the Connections Manager window
  2. Click the + button in the window’s toolbar
  3. Fill in the connection details:
    • Name — a friendly label (e.g., “Local Dev”)
    • Host — the server address
    • Port — the PostgreSQL port (5432 by default)
    • Database — the database name
    • Username and Password
    • SSL Mode — Prefer, Require, or Disable
  4. Click Test Connection to verify — on success, the latency is shown and the Default Schema menu is populated
  5. Click Save

Then, at the start of the editor’s header row, open the Connection pop-up button and choose your connection. Pharos connects it at once. The Database Navigator panel populates with your schema, and you’re ready to run queries. The Schema pop-up button after the connection pins one schema for the tab (or All Schemas); it is also where you set a connection’s default schema.

Running Your First Query

  1. Type a query in the card, for example SELECT * FROM my_table LIMIT 100;
  2. Press Cmd+Return to run the card
  3. Results appear in the grid below — sort, filter, chart, or export them from the action bar
  4. Press Ctrl+Cmd+N to add a new card for your next query

Next Steps

Pharos — A native macOS PostgreSQL client built with Swift and Rust.

This site uses Just the Docs, a documentation theme for Jekyll.