DB Scout for Omarchy

DB Scout is a quick local database console for Omarchy. It discovers supported services running on the host or in Docker, lets you choose a logical database, and runs SQL or Redis commands in a native overlay.

Features

• Discovers local MariaDB/MySQL and PostgreSQL services
• Discovers MariaDB, MySQL, PostgreSQL, and Redis Docker containers
• Opens existing SQLite database files from an isolated fd + fzf picker
• Enumerates databases for the selected connection
• Runs SQL and Redis commands with captured output
• Requires confirmation for DROP, TRUNCATE, unqualified UPDATE/DELETE, FLUSHDB, and FLUSHALL
• Caps output at 1 MiB and errors at 64 KiB by default
• Cancels running commands and enforces a 30-second timeout by default
• Closes with Esc or a click outside the panel

DB Scout is intended for quick work against trusted local development databases. Its confirmation step is a guard against accidents, not a security boundary or complete SQL parser. Review commands before running them.

Requirements

• A current Omarchy installation with third-party shell plugin support
• jq
• fd, fzf, and foot for the isolated SQLite file picker (included with Omarchy)
• Docker for Docker database discovery
• A host client for SQL databases:
  • mariadb or mysql for MariaDB/MySQL
  • psql for PostgreSQL
  • sqlite3 for SQLite files

Docker Redis connections use redis-cli or valkey-cli inside the container. Docker SQL connections still use the corresponding host SQL client. DB Scout reports a missing client in the status area instead of attempting to install software.

Missing clients remain visible with an Omarchy install command and an Ask agent action. That action opens the configured Omarchy coding agent with sanitized connection metadata and the expected package command. The prompt forbids inspecting database contents or credentials and asks the agent to explain the remediation before making changes. DB Scout never installs packages, requests elevated privileges, or launches an agent without an explicit click.

Install

omarchy plugin add https://github.com/itissdr/omarchy-dbscout-plugin.git --enable

Omarchy clones the repository to ~/.config/omarchy/plugins/itissdr.dbscout/. Third-party plugins execute unsandboxed inside omarchy-shell; review code before enabling plugins you do not trust.

Open DB Scout directly with:

omarchy-shell shell summon itissdr.dbscout '{}'

Update or remove it with the supported plugin commands:

omarchy plugin update itissdr.dbscout
omarchy plugin remove itissdr.dbscout

Optional menu entry

Add these entries to ~/.config/omarchy/extensions/omarchy-menu.jsonc if you want DB Scout under the Omarchy menu:

{
  "databases": {"icon":"","label":"Databases"},
  "databases.dbscout": {"icon":"","label":"DB Scout","action":"omarchy-shell shell summon itissdr.dbscout","parent":"databases"},
  "databases.refresh": {"icon":"","label":"Refresh Connections","action":"omarchy-shell shell summon itissdr.dbscout '{}'","parent":"databases"}
}

Usage

Select a detected connection in the left sidebar, select its database, enter a command, and press Ctrl+Enter or click Run. A running command can be cancelled from the same button.

The query helper uses the current system user and each database client's normal configuration by default. Optional overrides are:

• OMARCHY_DBSCOUT_USER
• OMARCHY_DBSCOUT_DATABASE
• OMARCHY_DBSCOUT_OUTPUT_LIMIT in bytes, minimum 1024
• OMARCHY_DBSCOUT_ERROR_LIMIT in bytes, minimum 1024
• OMARCHY_DBSCOUT_TIMEOUT as a timeout(1) duration such as 10s or 2m
• Standard client password variables such as MYSQL_PWD and PGPASSWORD

The older OMARCHY_SQL_* names remain accepted for compatibility.

Authentication

DB Scout does not store credentials. Host connections use the database clients' normal authentication mechanisms, so existing client configuration remains the safest option:

• MariaDB/MySQL: ~/.my.cnf, the current Unix-socket identity, or MYSQL_PWD
• PostgreSQL: ~/.pgpass, peer authentication, or PGPASSWORD
• Redis: Docker connections read REDIS_PASSWORD from the container environment when present

When discovery is permission-limited or authentication fails, the database picker offers a provider-aware login for MariaDB/MySQL, PostgreSQL, and Redis/Valkey. Credentials entered there are passed only to the relevant client subprocess, kept in memory for the selected connection, and cleared when the connection changes or DB Scout closes. They are never written to disk or included in command-line arguments.

OMARCHY_DBSCOUT_USER and OMARCHY_DBSCOUT_DATABASE select a host SQL user and default database; they do not supply a password. Environment overrides must be visible to the long-running omarchy-shell process, so client configuration files are generally more reliable than variables exported in a terminal after login.

For DockerDB-style containers, DB Scout reads the container's standard initialization variables: MYSQL_ROOT_PASSWORD, POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB, and REDIS_PASSWORD. Images configured through secrets, custom users, ACL files, or nonstandard variables may require future connection-profile support.

Development

The repository root is the plugin root required by Omarchy. manifest.json points to DBScout.qml; the remaining QML, JavaScript, and shell helpers are local dependencies of that entry point.

Run the checks with:

for file in *.qml; do qmllint "$file"; done
QT_QPA_PLATFORM=offscreen /usr/lib/qt6/bin/qmltestrunner -input tests -o -,txt
tests/test-run-query.sh
tests/test-dependencies.sh
bash -n ./*.sh tests/*.sh tests/bin/*
jq . manifest.json

The same checks run in GitHub Actions for every push and pull request.

Roadmap

• Saved connection profiles and authentication settings
• Query history and favorites
• Table and schema browsing
• CSV and JSON export
• Syntax highlighting
• MongoDB support

License

MIT