Managing Stored Credentials

Understand how QueryBox stores and protects your database credentials

Managing Stored Credentials

QueryBox prioritizes security by storing your database credentials in your operating system’s native keyring, not in plain text files.

How Credentials Are Stored

Three-Tier Storage System

QueryBox uses a three-tier fallback chain to ensure credentials are always available, even in environments where the OS keyring is unavailable:

1. Tier 1: OS Keyring (Preferred)

   Primary storage for all credentials

   • macOS - Keychain Access (same as Safari, Mail, and system passwords)
   • Windows - Credential Manager (Windows Vault)
   • Linux - Secret Service API (GNOME Keyring, KWallet, or compatible)

   Credentials stored in the OS keyring are encrypted by the operating system and protected by your user login.

2. Tier 2: SQLite Fallback

   Used when keyring is unavailable

   If the OS keyring is not accessible (e.g., on headless servers or CI environments), QueryBox falls back to a local SQLite database:

   • Location: ~/Library/Application Support/querybox/credentials.db (macOS), %APPDATA%\querybox\credentials.db (Windows), ~/.config/querybox/credentials.db (Linux)
   • Security: File is protected by filesystem permissions (readable only by your user account)
   • Encryption: Credentials are not encrypted in the SQLite file

   If you’re using SQLite fallback, ensure the file is not synced to cloud storage or accessible to other users. Restrict permissions to 600 (owner read/write only).

3. Tier 3: In-Memory (Ephemeral)

   Last resort for temporary environments

   If both keyring and SQLite fail (e.g., no write permissions), credentials are stored in memory:

   • Lifespan: Cleared when QueryBox quits
   • Use Case: Testing, sandboxed environments, or CI pipelines
   • Security: Not persistent; safe for ephemeral workloads

Credential Keys

Each connection’s credential is stored under a unique key:

connection:<uuid>

For example:

connection:a1b2c3d4-e5f6-7890-abcd-ef1234567890

The connections.db database stores only this key reference, never the actual password or token.

Viewing Stored Credentials

QueryBox does not provide a UI to view raw credentials. To inspect what’s stored:

macOS Keychain

1. Open Keychain Access

   Launch Keychain Access from Applications > Utilities.

2. Search for QueryBox Entries

   In the search bar, type querybox.

   All QueryBox credentials appear with the service name “querybox” and account names like connection:<uuid>.

3. View or Delete

   • Double-click an entry to view metadata (not the password)
   • Right-click and choose Delete to remove a credential

Windows Credential Manager

1. Open Credential Manager

   Search for “Credential Manager” in the Start menu.

2. Navigate to Generic Credentials

   Click Windows Credentials or Generic Credentials.

3. Find QueryBox Entries

   Look for entries with “querybox” in the name.

   Click an entry to view details or Remove to delete.

Linux Secret Service

1. Open Keyring Manager

   • GNOME: Search for “Passwords and Keys” (Seahorse)
   • KDE: Open KWallet Manager
2. Locate QueryBox Entries

   Browse the default keyring for items with the service “querybox”.

3. Manage Entries

   Right-click to delete or view properties.

Security Best Practices

What QueryBox Does Automatically

• Keyring Encryption - OS keyrings encrypt credentials at rest using your login password
• No Plain Text - Connection passwords never appear in connections.db
• Least Privilege - Only the QueryBox process can access its keyring entries
• Automatic Cleanup - Deleting a connection removes its credential from the keyring

What You Should Do

Use Strong Database Passwords - Even with keyring storage, weak passwords can be compromised through database server attacks.

Protect SQLite Fallback Files - If your OS keyring is unavailable, ensure credentials.db has restricted permissions:

chmod 600 ~/.config/querybox/credentials.db

Avoid Shared Accounts - Each user should have their own database credentials; don’t share a single QueryBox installation with stored credentials.

Troubleshooting

Keyring Access Denied

Symptom: “Failed to store credential: keyring unavailable”

Causes:

• macOS: Keychain Access is locked or permission denied
• Windows: Credential Manager service is disabled
• Linux: No Secret Service daemon running (e.g., headless server)

Solution:

1. Verify your OS keyring is accessible:
   • macOS: Open Keychain Access and unlock the “login” keychain
   • Windows: Check that Credential Manager opens without errors
   • Linux: Ensure gnome-keyring-daemon or kwalletd is running
2. If the keyring is unavailable, QueryBox automatically falls back to SQLite storage
3. Check the Logs panel for detailed error messages

Credentials Not Found

Symptom: “No credential stored” when connecting

Causes:

• Connection was created before credential storage was implemented
• Credential was manually deleted from the keyring
• Keyring was reset or cleared

Solution:

1. Delete the connection from QueryBox
2. Recreate it with the correct credentials
3. Verify the new credential is stored by connecting successfully

Migration from Legacy Storage

Older versions of QueryBox (before v1.0) stored credentials in a credential_blob column. The current version automatically migrates these to the keyring:

