Resilient Connections in QoreDB: Health Checks and SSH Reconnection

A database connection can drop for dozens of reasons: a network timeout, an SSH tunnel going down, a server restart, a failover switch. A desktop database client that ignores this problem leaves the user facing cryptic errors at the very moment they run a query.

QoreDB takes a proactive approach: a health monitor runs in the background and watches every active session, every 30 seconds. When a connection drops, the client detects it, tries to restore it, and informs the interface in real time.

The SessionManager: a single source of truth

All active sessions are managed by the SessionManager, a Rust component in the qore-drivers crate. It is what stores the state of each open connection: the driver in use, the configuration, the optional SSH tunnel, the proxy tunnel, and the current health status.

Each session is identified by a UUID and maintains a consecutive-failures counter (consecutive_failures). This counter only resets on a successful ping.

Three health states are possible: healthy, unhealthy, and reconnecting. The last one indicates that an SSH tunnel reconnection attempt is in progress.

The health check cycle: tunnel first, ping next

The run_health_check method is called by a Tokio task every 30 seconds. For each active session, it proceeds in two ordered steps.

The first is a TCP check of the SSH tunnel, if there is one. QoreDB attempts a TCP connection on the tunnel's local port and verifies that it succeeds. If it fails, the tunnel is considered dead. This check is deliberately lightweight: no SSH protocol handshake, just a test of the port's reachability.

If the tunnel is active (or absent), QoreDB sends a ping to the driver. The ping timeout is set to 5 seconds. Each driver implements the ping method according to its own semantics: a SELECT 1 query for PostgreSQL, a native ping for MongoDB, and so on. On failure, the consecutive-failures counter is incremented.

Automatic SSH tunnel reconnection

When the tunnel is dead and the consecutive-failures counter reaches the threshold of 2, QoreDB attempts a reconnection. The session first moves to the reconnecting state, which is immediately notified to the frontend. Then the tunnel is reopened using the same SSH configuration stored in the session.

If the reconnection succeeds, the old tunnel is closed on a best-effort basis, the new one takes its place, the counter is reset to 0, and the session goes back to healthy. If the reconnection fails, the session stays unhealthy and the monitor will try again on the next cycle.

This mechanism covers the most common use case: an SSH tunnel dropped after a long period of inactivity, or following a temporary network disconnection.

What the interface receives

The backend emits Tauri events (connection_health) on every status change. The React SessionProvider listens for these events and updates the health status displayed in the status bar.

When a connection turns unhealthy, a toast notification appears. When it returns to healthy - after an automatic tunnel reconnection, for example - a success notification confirms the restoration. The user has nothing to do.

The check_connection_health command is also exposed as a Tauri command, which allows a manual, on-demand ping from the interface.

Conclusion

Connection resilience in QoreDB rests on a lightweight background monitor, a three-level health state, and automatic SSH reconnection logic. The goal is to prevent the user from discovering a dead connection at the moment they run a query. The desktop context makes this mechanism simpler to implement than a shared backend: there is no contention between users, no distributed coordination, just a local process watching its own connections.