Documentation

Database Connections

QueryGlow connects to six database engines: directly, over SSL/TLS, or through a built-in SSH tunnel. Passwords, SSH keys and passphrases are encrypted at rest with AES-256-GCM.

Supported Databases

PostgreSQL :5432
MySQL :3306
MariaDB :3306
SQLite file
CockroachDB :26257
TimescaleDB :5432

Add Connections Without Typing Hosts and Ports

The New Connection dialog ("Paste a URL, pick a local server, or fill in the details") has three shortcuts, and an HTTP API covers scripted setup.

Paste a connection URL

Under Quick start, paste into Connection URL and the fields below fill themselves: type, host, port, database, username and password. Accepted schemes: postgres://, postgresql://, mysql://, mariadb:// and cockroachdb://. With sslmode=require, verify-ca or verify-full SSL is switched on; the last two also switch on Verify server certificate. The URL itself is not stored.

There is no scheme for SQLite or TimescaleDB: paste a TimescaleDB URL as postgres:// and switch the type. JDBC URLs and key=value strings are not parsed.

Find local servers

The radar icon in the sidebar footer, and the button in the dialog, check the standard ports on the machine QueryGlow runs on: 5432 and 5433 (PostgreSQL or TimescaleDB), 3306 and 3307 (MySQL or MariaDB), 26257 (CockroachDB). One TCP connect per port, only when you click. Nothing leaves the machine.

A port cannot tell PostgreSQL from TimescaleDB, so each server found offers one button per product, for example Use as PostgreSQL and Use as TimescaleDB. A server on another port or another machine is not found this way.

Find databases on this server

Enter host, port, username and password, then click Find databases on this server. QueryGlow logs in, lists the databases that login can open, and you tick the ones you want. Add N connections adds them in one atomic write, all or nothing, each named after its database. When a name is already taken, the dialog proposes <database> (<host>:<port>) and shows the final names first. Databases you already have are marked already added.

For PostgreSQL, TimescaleDB, CockroachDB, MySQL and MariaDB, when you create a connection. It needs a working login; it does not discover servers or credentials.

Let a coding agent add them

POST /api/connections adds one connection, POST /api/connections/bulk adds up to 200 databases of one server per request. Both sit behind the same Basic Auth login you use in the browser.

A database that already exists as a connection is skipped and listed under skipped. A connection name that is already taken rejects the whole batch with 409, and nothing is written.

curl -u user:pass -X POST https://<your-host>/api/connections/bulk \
  -H 'Content-Type: application/json' \
  -d '{"type":"postgresql","host":"127.0.0.1","port":5432,"username":"app","password":"secret","environment":"development","databases":["shop","analytics"]}'
QueryGlow New Connection dialog with the Connection URL field under Quick start, the Find local servers button and the connection form
New Connection with the Connection URL field.
QueryGlow Find Local Servers step listing database servers found on this machine, each with Use as buttons
Find Local Servers after a scan.

Which Method Should I Use?

Your SetupConnection MethodSSL?
Database on same server as QueryGlowlocalhostNo
Your own VPS (Hetzner, DigitalOcean, etc.)SSH TunnelNo (tunnel encrypts)
Cloud database (Supabase, RDS, Neon, etc.)Direct connectionYes (required)

Scenario 1: Database on Same Server

QueryGlow and your database are on the same machine. Find local servers fills in type, host and port for you.

Connection Settings

Host: localhost
Port: 5432 (or 3306 for MySQL)
SSL: No
SSH Tunnel: Off

QueryGlow uses network_mode: host in production, so it can access localhost services directly.

Scenario 2: Your Own VPS (SSH Tunnel)Recommended

Your database is on a remote server you control, and its port is not open to the internet. The SSH tunnel lets QueryGlow reach it through the SSH access you already have.

Why SSH Tunnel?

A VPS firewall that keeps the database closed looks like this:

22/tcp   ALLOW  # SSH, how you manage the server
80/tcp   ALLOW  # HTTP
443/tcp  ALLOW  # HTTPS
# Port 5432 is not listed, so it is blocked

Through the tunnel QueryGlow connects as if it were on your server, so the database host is localhost.

How to Configure

  1. Open the New Connection dialog.
  2. Under SSH Tunnel (Bastion), tick Connect via SSH Tunnel.
  3. Enter your SSH details:
    • SSH Host: your server's public IP (e.g. 203.0.113.10)
    • SSH Port: 22 (default)
    • SSH Username: your server user (e.g. ubuntu or deploy)
    • SSH Private Key (PEM/OpenSSH): the full private key, including the BEGIN and END lines. If the key is encrypted, enter its passphrase in SSH Passphrase (Optional).
  4. Configure the database connection:

    Host: localhost or 127.0.0.1

    Port: 5432

    SSL: No (SSH encrypts the connection)

