Documentation

Getting Started with Simpl Desktop

Learn how to download, install, and set up Simpl Desktop to browse your PostgreSQL databases.

Prerequisites

Before you begin, ensure you have:

  • A Mac computer (Apple Silicon or Intel)
  • A Simpl license key (from your account dashboard)
  • A PostgreSQL database (version 12 or later recommended)
  • A connection string with appropriate credentials

Step 1: Download Simpl Desktop

  1. Visit your account dashboard
  2. Click Download for Mac (Apple Silicon or Intel)
  3. Open the downloaded .dmg file
  4. Drag Simpl to your Applications folder

Step 2: Activate with Your License Key

  1. Open Simpl from your Applications folder
  2. When prompted, enter your license key
  3. You can find your license key in your account dashboard

Your license key links the desktop app to your account and enables all features.

Step 3: Add a Database Connection

Enter Your Connection String

Provide your PostgreSQL connection string in the standard format:

postgresql://username:password@hostname:port/database

Example connection strings:

ProviderFormat
Standardpostgresql://user:pass@localhost:5432/mydb
Supabasepostgresql://postgres.[project]:[password]@aws-0-[region].pooler.supabase.com:6543/postgres
Neonpostgresql://[user]:[password]@[endpoint].neon.tech/[database]
Railwaypostgresql://postgres:[password]@[host].railway.app:5432/railway

Test Your Connection

Click Test Connection to verify connectivity. This checks:

  • Network connectivity from your machine
  • Authentication credentials
  • Database accessibility

Save and Explore

Once the test passes, save your connection. Simpl will automatically:

  1. Introspect your database schema
  2. Discover all tables and their columns
  3. Detect relationships between tables
  4. Generate initial layouts for each table

Connection Security

Your credentials are stored securely on your local machine:

  • 100% local storage - Credentials never leave your device
  • AES-256-GCM encryption - Protected even on disk
  • Direct connections - Queries go straight from your computer to your database

No data passes through our servers. Learn more in our Security documentation.

Managing Connections

Viewing Connection Details

From the main screen, each database shows:

  • Database name and host
  • PostgreSQL version
  • Total number of tables
  • Estimated total rows
  • Last connected timestamp

Removing a Connection

To remove a database connection:

  1. Right-click on the connection
  2. Select Delete Connection
  3. Confirm the deletion

This removes the connection from Simpl but does not affect your actual database.

Troubleshooting

Connection Failed

If your connection test fails, check:

  1. Credentials - Verify username and password are correct
  2. Network - Ensure your machine can reach the database server
  3. Firewall - Check if your database allows connections from your IP
  4. SSL - Some providers require SSL; add ?sslmode=require to your connection string

Supabase Connection Issues

If you're connecting to Supabase, use the Connection Pooler URL:

  1. Go to your Supabase dashboard
  2. Navigate to Settings → Database → Connection string
  3. Select Connection Pooler (not "Direct connection")
  4. Choose Transaction mode
  5. Copy the pooler connection string

The pooler URL format:

postgresql://postgres.[project-ref]:[password]@aws-0-[region].pooler.supabase.com:6543/postgres

Schema Not Loading

If tables aren't appearing after connection:

  1. Verify the user has SELECT privileges on tables
  2. Check that tables exist in the public schema
  3. Try refreshing the schema manually

Slow Connection

For distant database servers:

  • Consider using a connection pooler (like PgBouncer)
  • Check your database's connection limits
  • Ensure adequate network bandwidth

Next Steps

Now that you're connected, learn how to: