Merge pull request #180 from Maxteabag/xdg-config-dir

Maxteabag · web-flow · commit b3caa5d2e3b3 · 2026-04-18T20:15:39.000+02:00
Default to XDG config dir with migration from ~/.sqlit
diff --git a/README.md b/README.md
@@ -233,13 +233,15 @@ Autocomplete triggers automatically in INSERT mode. Use `Tab` to accept.
 
 ## Configuration
 
-Connections and settings are stored in `~/.sqlit/`.
+Connections and settings are stored in `$XDG_CONFIG_HOME/sqlit/` (default: `~/.config/sqlit/`). Override the location by setting `SQLIT_CONFIG_DIR`.
+
+If an older install left files in `~/.sqlit/`, they are moved to the new location automatically on first run.
 
 ## FAQ
 
 ### How are sensitive credentials stored?
 
-Connection details are stored in `~/.sqlit/connections.json`, but passwords are stored in your OS keyring when available (macOS Keychain, Windows Credential Locker, Linux Secret Service).
+Connection details are stored in `connections.json` inside the config directory, but passwords are stored in your OS keyring when available (macOS Keychain, Windows Credential Locker, Linux Secret Service).
 
 ### How does sqlit compare to Harlequin, Lazysql, etc.?
 
diff --git a/sqlit/cli.py b/sqlit/cli.py
@@ -372,7 +372,7 @@ def main() -> int:
     parser.add_argument(
         "--settings",
         metavar="PATH",
-        help="Path to settings JSON file (overrides ~/.sqlit/settings.json)",
+        help="Path to settings JSON file (overrides the one in the sqlit config directory)",
     )
     parser.add_argument(
         "--theme",
diff --git a/sqlit/domains/connections/cli/commands.py b/sqlit/domains/connections/cli/commands.py
@@ -63,7 +63,7 @@ def _maybe_prompt_plaintext_credentials(services: AppServices) -> bool:
     if not sys.stdin.isatty():
         return False
 
-    answer = input("Keyring isn't available. Save passwords as plaintext in ~/.sqlit/? [y/N]: ").strip().lower()
+    answer = input("Keyring isn't available. Save passwords as plaintext in the sqlit config directory? [y/N]: ").strip().lower()
     allow = answer in {"y", "yes"}
     settings[ALLOW_PLAINTEXT_CREDENTIALS_SETTING] = allow
     services.settings_store.save_all(settings)
diff --git a/sqlit/domains/connections/discovery/cloud/aws/cache.py b/sqlit/domains/connections/discovery/cloud/aws/cache.py
@@ -3,18 +3,18 @@
 from __future__ import annotations
 
 import json
-import os
 import time
 from dataclasses import dataclass, field
-from pathlib import Path
 from typing import TYPE_CHECKING
 
+from sqlit.shared.core.store import CONFIG_DIR
+
 if TYPE_CHECKING:
     from .provider import RegionResources
 
 # Cache configuration
 AWS_CACHE_TTL_SECONDS = 300  # 5 minutes
-AWS_CACHE_FILE = Path(os.path.expanduser("~/.config/sqlit/aws_cache.json"))
+AWS_CACHE_FILE = CONFIG_DIR / "aws_cache.json"
 
 
 @dataclass
diff --git a/sqlit/domains/connections/discovery/cloud/azure/cache.py b/sqlit/domains/connections/discovery/cloud/azure/cache.py
@@ -3,16 +3,16 @@
 from __future__ import annotations
 
 import json
-import os
 import time
 from dataclasses import dataclass
-from pathlib import Path
+
+from sqlit.shared.core.store import CONFIG_DIR
 
 from .models import AzureSqlServer, AzureSubscription
 
 # Cache configuration
 AZURE_CACHE_TTL_SECONDS = 300  # 5 minutes
-AZURE_CACHE_FILE = Path(os.path.expanduser("~/.config/sqlit/azure_cache.json"))
+AZURE_CACHE_FILE = CONFIG_DIR / "azure_cache.json"
 
 
 @dataclass
diff --git a/sqlit/domains/connections/discovery/cloud/gcp/cache.py b/sqlit/domains/connections/discovery/cloud/gcp/cache.py
@@ -3,18 +3,18 @@
 from __future__ import annotations
 
 import json
-import os
 import time
 from dataclasses import dataclass, field
-from pathlib import Path
 from typing import TYPE_CHECKING
 
+from sqlit.shared.core.store import CONFIG_DIR
+
 if TYPE_CHECKING:
     from .provider import GCPCloudSQLInstance
 
 # Cache configuration
 GCP_CACHE_TTL_SECONDS = 300  # 5 minutes
-GCP_CACHE_FILE = Path(os.path.expanduser("~/.config/sqlit/gcp_cache.json"))
+GCP_CACHE_FILE = CONFIG_DIR / "gcp_cache.json"
 
 
 @dataclass
diff --git a/sqlit/domains/connections/store/connections.py b/sqlit/domains/connections/store/connections.py
@@ -15,7 +15,7 @@
 class ConnectionStore(JSONFileStore):
     """Store for managing saved database connections.
 
-    Connections are stored as a JSON object (versioned) in ~/.sqlit/connections.json.
+    Connections are stored as connections.json in the sqlit config directory (versioned).
     Passwords are stored separately in the OS keyring via CredentialsService.
     """
 
diff --git a/sqlit/domains/connections/ui/mixins/connection.py b/sqlit/domains/connections/ui/mixins/connection.py
@@ -597,7 +597,7 @@ def on_confirm(confirmed: bool | None) -> None:
                         self.services.credentials_service = build_credentials_service(self.services.settings_store)
                         self.services.connection_store.set_credentials_service(self.services.credentials_service)
                         do_save(config, original_name)
-                        self.notify("Saved passwords as plaintext in ~/.sqlit/ (0600)", severity="warning")
+                        self.notify("Saved passwords as plaintext in the sqlit config directory (0600)", severity="warning")
                         return
 
                     settings2[ALLOW_PLAINTEXT_CREDENTIALS_SETTING] = False
@@ -612,7 +612,7 @@ def on_confirm(confirmed: bool | None) -> None:
                 self.push_screen(
                     ConfirmScreen(
                         "Keyring isn't available",
-                        "Save passwords as plaintext in ~/.sqlit/ (protected directory)?",
+                        "Save passwords as plaintext in the sqlit config directory (protected directory)?",
                         yes_label="Yes",
                         no_label="No",
                     ),
diff --git a/sqlit/domains/query/store/history.py b/sqlit/domains/query/store/history.py
@@ -44,7 +44,7 @@ def from_dict(cls, data: dict) -> QueryHistoryEntry:
 class HistoryStore(JSONFileStore):
     """Store for managing query history.
 
-    History is stored as a JSON array in ~/.sqlit/query_history.json
+    History is stored as query_history.json in the sqlit config directory.
     Each entry includes query text, timestamp, and connection name.
     """
 
diff --git a/sqlit/domains/query/store/starred.py b/sqlit/domains/query/store/starred.py
@@ -8,7 +8,7 @@
 class StarredStore(JSONFileStore):
     """Store for managing starred queries.
 
-    Starred queries are stored as a JSON object in ~/.sqlit/starred_queries.json
+    Starred queries are stored as starred_queries.json in the sqlit config directory.
     Structure: { "connection_name": ["query1", "query2", ...] }
 
     Starred queries persist independently of history - they are never auto-deleted
diff --git a/sqlit/domains/shell/app/commands/credentials.py b/sqlit/domains/shell/app/commands/credentials.py
@@ -4,6 +4,8 @@
 
 from typing import Any
 
+from sqlit.shared.core.store import CONFIG_DIR
+
 from .router import register_command_handler
 
 
@@ -85,15 +87,13 @@ def _handle_credentials_command(app: Any, cmd: str, args: list[str]) -> bool:
         if hasattr(app.services.connection_store, "set_credentials_service"):
             app.services.connection_store.set_credentials_service(app.services.credentials_service)
 
-        msg = "Credentials will be stored as plaintext in ~/.sqlit/ (protected folder)"
+        msg = "Credentials will be stored as plaintext in the sqlit config directory (protected folder)"
         if migrated > 0:
             msg += f" ({migrated} password(s) migrated from keyring)"
         app.notify(msg)
         return True
 
     if value == "keyring":
-        from sqlit.shared.core.store import CONFIG_DIR
-
         settings = app.services.settings_store.load_all()
         was_plaintext = settings.get(ALLOW_PLAINTEXT_CREDENTIALS_SETTING) is True
 
@@ -142,7 +142,7 @@ def _handle_credentials_command(app: Any, cmd: str, args: list[str]) -> bool:
         keyring_ok = is_keyring_usable()
 
         if allow_plaintext:
-            app.notify("Credentials: plaintext (~/.sqlit/credentials.json)")
+            app.notify(f"Credentials: plaintext ({CONFIG_DIR / 'credentials.json'})")
         elif keyring_ok:
             app.notify("Credentials: system keyring")
         else:
diff --git a/sqlit/domains/shell/app/main.py b/sqlit/domains/shell/app/main.py
@@ -750,7 +750,7 @@ def _show_command_list(self) -> None:
                 "Connection",
                 ":credentials [plaintext|keyring]",
                 "Configure password storage",
-                "Use 'plaintext' to store passwords in ~/.sqlit/ (protected folder), 'keyring' to use system keyring.",
+                "Use 'plaintext' to store passwords in the sqlit config directory (protected folder), 'keyring' to use system keyring.",
             ),
             ("Appearance", ":theme", "Open theme selection", ""),
             ("Query", ":alert off|delete|write", "Confirm before risky queries", "Modes: off, delete, write"),
diff --git a/sqlit/domains/shell/app/theme_manager.py b/sqlit/domains/shell/app/theme_manager.py
@@ -17,6 +17,7 @@
 
 from sqlit.domains.shell.store.settings import SettingsStore
 from sqlit.shared.core.protocols import SettingsStoreProtocol
+from sqlit.shared.core.store import CONFIG_DIR
 
 from .omarchy import (
     DEFAULT_THEME,
@@ -34,7 +35,7 @@
 )
 
 CUSTOM_THEME_SETTINGS_KEY = "custom_themes"
-CUSTOM_THEME_DIR = Path.home() / ".sqlit" / "themes"
+CUSTOM_THEME_DIR = CONFIG_DIR / "themes"
 CUSTOM_THEME_FIELDS = {
     "name",
     "primary",
diff --git a/sqlit/domains/shell/store/settings.py b/sqlit/domains/shell/store/settings.py
@@ -19,7 +19,7 @@ def _resolve_settings_path() -> Path:
 class SettingsStore(JSONFileStore):
     """Store for managing application settings.
 
-    Settings are stored as a JSON object in ~/.sqlit/settings.json
+    Settings are stored as settings.json in the sqlit config directory.
     """
 
     _instance: SettingsStore | None = None
diff --git a/sqlit/domains/shell/ui/screens/theme.py b/sqlit/domains/shell/ui/screens/theme.py
@@ -115,7 +115,7 @@ def compose(self) -> ComposeResult:
         shortcuts = [("Add", "<enter>"), ("Cancel", "<esc>")]
         with Dialog(id="custom-theme-dialog", title="Add Theme", shortcuts=shortcuts):
             yield Static(
-                "Enter theme name (template created in ~/.sqlit/themes/<name>.json):",
+                "Enter theme name (template created under <config-dir>/themes/<name>.json):",
                 id="custom-theme-description",
             )
             container = Container(id="custom-theme-container")
diff --git a/sqlit/shared/core/store.py b/sqlit/shared/core/store.py
@@ -8,8 +8,74 @@
 from pathlib import Path
 from typing import Any
 
-# Shared config directory - can be overridden via environment variable for testing
-CONFIG_DIR = Path(os.environ.get("SQLIT_CONFIG_DIR", Path.home() / ".sqlit"))
+LEGACY_CONFIG_DIR = Path.home() / ".sqlit"
+
+# Files that indicate the config directory already holds real user
+# config (as opposed to just side-effect cache files created by
+# earlier cloud-discovery code that wrote straight into ~/.config/sqlit).
+_CORE_CONFIG_FILES = ("settings.json", "connections.json", "credentials.json")
+
+
+def _has_core_config(path: Path) -> bool:
+    if not path.is_dir():
+        return False
+    return any((path / name).exists() for name in _CORE_CONFIG_FILES)
+
+
+def _resolve_config_dir() -> Path:
+    """Resolve the sqlit config directory, migrating from the legacy path if needed.
+
+    Precedence:
+      1. $SQLIT_CONFIG_DIR if set (no migration).
+      2. $XDG_CONFIG_HOME/sqlit (falling back to ~/.config/sqlit).
+
+    Migration rules when no env override is set:
+      - Legacy ~/.sqlit absent: nothing to do.
+      - New path absent: rename the whole legacy tree into place (one
+        atomic move on the same filesystem).
+      - New path exists but contains no core config files (e.g. only
+        cloud-discovery caches): move legacy entries in one-by-one,
+        skipping anything already at the destination, then drop the
+        empty legacy dir.
+      - New path already holds core config: leave legacy alone — the
+        user has (knowingly or not) set up the new location and we
+        don't want to clobber either side.
+    """
+    env_override = os.environ.get("SQLIT_CONFIG_DIR")
+    if env_override:
+        return Path(env_override).expanduser()
+
+    xdg_home = os.environ.get("XDG_CONFIG_HOME")
+    base = Path(xdg_home).expanduser() if xdg_home else Path.home() / ".config"
+    new_path = base / "sqlit"
+
+    legacy = LEGACY_CONFIG_DIR
+    if legacy.is_dir() and not _has_core_config(new_path):
+        try:
+            if not new_path.exists():
+                new_path.parent.mkdir(parents=True, exist_ok=True)
+                os.rename(legacy, new_path)
+            else:
+                for entry in legacy.iterdir():
+                    dest = new_path / entry.name
+                    if dest.exists():
+                        continue
+                    os.rename(entry, dest)
+                try:
+                    legacy.rmdir()
+                except OSError:
+                    pass
+        except OSError:
+            # e.g. cross-filesystem move. Fall through and let the user
+            # migrate manually or point SQLIT_CONFIG_DIR at the legacy path.
+            pass
+
+    return new_path
+
+
+# Shared config directory. Resolved once at import time so module-level
+# constants (e.g. CUSTOM_THEME_DIR) pick up the same value.
+CONFIG_DIR = _resolve_config_dir()
 
 
 class JSONFileStore:
diff --git a/tests/unit/test_config_dir_resolution.py b/tests/unit/test_config_dir_resolution.py

Original file line number	Diff line number	Diff line change
`@@ -372,7 +372,7 @@ def main() -> int:`
`372`	`372`	`parser.add_argument(`
`373`	`373`	`"--settings",`
`374`	`374`	`metavar="PATH",`
`375`		`- help="Path to settings JSON file (overrides ~/.sqlit/settings.json)",`
	`375`	`+ help="Path to settings JSON file (overrides the one in the sqlit config directory)",`
`376`	`376`	`)`
`377`	`377`	`parser.add_argument(`
`378`	`378`	`"--theme",`