dbtui

A Vim-inspired terminal database workbench with a connection/table browser on the left, SQL editor in the center, and query results either below or beside the editor. Multiple saved connections can be switched in one TUI.

Install

Create and activate a virtual environment, then install the project into it:

python3 -m venv .venv
source .venv/bin/activate  # Windows PowerShell: .venv\\Scripts\\Activate.ps1
python -m pip install -e '.[all]'

Database drivers are optional. Install only what you need, for example python -m pip install -e '.[postgres,mysql,duckdb]' (while the venv is active). SQL Server (MSSQL) requires pyodbc and an OS-level SQL Server ODBC driver. SQLite is built in. Activate .venv before running dbtui.

Configure multiple connections

Create ~/.config/dbtui/connections.json (or point DBTUI_CONFIG / --config at a file):

{
  "connections": [
    {"name": "Local analytics", "type": "duckdb", "database": "analytics.duckdb"},
    {"name": "App PostgreSQL", "type": "postgresql", "database": "appdb", "options": {"host": "localhost", "user": "app", "password": "secret", "port": 5432}},
    {"name": "MySQL", "type": "mysql", "database": "appdb", "options": {"host": "localhost", "user": "app", "password": "secret"}},
    {"name": "SQL Server", "type": "mssql", "database": "", "options": {"connection_string": "DRIVER={ODBC Driver 18 for SQL Server};SERVER=localhost;DATABASE=appdb;UID=app;PWD=secret;TrustServerCertificate=yes"}},
    {"name": "Local TinyDB", "type": "tinydb", "database": "./documents.json"}
  ]
}

Keep credentials out of source control and restrict permissions on this file (chmod 600). type may be mssql, mysql, postgresql, duckdb, sqlite, or tinydb. PostgreSQL/MySQL connection parameters go under options; for SQL Server, provide a connection_string there. TinyDB is a document database rather than SQL: its editor supports commands such as tables, select users, select users active=true, insert users {"name":"Ada"}, and delete users name=Ada.

With the venv active, run dbtui or python dbtui.py.

Keys and commands

• i insert in editor; Esc back to normal mode. Press F5 to run the current query (same as :w). The editor shows a blinking terminal cursor at the insertion point while typing, and highlights the character under the cursor in normal mode.
• Normal mode: h/j/k/l, gg, G, a, A, o, O; q quits. Use [ and ] to cycle between query tabs. :tabnew [NAME] opens a tab, :tabnext / :tabprev cycle tabs, and :tabclose closes the current tab. Press Shift+? (?) for the in-app keybinding/help overlay.
• : opens command mode. :w executes the editor; :connect NAME switches connection; :connections lists profiles; :layout bottom / :layout side changes result placement; :save NAME saves or updates the current query; :queries opens the saved-query browser; :theme NAME changes the color theme (:theme lists options); :help opens the help overlay. Themes include default, catppuccin-mocha, catppuccin-frappe, catppuccin-macchiato, and catppuccin-latte. The selected theme is saved in ~/.config/dbtui/settings.json (or under $XDG_CONFIG_HOME) and restored on the next launch. Press any key to close help.
• Ctrl-W cycles focus between editor, table browser, and connections; the focused editor pane is highlighted in cyan and the selected connection/table in yellow (with reverse-video fallback on terminals without color). In the connections list j/k navigate and Enter selects a profile. In the table browser j/k navigate, Enter expands/collapses a table, and / filters table names. Ctrl-L refreshes table metadata.
• In editor insert mode, press Tab to show SQL keyword, table, or column hints without changing the query. Use ↑ / ↓ to choose a suggestion, then press Tab or Enter to insert it; Esc cancels the hints. Long table and completion lists scroll within their panes. Suggestions use metadata from the active connection.
• Saved queries: use :save NAME to save the editor contents and :queries to browse them. Press / in normal mode to open the saved-query browser directly in search entry; type a term and press Enter to filter query names, SQL text, and connection names case-insensitively. You can also use :queries and press / in the browser. Use arrows or j/k to navigate, Enter to load into the editor, d to delete, r to reload from disk, and Esc to clear the search or close the browser. Queries are stored in ~/.local/share/dbtui/queries.json (or $XDG_DATA_HOME/dbtui/queries.json).

Each query tab keeps its own editor contents, cursor, connection, and last results while you switch between them. This initial implementation is a lightweight curses TUI, not a full SQL IDE: query editing is intentionally basic, and result rendering is plain text. Query syntax remains the responsibility of the selected database.