feat(portal): add atexit handler for graceful shutdown

Register cleanup handler on first portal creation to ensure background
thread and event loop are properly stopped when the interpreter exits.
Prevents resource leaks and ensures pending async operations complete.

Author: cofin

sqlspec/utils/portal.py

@@ -5,6 +5,7 @@
 """
 
 import asyncio
+import atexit
 import functools
 import os
 import queue
@@ -257,12 +258,13 @@ def __init__(self) -> None:
         self._portal: Portal | None = None
         self._lock = threading.Lock()
         self._pid: int | None = None
+        self._atexit_registered: bool = False
 
     def get_or_create_portal(self) -> Portal:
         """Get or create the global portal instance.
 
         Lazily creates and starts the portal provider on first access.
-        Thread-safe via locking.
+        Thread-safe via locking. Registers an atexit handler for cleanup.
 
         Returns:
             Global portal instance.
@@ -278,10 +280,31 @@ def get_or_create_portal(self) -> Portal:
                     self._provider.start()
                     self._portal = Portal(self._provider)
                     self._pid = current_pid
+                    self._register_atexit()
                     logger.debug("Global portal provider created and started")
 
         return cast("Portal", self._portal)
 
+    def _register_atexit(self) -> None:
+        """Register atexit handler for graceful shutdown.
+
+        Only registers once per process to avoid duplicate cleanup.
+        """
+        if not self._atexit_registered:
+            atexit.register(self._atexit_cleanup)
+            self._atexit_registered = True
+            logger.debug("Portal atexit handler registered")
+
+    def _atexit_cleanup(self) -> None:
+        """Cleanup handler called at interpreter shutdown.
+
+        Gracefully stops the portal provider to ensure pending
+        async operations complete before the process exits.
+        """
+        if self._provider is not None and self._provider.is_running:
+            logger.debug("Portal atexit cleanup: stopping provider")
+            self.stop()
+
     @property
     def is_running(self) -> bool:
         """Check if global portal is running.

tests/unit/test_utils/test_portal.py

@@ -342,3 +342,42 @@ def get_portal() -> None:
     assert all(p is portals[0] for p in portals)
 
     manager.stop()
+
+
+def test_portal_manager_atexit_registration() -> None:
+    """PortalManager registers atexit handler on portal creation."""
+    manager = PortalManager()
+
+    assert not manager._atexit_registered
+
+    manager.get_or_create_portal()
+
+    assert manager._atexit_registered
+    assert manager.is_running
+
+    manager.stop()
+
+
+def test_portal_manager_atexit_cleanup() -> None:
+    """PortalManager._atexit_cleanup stops running provider."""
+    manager = PortalManager()
+    manager.get_or_create_portal()
+
+    assert manager.is_running
+
+    manager._atexit_cleanup()
+
+    assert not manager.is_running
+
+
+def test_portal_manager_atexit_cleanup_noop_when_stopped() -> None:
+    """PortalManager._atexit_cleanup is no-op when already stopped."""
+    manager = PortalManager()
+    manager.get_or_create_portal()
+    manager.stop()
+
+    assert not manager.is_running
+
+    manager._atexit_cleanup()
+
+    assert not manager.is_running