How to Use Harlequin SQL IDE with Upsun

The Upsun CLI includes upsun sql, a quick way to run queries against your database from the command line. But sometimes you want more than a basic prompt. You want autocomplete, syntax highlighting, a visual schema browser, and the ability to scroll through large result sets. That’s where Harlequin comes in. Harlequin is a terminal-based (TUI) SQL IDE that brings a rich, interactive experience to your shell. It includes a data catalog for browsing tables and columns, a query editor with autocompletion, and a results viewer that handles millions of rows. All without leaving your terminal. This tutorial covers two ways to use Harlequin with your Upsun PostgreSQL database:

Run Harlequin locally and connect through an SSH tunnel
Install Harlequin on your Upsun environment and access it via SSH

Both approaches give you the same powerful interface. Choose the one that fits your workflow.

Harlequin's interface showing the data catalog, query editor, and results pane

Prerequisites

Before you start, make sure you have:

An Upsun account with a project deployed
A PostgreSQL service configured in your .upsun/config.yaml
The Upsun CLI installed and authenticated
For Option 1: Python 3.10+ and uv (or pip) installed locally

Your project should have a PostgreSQL service defined. If you don’t have one yet, add this to your .upsun/config.yaml:

services:
  postgresql:
    type: postgresql:16

applications:
  myapp:
    # ... your app config
    relationships:
      database: "postgresql:postgresql"

Option 1: Run Harlequin locally with an SSH tunnel

This approach keeps Harlequin on your local machine and connects to Upsun through a secure SSH tunnel. It’s ideal for day-to-day development when you want quick access to your database without modifying your deployment.

Install Harlequin with the PostgreSQL adapter

Harlequin uses adapters to connect to different database types. Install both Harlequin and its PostgreSQL adapter:

uv tool install 'harlequin[postgres]'

Alternatively, you can use pip:

pip install harlequin harlequin-postgres

Or Homebrew on macOS:

brew install harlequin

Verify the installation:

harlequin --version
harlequin, version 2.5.0

Installed Adapters:
  - duckdb, version 2.5.0
  - sqlite, version 2.5.0
  - postgres, version 1.3.0

Open an SSH tunnel to your Upsun services

The Upsun CLI can create SSH tunnels to all services in your environment. Run:

upsun tunnel:open

You’ll see output similar to:

upsun tunnel:open
Enter a number to choose an app:
  [0] api
  [1] chainlit
  [2] next
 > 0

SSH tunnel opened to postgresql at: postgresql://main:main@127.0.0.1:30000/main
SSH tunnel opened to cache at: valkey://127.0.0.1:30001

Logs are written to: /Users/nls/.upsun-cli/tunnels.log

List tunnels with: upsun tunnels
View tunnel details with: upsun tunnel:info
Close tunnels with: upsun tunnel:close

Save encoded tunnel details to the PLATFORM_RELATIONSHIPS variable using:
  export PLATFORM_RELATIONSHIPS="$(upsun tunnel:info --encode)"

Note the connection details. In this example:

Host: 127.0.0.1
Port: 30000
Username: main
Password: main
Database: main

Your values may differ depending on your configuration.

Connect Harlequin to the tunnel

With the tunnel open, launch Harlequin using the connection details:

harlequin -a postgres "postgres://main:main@127.0.0.1:30000/main"

You can also pass the connection parameters individually:

harlequin -a postgres -h 127.0.0.1 -p 30000 -U main --password main -d main

Harlequin opens in your terminal, ready to explore your database.

Explore your database

Once connected, you can:

Browse the data catalog: The left sidebar shows all schemas, tables, and columns in your database
Write queries: The center pane is a full-featured editor with syntax highlighting and autocomplete (press Ctrl+Space to trigger suggestions)
View results: Execute queries with Ctrl+Enter and scroll through results in the bottom pane
Export data: Select results and export to CSV, JSON, or Parquet formats

Press F1 to see all keyboard shortcuts. When you’re done, close the tunnel:

upsun tunnel:close

Option 2: Install Harlequin on Upsun

If you prefer to keep your tools on the platform, or want consistent access for your team, you can install Harlequin directly in your Upsun environment. Since Harlequin is a terminal UI, you’ll access it by SSH-ing into your container.

Add Harlequin to your build hook

Modify your .upsun/config.yaml to install Harlequin during the build phase. Add the pip install command to your existing build hook:

applications:
  myapp:
    type: python:3.13
    dependencies:
      python3:
        uv: "*"
    hooks:
      build: |
        set -eux
        uv tool install --python 3.13 'harlequin[postgres]'
        # Add your other build commands here

    relationships:
      database: "postgresql:postgresql"

    # ... rest of your config

If your application isn’t Python-based, you can still install Harlequin. Python is available in most Upsun containers. Add a build hook that installs it:

applications:
  myapp:
    type: nodejs:22  # or php:8.3, etc.
    dependencies:
      python3:
        uv: "*"
    hooks:
      build: |
        set -eux
        uv tool install --python 3.13 'harlequin[postgres]'
        # Your other build commands

    relationships:
      database: "postgresql:postgresql"

    # ... rest of your config

Deploy your changes

Commit and push your configuration changes:

git add .upsun/config.yaml
git commit -m "Add Harlequin SQL IDE"
upsun push

Wait for the deployment to complete.

SSH into your environment

Connect to your running container:

upsun ssh

Launch Harlequin

Upsun generate one environment variable for the database DSN automatically (see Service Environment variables):

web@api.0:~$ env | grep DATABASE
DATABASE_URL=postgresql://main:main@postgresql.internal:5432/main

The name can vary as it is using the relationships name in the myapp section of the .upsun/config.yaml file (e.g. database: in the example above) You can now launch Harlequin:

/app/.local/bin/harlequin -a postgres $DATABASE_URL

If you want to avoid specifying the whole path, update your PATH variable in the deploy hook of your application:

hooks:
  deploy: |
    set -x -e
    export PATH="$PATH:/app/.local/bin/"

Tips and best practices

Create a shell alias for quick access

If you use Option 1 frequently, add an alias to your shell configuration:

alias upsun-harlequin='upsun tunnel:open && harlequin -a postgres "$(upsun tunnel:info --property=database.0.url)"'

Use read-only credentials for safety

When exploring production data, consider creating a read-only PostgreSQL user to prevent accidental modifications. You can configure additional database endpoints in your services configuration.

Keyboard shortcuts

Here are the most useful Harlequin shortcuts:

Action	Shortcut
Execute query	`Ctrl+Enter`
Autocomplete	`Ctrl+Space`
New query tab	`Ctrl+N`
Close tab	`Ctrl+W`
Focus data catalog	`Ctrl+B`
Help / all shortcuts	`F1`
Quit	`Ctrl+Q`

Query history

Harlequin automatically saves your query history. Press F8 to browse previous queries and re-run them.

Conclusion

You now have two ways to use Harlequin with your Upsun PostgreSQL database:

Local installation with SSH tunnel: Best for individual developers who want quick, on-demand access
Installed on Upsun: Best for team environments or when you want tools available directly on the platform

Both approaches give you a powerful, visual way to explore and query your data without leaving the terminal. For more Harlequin features and configuration options, check out the official documentation. Ready to try it out? Create a free Upsun account and deploy your first PostgreSQL-powered application.

​Prerequisites

​Option 1: Run Harlequin locally with an SSH tunnel

​Install Harlequin with the PostgreSQL adapter

​Open an SSH tunnel to your Upsun services

​Connect Harlequin to the tunnel

​Explore your database

​Option 2: Install Harlequin on Upsun

​Add Harlequin to your build hook

​Deploy your changes

​SSH into your environment

​Launch Harlequin

​Tips and best practices

​Create a shell alias for quick access

​Use read-only credentials for safety

​Keyboard shortcuts

​Query history

​Conclusion