Flashboard requires SSL for local database connections. This ensures your data is encrypted end-to-end, even when traveling through the secure tunnel.

If you see an "SSL connection failed" error, follow this guide to enable SSL on your PostgreSQL server.

💡 Pro tip: paste this article into Claude Code and let it run the commands for you. Carefully review each command before running.

Check if SSL is already enabled

Before making changes, check if SSL is already enabled on your PostgreSQL server:

psql -c "SHOW ssl;"

If this returns on, SSL is already enabled. Skip to the Verify SSL is working section to confirm it's working correctly.

If it returns off or you get an error, continue with the steps below.

Find your PostgreSQL directories

Run these commands to find your PostgreSQL directories:

# Configuration file location
psql -c "SHOW config_file;"

# Data directory (where certificates go)
psql -c "SHOW data_directory;"

Save both paths — you'll need them throughout this guide.

Note: On some systems (like Ubuntu/Debian), the configuration files and data directory are in different locations. The data directory is where your SSL certificates must go.

Back up your PostgreSQL configuration

Back up your configuration files before making changes. The pg_hba.conf file is in the same directory as postgresql.conf:

# Navigate to the directory from SHOW config_file
cp postgresql.conf postgresql.conf.backup
cp pg_hba.conf pg_hba.conf.backup

Use sudo if needed (common on Linux).

Generate SSL certificates

PostgreSQL needs a certificate and private key to enable SSL. You can generate a self-signed certificate for local development.

Note: If you already have server.key and server.crt files in your data directory, SSL may already be configured. Skip to "Configure postgresql.conf" to verify, or back up your existing certificates before regenerating.

macOS / Linux

Run these commands in your PostgreSQL data directory (use the path from SHOW data_directory):

# Navigate to your data directory
cd /path/to/your/data/directory

# Generate a private key
openssl genrsa -out server.key 2048

# Set proper permissions (required by PostgreSQL)
chmod 600 server.key

# Generate a self-signed certificate (valid for 365 days)
openssl req -new -x509 -days 365 -key server.key -out server.crt -subj "/CN=localhost"

If PostgreSQL runs as a different user (common on Linux servers), change ownership:

sudo chown postgres:postgres server.key server.crt

On macOS with Homebrew or Postgres.app, PostgreSQL runs as your user, so no ownership change is needed.

SELinux (RHEL/Fedora/CentOS): If SELinux is enabled, restore the security context:

sudo restorecon -v server.key server.crt

Windows

Windows requires OpenSSL and has different file permission handling.

Step 1: Install OpenSSL

The easiest option is to install Git for Windows, which includes OpenSSL. Alternatively, install OpenSSL for Windows from slproweb.com/products/Win32OpenSSL.html.

Step 2: Generate certificates

Open Git Bash and navigate to your PostgreSQL data directory (use the path from SHOW data_directory):

# Navigate to your data directory
cd "/path/to/your/data/directory"

# Generate a private key
openssl genrsa -out server.key 2048

# Generate a self-signed certificate (valid for 365 days)
openssl req -new -x509 -days 365 -key server.key -out server.crt -subj "/CN=localhost"

Step 3: Set file permissions

PostgreSQL on Windows checks Windows ACLs and will refuse to start if the key file permissions are too open. Set proper permissions using one of these methods:

Option A: PowerShell (run as Administrator)

cd "C:\path\to\your\data\directory"
icacls server.key /inheritance:r
icacls server.key /grant:r "$($env:USERNAME):(F)"

Option B: File Explorer

1. Right-click server.key → Properties → Security tab → Advanced
2. Click "Disable inheritance" → "Remove all inherited permissions"
3. Click "Add" → "Select a principal" → Enter your Windows username → OK
4. Check "Full control" → OK → Apply

If PostgreSQL runs as a service under a different account (like NT AUTHORITY\NetworkService), grant that account access instead of your username.

Configure postgresql.conf

Open your postgresql.conf file and update these settings:

ssl = on
ssl_cert_file = 'server.crt'
ssl_key_file = 'server.key'

Save the file.

Configure pg_hba.conf

The pg_hba.conf file controls client authentication. You need to allow SSL connections from localhost.

Find the file in the same directory as postgresql.conf (use SHOW config_file to find it).

Important: Rules are processed top-to-bottom, and the first match wins. Add these lines near the top of the file, before any existing host rules for localhost:

# Allow SSL connections from localhost
hostssl all all 127.0.0.1/32 scram-sha-256
hostssl all all ::1/128 scram-sha-256

Match the authentication method to your existing configuration:

