Skip to main content
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:
  1. Run Harlequin locally and connect through an SSH tunnel
  2. 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

harlequin-tunnel 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:
ActionShortcut
Execute queryCtrl+Enter
AutocompleteCtrl+Space
New query tabCtrl+N
Close tabCtrl+W
Focus data catalogCtrl+B
Help / all shortcutsF1
QuitCtrl+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:
  1. Local installation with SSH tunnel: Best for individual developers who want quick, on-demand access
  2. 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.
Last modified on April 14, 2026