1. Automatic Migration on Startup

   When you launch QueryBox, it scans for connections with legacy credential_blob data.

2. Keyring Storage

   For each legacy credential:

   1. A keyring entry is created with key connection:<uuid>
   2. The credential_key column is updated
   3. The credential_blob column is cleared
3. Verify Migration

   Test each migrated connection to ensure credentials are accessible.

Migration happens silently; you don’t need to take any action. Check the Logs panel for migration status messages.

Backup and Export

Backing Up Credentials

QueryBox does not provide a built-in credential export feature for security reasons. To back up credentials:

1. Document passwords separately - Use a password manager (1Password, LastPass, Bitwarden)
2. OS Keyring Backup - Use your operating system’s built-in backup tools:
   • macOS: Time Machine backs up Keychain automatically
   • Windows: Windows Backup includes Credential Manager
   • Linux: Back up ~/.local/share/keyrings/ (or equivalent)

Copying the connections.db file alone is not sufficient - it only contains connection metadata, not credentials.

Moving to a New Machine

1. Copy Connection Metadata

   Transfer the connections.db file from the old machine to the new one.

   Old Machine Path:

   • macOS: ~/Library/Application Support/querybox/connections.db
   • Windows: %APPDATA%\querybox\connections.db
   • Linux: ~/.config/querybox/connections.db
2. Recreate Credentials

   On the new machine, open QueryBox and test each connection.

   If credentials are missing (likely, since the keyring is machine-specific), delete and recreate each connection.

3. Or: Migrate Keyring

   Advanced users can export/import OS keyring entries:

   • macOS: Export from Keychain Access, import on new Mac
   • Windows: Use cmdkey or Credential Manager export
   • Linux: Copy keyring files manually (requires matching user account)

Credential Lifecycle

Creation

When you save a new connection:

1. QueryBox generates a UUID (e.g., a1b2c3d4-...)
2. The credential JSON (passwords, tokens) is sent to CredManager.Store("connection:<uuid>", json)
3. CredManager attempts to store in the OS keyring, then SQLite, then memory
4. The connection record is saved with credential_key: "connection:<uuid>"

Retrieval

When you connect to a database:

1. QueryBox reads the credential_key from connections.db
2. CredManager.Get("connection:<uuid>") fetches the credential from keyring → SQLite → memory
3. The credential JSON is passed to the database plugin
4. The plugin uses it to establish a connection

Deletion

When you delete a connection:

1. QueryBox looks up the credential_key
2. CredManager.Delete("connection:<uuid>") removes the credential from all tiers (best-effort)
3. The connection record is removed from connections.db

Credential deletion is best-effort: if the keyring is temporarily unavailable, the credential may persist. Manually remove it from the OS keyring if needed.

Advanced: Direct Database Access

Inspecting connections.db

Advanced users can query the SQLite database directly:

sqlite3 ~/Library/Application\ Support/querybox/connections.db

SELECT id, name, driver_type, credential_key FROM connections;

Output:

id	name	driver_type	credential_key
a1b2…	Production DB	pgsql	connection:a1b2…
c3d4…	Local MySQL	mysql	connection:c3d4…

Never modify connections.db manually - it can corrupt your connection list and orphan credentials in the keyring.

Inspecting credentials.db (Fallback)

If using SQLite fallback storage:

sqlite3 ~/.config/querybox/credentials.db

SELECT key FROM credentials;

This shows which credentials are stored in the fallback tier. Do not query the value column - it contains sensitive passwords in plain text.

Security Audit

To verify credential security on your system:

1. Check Storage Tier

   Open QueryBox logs and search for “CredManager” messages. Look for:

   • “stored in keyring” (Tier 1 - secure)
   • “keyring unavailable, using sqlite” (Tier 2 - fallback)
   • “using memory store” (Tier 3 - ephemeral)
2. Verify Keyring Access

   • macOS: Open Keychain Access, search for “querybox”, confirm entries exist
   • Windows: Open Credential Manager, verify “querybox” entries
   • Linux: Check Secret Service with secret-tool search service querybox
3. Review File Permissions

   If using SQLite fallback:

   ls -la ~/.config/querybox/credentials.db
   

   Ensure permissions are -rw------- (600) or stricter.

4. Test Deletion

   1. Create a test connection
   2. Verify the credential appears in the keyring
   3. Delete the connection from QueryBox
   4. Confirm the credential is removed from the keyring

Tips

• Use OS Keyring When Possible - It’s the most secure tier; ensure your keyring daemon is running
• Rotate Passwords Regularly - Update database passwords and recreate connections in QueryBox
• Limit Connection Scope - Create read-only connections for browsing; use separate write-enabled connections for modifications
• Monitor Logs - The Logs panel shows credential storage events; watch for fallback warnings
• Backup Separately - Don’t rely on QueryBox alone; store credentials in a password manager as backup