• scram-sha-256 — Modern default (PostgreSQL 14+)
• md5 — Legacy password hashing (older installations)
• trust — Passwordless connections (common for local development)

The key is using hostssl (which requires SSL) instead of host (which allows both SSL and non-SSL connections).

If you have existing host all all 127.0.0.1/32 lines, either comment them out or ensure your new hostssl lines appear before them.

Tip: If SSL connections fail after restarting, the most common cause is pg_hba.conf rule ordering. Run grep -n "host" pg_hba.conf to see all rules and their line numbers.

Restart PostgreSQL

After making these changes, restart PostgreSQL for them to take effect.

macOS (Homebrew)

# PostgreSQL 17 (adjust version number as needed)
brew services restart postgresql@17

macOS (Postgres.app)

In Postgres.app, click the server name, then click "Stop". Once stopped, click "Start" to restart with the new configuration.

Alternatively, use pg_ctl from the terminal:

# PostgreSQL 17 (adjust version number as needed)
/Applications/Postgres.app/Contents/Versions/latest/bin/pg_ctl restart -D ~/Library/Application\ Support/Postgres/var-17

Ubuntu/Debian

sudo systemctl restart postgresql

Windows

Restart the PostgreSQL service from the Services application, or run:

# PostgreSQL 17 (adjust version number as needed)
Restart-Service postgresql-x64-17

RHEL/Fedora/CentOS

# PostgreSQL 17 (adjust version number as needed)
sudo systemctl restart postgresql-17

Arch Linux

sudo systemctl restart postgresql

Verify SSL is working

Test that SSL is enabled by connecting with psql:

psql "postgres://username:password@localhost:5432/your_database?sslmode=require"

Read our PostgreSQL integration docs for help building your connection URL.

Windows (CMD or PowerShell): Use double quotes for the connection string. If you have issues, try escaping special characters or use Git Bash instead.

If the connection succeeds, SSL is working. You can also verify by running this query:

SHOW ssl;

It should return on. You're now ready to connect your local database to Flashboard.

Certificate renewal

The self-signed certificate expires after 365 days. When it expires, PostgreSQL will still start, but SSL connections may fail with certificate errors.

To renew, regenerate the certificate using the same commands from the "Generate SSL certificates" section above. You'll need to restart PostgreSQL after replacing the certificate.

Special environments

Docker

If you're running PostgreSQL in a Docker container, SSL configuration depends on your Docker image. Many official images have SSL disabled by default.

For the official postgres image, you'll need to mount SSL certificates and modify the PostgreSQL configuration. See the official postgres Docker image documentation for details.

Windows Subsystem for Linux (WSL)

If you're running PostgreSQL inside WSL, follow the Ubuntu/Debian instructions above. Your data directory is typically /var/lib/postgresql/VERSION/main/.

Make sure you're connecting to the PostgreSQL instance running inside WSL, not a separate Windows installation.

Troubleshooting

PostgreSQL won't start after changes

Check the PostgreSQL logs for errors:

macOS (Homebrew):

# PostgreSQL 17 (adjust version number as needed)

# Check service status
brew services info postgresql@17

# View logs
cat /opt/homebrew/var/log/postgresql@17.log  # Apple Silicon
cat /usr/local/var/log/postgresql@17.log     # Intel

macOS (Postgres.app):

Open Postgres.app, click the server name, then click "Server Logs" in the sidebar.

Ubuntu/Debian:

sudo journalctl -u postgresql --no-pager -n 50
# or (adjust version number as needed)
sudo tail -50 /var/log/postgresql/postgresql-17-main.log

Windows:

Check the Windows Event Viewer under "Windows Logs" → "Application", or look for logs in your PostgreSQL data directory.

RHEL/Fedora/CentOS:

# PostgreSQL 17 (adjust version number as needed)
sudo journalctl -u postgresql-17 --no-pager -n 50
# or
sudo tail -50 /var/lib/pgsql/17/data/log/postgresql-*.log

Arch Linux:

sudo journalctl -u postgresql --no-pager -n 50
# or
sudo tail -50 /var/lib/postgres/data/log/postgresql-*.log

Common errors

• "could not load private key file": Check file permissions. On macOS/Linux, run chmod 600 server.key and ensure ownership matches the PostgreSQL process user. On Windows, check that only your user (or the PostgreSQL service account) has access—see the Windows permissions section above.
• "SSL certificate file not found": Verify the certificate files are in your PostgreSQL data directory and the paths in postgresql.conf are correct.
• Syntax error in config file: Double-check your edits to postgresql.conf and pg_hba.conf. Restore from backup if needed.