SSH tunnels are not available for SQLite. With a tunnel on, the SSL option is disabled because the tunnel already encrypts.

The SSH host key is pinned (since 1.3.0)

The first connection to an SSH server records the fingerprint of its host key (SHA256:..., the form ssh-keygen -lf prints) in data/ssh-known-hosts.json. Every later connection must present the same key; otherwise the tunnel is refused with both fingerprints in the error. If you reinstalled the server, remove its pinned entry.

Tip: a dedicated key for QueryGlow. A separate key keeps your personal key out of the app, and you can revoke it on its own.

# On your computer: a key just for QueryGlow (a passphrase is optional)
ssh-keygen -t ed25519 -f ~/.ssh/queryglow_key -C "queryglow"

# Authorize it on the database server
ssh-copy-id -i ~/.ssh/queryglow_key.pub user@your-server-ip

# Show the private key and paste it into QueryGlow
cat ~/.ssh/queryglow_key

Scenario 3: Cloud Database (Direct + SSL)

Managed databases such as Supabase, AWS RDS, Google Cloud SQL, Neon or PlanetScale. You have no SSH access; the provider manages the server.

Connection Settings

Host: db.xxx.supabase.co
Port: 5432
SSL: Yes
SSH Tunnel: Off

Copy the connection string from your provider's dashboard and paste it into Connection URL; the form fills itself.

Verify server certificate (since 1.3.0)

With Enable SSL/TLS connection ticked, the dialog offers Verify server certificate. It is off for a new connection: the connection is encrypted, but the server is not authenticated. Turn it on when your provider's certificate comes from a publicly trusted authority.

  • Leave it off for Amazon RDS and Google Cloud SQL: their certificates come from the provider's own authority, and a custom CA cannot be supplied.
  • A pasted URL with sslmode=verify-ca or verify-full turns it on.
  • Connections saved before 1.3.0 keep their old behavior: MySQL and MariaDB verified, the PostgreSQL family did not. Edit such a connection to change it.

Many Connections

  • Search: the Search connections... box above the list matches name, engine, database, host and port. Escape clears it.
  • Sort: the clock button (Sort by recently used) puts the connection you opened last at the top; click again for name order. The choice is remembered in your browser.
  • Group by host: the layers button puts every connection on the same host and port under one heading. SQLite files get their own group.
  • Rows: each row shows the database (or SQLite file name), host and port and the engine under the name, plus the environment badge. Drag the sidebar's right edge to any width between 240 and 480 pixels.
  • Export and import: Export Connections downloads a JSON file without passwords, SSH keys or passphrases. Import Connections skips names that already exist; enter the secrets again after an import.

Environment Badges

Every connection has an Environment: Development, Staging or Production. It shows as a colored badge in the sidebar, the header breadcrumb and the Agent Access dialog (dev, stg and prod when the sidebar is narrow).

developmentGreen: local databases and test containers
stagingAmber: data that may matter
productionRed: the Query Editor asks before writes, row deletes need a typed DELETE

What changes on production, and what Safe Mode blocks on every connection: Environments.

SQLite Configuration

Security: Path Restriction

SQLite database paths are restricted to the /app/data directory inside the container. This prevents path traversal. In Docker that directory is the named volume queryglow-data, not a folder on your server.

How to Use SQLite

  1. Copy your SQLite file into the container on the server QueryGlow runs on:
    # Copy the file into the QueryGlow data volume
docker cp /path/to/your.db queryglow:/app/data/your.db

# docker cp keeps the owner from your server (usually root);
# give the file to the user QueryGlow runs as, so it can write to it
docker exec -u root queryglow chown -R nextjs:nodejs /app/data
  2. In QueryGlow, connect using the container path:
    /app/data/your.db
  3. To create a new database, enter a path that does not exist yet and click Test Connection. QueryGlow creates it.

Timeouts and CockroachDB

QueryGlow waits at most 5 seconds for a database server to accept the connection, and 15 seconds for an SSH handshake. If a CockroachDB (or MySQL) connection times out, change localhost to 127.0.0.1. This avoids an IPv6/IPv4 mismatch.

Credential Security

  • Encrypted at rest: passwords, SSH keys and passphrases (and AI keys entered in the app) are encrypted with AES-256-GCM before storage.
  • Unique per installation: the key is derived from your SESSION_SECRET (scrypt).
  • Tampering detected: GCM mode detects if stored credentials have been modified.
Next: Browse your tables in the Data Browser →Query Editor →