Welcome to HarborDB! This guide will walk you through creating your first PostgreSQL connection. Whether you're connecting to a local database on your Mac or a remote server, HarborDB makes the process simple and secure.

Prerequisites

Before you begin, ensure you have:

HarborDB installed (see Installation Guide)
PostgreSQL server running and accessible
Connection details ready:
- Hostname or IP address
- Port number (default: 5432)
- Database name
- Username and password
- Optional: SSL certificate if required

Step 1: Launch HarborDB and Access Connections

Open HarborDB from your Applications folder or Launchpad
Locate the Connections sidebar on the left side of the window
Click the "+" button or go to File → Add Connection

Step 2: Fill in Connection Details

The connection dialog has several fields to complete:

Basic Information

Name: A friendly name for this connection (e.g., "Local Development", "Production Server")
Host: The PostgreSQL server address
- Local database: localhost or 127.0.0.1
- Remote server: IP address or hostname (e.g., db.example.com)
Port: PostgreSQL port (default: 5432)
Database: The specific database to connect to
Username: Your PostgreSQL username
Password: Your PostgreSQL password

Advanced Options (Optional)

Schema: Preferred schema (defaults to public)
SSL Mode: Choose based on your server configuration:
- prefer: Use SSL if available
- require: Require SSL connection
- verify-full: Require SSL with certificate validation
Timeout: Connection timeout in seconds
Application Name: Custom identifier for this connection

Step 3: Test Your Connection

Before saving, always test your connection:

Click "Test Connection" in the dialog
Wait for confirmation - You should see "Connection successful"
Review any warnings about SSL or other settings

Common Test Results

✅ Success: You're ready to save and connect
❌ Failure: Check error message for clues:
- "Connection refused": Server not running or firewall blocking
- "Authentication failed": Incorrect username/password
- "Database does not exist": Database name incorrect

Step 4: Save and Secure Your Connection

Password Storage Options

HarborDB offers secure password storage:

Save in Keychain (Recommended): Password encrypted in macOS Keychain
Save in connection: Password stored with connection settings (less secure)
Ask each time: Prompt for password on every connection

Choosing the Right Option

| Storage Method | Security | Convenience | Best For | | --------------- | ---------- | ----------- | ------------------------------- | | macOS Keychain | 🔒 High | ⚡ High | Daily use, trusted computers | | Connection file | 🔒 Medium | ⚡ High | Quick setup, testing | | Ask each time | 🔒 Highest | ⚡ Low | Shared computers, high security |

Saving Your Connection

Choose password storage method
Click "Save" to store the connection
Find your connection in the Connections sidebar
Double-click to connect

Step 5: Connect and Explore

Once connected, you can:

Navigate Your Database

Expand the connection to see databases
Browse schemas and tables in the sidebar
Right-click tables for quick actions:
- View table structure
- Preview first 100 rows
- Generate SELECT query

Quick Start Actions

Open Query Editor: Click the SQL icon or press ⌘ + N
Run a test query:
```
SELECT version();
```
Explore interface: Familiarize yourself with tabs, panels, and tools

Connection Management

Organizing Multiple Connections

As you add more connections, keep them organized:

Favorites: Star frequently used connections for quick access
Groups: Organize by project, environment, or team
Color coding: Use tags or naming conventions

Editing Existing Connections

Right-click connection in sidebar
Select "Edit Connection"
Update any fields as needed
Test and save changes

Duplicating Connections

Save time by duplicating similar connections:

Right-click source connection
Select "Duplicate"
Modify only the changed fields
Save as new connection

Security Best Practices

Password Security

Never share Keychain passwords
Use strong passwords for PostgreSQL users
Rotate passwords periodically
Avoid reusing passwords across different servers

Connection Security

Use SSL for remote connections
Limit database permissions to necessary operations
Use read-only connections for reporting
Regularly audit connection logs

Network Security

Firewall configuration: Allow only trusted IPs
VPN access for remote databases
SSH tunneling for additional security layers

Common Connection Scenarios

Local PostgreSQL (Installed via Homebrew)

Name: Local PostgreSQL
Host: localhost
Port: 5432
Database: postgres
Username: your_username
Password: [Keychain]

Docker PostgreSQL Container

Name: Docker Dev DB
Host: localhost
Port: 5432  # Or custom port if mapped differently
Database: app_database
Username: postgres
Password: postgres_password

Amazon RDS PostgreSQL

Name: AWS Production
Host: your-db-instance.region.rds.amazonaws.com
Port: 5432
Database: production_db
Username: app_user
SSL Mode: verify-full

Google Cloud SQL

Name: GCP Cloud SQL
Host: /cloudsql/project:region:instance
Port: 5432
Database: cloud_db
SSL Mode: require

Troubleshooting Connection Issues

"Cannot Connect to Server"

Verify PostgreSQL is running:

# In Terminal
pg_isready -h localhost -p 5432

Check firewall settings:
- macOS Firewall (System Preferences → Security & Privacy)
- Network firewall rules

Test network connectivity:

# In Terminal
ping your-server-address
telnet your-server-address 5432

"Password Authentication Failed"

Check PostgreSQL authentication method:
- View pg_hba.conf file
- Ensure md5 or scram-sha-256 authentication

Reset password if needed:

ALTER USER username WITH PASSWORD 'new_password';

Verify user has database access:

-- Connect as superuser
\du  -- List users
\l   -- List databases

SSL/TLS Connection Errors

Check SSL requirements:
- Server may require specific SSL mode
- Certificate may need to be imported
Adjust SSL mode in connection settings
Import certificate if using verify-full mode

Performance Tips

Connection Pooling

Keep connections open for frequent use
Close unused connections to free resources
Use connection pooling for applications

Network Optimization

Local connections: Use localhost for best performance
Remote connections: Ensure sufficient bandwidth
Compression: Enable if dealing with large result sets

Next Steps

Now that you're connected:

Explore Query Basics - Learn to write and execute SQL queries
Database Navigation - Explore schemas, tables, and relationships
Exporting Data - Save results to CSV or JSON

Getting Help

If you're still having trouble:

Check our Support Guide for more troubleshooting
Visit the FAQ for common questions
Contact Support for personalized assistance

Creating Your First Connection