Make SSH packages optional (#19)

* Make SSH packages optional

* Update gh worker and readme

---------

Co-authored-by: Peter Adams <18162810+Maxteabag@users.noreply.github.com>

Author: Maxteabag

.github/workflows/ci.yml

@@ -414,7 +414,7 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install -e ".[test]"
+          pip install -e ".[test,ssh]"
           pip install psycopg2-binary
 
       - name: Create Docker network

README.md

@@ -196,6 +196,18 @@ Most of the time you can just run `sqlit` and connect. If a Python driver is mis
 
 **Note:** SQL Server also requires the platform-specific ODBC driver. On your first connection attempt, `sqlit` can help you install it if it's missing.
 
+### SSH Tunnel Support
+
+SSH tunnel functionality requires additional dependencies. Install with the `ssh` extra:
+
+| Method | Command |
+| :--- | :--- |
+| pipx | `pipx install 'sqlit-tui[ssh]'` |
+| uv | `uv tool install 'sqlit-tui[ssh]'` |
+| pip | `pip install 'sqlit-tui[ssh]'` |
+
+If you try to create an SSH connection without these dependencies, sqlit will detect this and show you the exact command to install them for your environment.
+
 ## License
 
 MIT

mock-ssh-missing.json

@@ -0,0 +1,13 @@
+{
+  "_note": "Run: sqlit --settings mock-ssh-missing.json",
+  "mock": {
+    "enabled": true,
+    "profile": "empty",
+    "use_default_adapters": true,
+    "drivers": {
+      "missing": ["ssh"],
+      "install_result": "real",
+      "pipx": "auto"
+    }
+  }
+}

pyproject.toml

@@ -29,8 +29,6 @@ classifiers = [
 dependencies = [
     "textual[syntax]>=6.10.0",
     "pyperclip>=1.8.2",
-    "sshtunnel>=0.4.0",
-    "paramiko>=2.0.0,<4.0.0",  # sshtunnel requires paramiko<4.0.0 (DSSKey removed in 4.0)
     "keyring>=24.0.0",
 ]
 
@@ -44,6 +42,8 @@ all = [
     "duckdb>=0.9.0",
     "requests>=2.0.0",
     "libsql-client>=0.1.0",
+    "sshtunnel>=0.4.0",
+    "paramiko>=2.0.0,<4.0.0",
 ]
 postgres = ["psycopg2-binary>=2.9.0"]
 cockroachdb = ["psycopg2-binary>=2.9.0"]
@@ -54,6 +54,10 @@ oracle = ["oracledb>=2.0.0"]
 duckdb = ["duckdb>=0.9.0"]
 d1 = ["requests>=2.0.0"]
 turso = ["libsql-client>=0.1.0"]
+ssh = [
+    "sshtunnel>=0.4.0",
+    "paramiko>=2.0.0,<4.0.0",
+]
 test = [
     "pytest>=7.0",
     "pytest-timeout>=2.0",

sqlit/db/__init__.py

@@ -15,7 +15,7 @@
     is_file_based,
     supports_ssh,
 )
-from .tunnel import create_ssh_tunnel
+from .tunnel import create_ssh_tunnel, ensure_ssh_tunnel_available
 
 __all__ = [
     # Base
@@ -50,6 +50,7 @@
     "TursoAdapter",
     # Tunnel
     "create_ssh_tunnel",
+    "ensure_ssh_tunnel_available",
 ]
 
 if TYPE_CHECKING:

sqlit/db/tunnel.py

@@ -10,6 +10,23 @@
     from ..config import ConnectionConfig
 
 
+def ensure_ssh_tunnel_available() -> None:
+    """Ensure SSH tunnel dependencies are installed."""
+    forced_missing = os.environ.get("SQLIT_MOCK_MISSING_DRIVERS", "").strip()
+    if forced_missing:
+        forced = {s.strip() for s in forced_missing.split(",") if s.strip()}
+        if "ssh" in forced:
+            from .exceptions import MissingDriverError
+
+            raise MissingDriverError("SSH tunnel", "ssh", "sshtunnel")
+    try:
+        import sshtunnel  # noqa: F401
+    except Exception as e:
+        from .exceptions import MissingDriverError
+
+        raise MissingDriverError("SSH tunnel", "ssh", "sshtunnel") from e
+
+
 def create_ssh_tunnel(config: ConnectionConfig) -> tuple[Any, str, int]:
     """Create an SSH tunnel for the connection if SSH is enabled.
 
@@ -21,6 +38,8 @@ def create_ssh_tunnel(config: ConnectionConfig) -> tuple[Any, str, int]:
         port = int(config.port) if config.port else 0
         return None, config.server, port
 
+    ensure_ssh_tunnel_available()
+
     from sshtunnel import SSHTunnelForwarder
 
     # Parse remote database host and port

sqlit/ui/screens/connection.py

@@ -277,6 +277,8 @@ def __init__(
         self.validation_state: ValidationState = ValidationState()
         self._saved_dialog_subtitle: str | None = None
         self._missing_driver_error: Any = None  # Stores MissingDriverError if driver is missing
+        self._missing_ssh_driver_error: Any = None  # Stores MissingDriverError for SSH tunnel
+        self._install_error: Any = None
         self._install_in_progress: bool = False
         self._install_spinner_timer: Timer | None = None
         self._install_spinner_index: int = 0
@@ -506,6 +508,36 @@ def _check_driver_availability(self, db_type: DatabaseType) -> None:
 
         self._update_driver_status_ui()
 
+    def _check_ssh_driver_availability(self) -> None:
+        from ...db import ensure_ssh_tunnel_available
+
+        self._missing_ssh_driver_error = None
+        if not supports_ssh(self._current_db_type.value):
+            self._update_driver_status_ui()
+            return
+        try:
+            ensure_ssh_tunnel_available()
+        except MissingDriverError as e:
+            self._missing_ssh_driver_error = e
+
+        self._update_driver_status_ui()
+
+    def _get_active_tab(self) -> str:
+        try:
+            tabs = self.query_one("#connection-tabs", TabbedContent)
+            return tabs.active
+        except Exception:
+            return "tab-general"
+
+    def _format_install_hint(self, strategy: Any, package_name: str) -> str:
+        if strategy.kind == "pip":
+            return f"pip install {package_name}"
+        if strategy.kind == "pip-user":
+            return f"pip install --user {package_name}"
+        if strategy.kind == "pipx":
+            return f"pipx inject sqlit-tui {package_name}"
+        return strategy.manual_instructions.split("\n")[0].strip()
+
     def _update_driver_status_ui(self) -> None:
         try:
             test_status = self.query_one("#test-status", Static)
@@ -518,8 +550,8 @@ def _update_driver_status_ui(self) -> None:
         except Exception:
             pass
 
-        if self._install_in_progress and self._missing_driver_error:
-            error = self._missing_driver_error
+        if self._install_in_progress and self._install_error:
+            error = self._install_error
             spinner = self._INSTALL_SPINNER_FRAMES[self._install_spinner_index % len(self._INSTALL_SPINNER_FRAMES)]
             test_status.update(
                 f"[yellow]⚠ Missing driver:[/] {error.package_name}\n"
@@ -528,11 +560,16 @@ def _update_driver_status_ui(self) -> None:
             dialog.border_subtitle = "[bold]Installing…[/]  Cancel <esc>"
             return
 
-        if self._missing_driver_error:
+        active_tab = self._get_active_tab()
+        if active_tab == "tab-ssh":
+            error = self._missing_ssh_driver_error
+        else:
             error = self._missing_driver_error
+
+        if error:
             strategy = detect_strategy(extra_name=error.extra_name, package_name=error.package_name)
             if strategy.can_auto_install:
-                install_cmd = strategy.manual_instructions.split("\n")[0].strip()
+                install_cmd = self._format_install_hint(strategy, error.package_name)
                 test_status.update(
                     f"[yellow]⚠ Missing driver:[/] {error.package_name}\n"
                     f"[dim]Install with:[/] {escape(install_cmd)}"
@@ -645,6 +682,7 @@ def _start_missing_driver_install(self, error: Any) -> None:
             return
 
         self._install_in_progress = True
+        self._install_error = error
         self._install_spinner_index = 0
         self._post_install_message = None
         self._update_driver_status_ui()
@@ -672,9 +710,13 @@ def _on_missing_driver_install_complete(self, success: bool, output: str, error:
 
         self._stop_install_spinner()
         self._install_in_progress = False
+        self._install_error = None
 
         if success:
-            self._check_driver_availability(self._current_db_type)
+            if isinstance(error, MissingDriverError) and error.extra_name == "ssh":
+                self._check_ssh_driver_availability()
+            else:
+                self._check_driver_availability(self._current_db_type)
             self._post_install_message = "Successfully installed driver"
             self._update_driver_status_ui()
 
@@ -828,6 +870,8 @@ def _deferred_driver_check(self) -> None:
             t0 = time.perf_counter()
 
         self._check_driver_availability(self._current_db_type)
+        if self._get_active_tab() == "tab-ssh":
+            self._check_ssh_driver_availability()
 
         if debug:
             print(f"[DEBUG] _check_driver_availability: {(time.perf_counter() - t0)*1000:.1f}ms", file=sys.stderr)
@@ -882,6 +926,12 @@ def _apply_prefill_values(self) -> None:
             except Exception:
                 pass
 
+    def on_tabbed_content_tab_activated(self, event: TabbedContent.TabActivated) -> None:
+        if self._get_active_tab() == "tab-ssh":
+            self._check_ssh_driver_availability()
+        else:
+            self._update_driver_status_ui()
+
     def on_descendant_focus(self, event: Any) -> None:
         focused = self.focused
         if focused is None:
@@ -1235,9 +1285,14 @@ def action_open_odbc_setup(self) -> None:
     def action_install_driver(self) -> None:
         if self._install_in_progress:
             return
+        active_tab = self._get_active_tab()
+        if active_tab == "tab-ssh" and self._missing_ssh_driver_error:
+            self._prompt_install_missing_driver(self._missing_ssh_driver_error)
+            return
         if self._missing_driver_error:
             self._prompt_install_missing_driver(self._missing_driver_error)
-        elif self._current_db_type.value == "mssql":
+            return
+        if self._current_db_type.value == "mssql":
             self._open_odbc_driver_setup()
 
     def _clear_field_error(self, name: str) -> None: