Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/felixdotgo/querybox/llms.txt

Use this file to discover all available pages before exploring further.

​
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 unavailableIf 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 environmentsIf 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:
idnamedriver_typecredential_key
a1b2…Production DBpgsqlconnection:a1b2…
c3d4…Local MySQLmysqlconnection: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

Build docs developers (and LLMs) love

Get started for freeTalk to us