# maxteabag/sqlit architecture

> Architecture diagram of the GitHub repository maxteabag/sqlit, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/maxteabag/sqlit
- Repository: https://github.com/maxteabag/sqlit

## Overview

sqlit is a keyboard-driven terminal SQL client with interactive and CLI entry points. Its principal workflow is to select or discover a database, establish a provider-backed connection, explore schema or edit and execute SQL, then inspect and filter results; query history and saved queries support repeat use. Separate product branches cover connection management and cloud/Docker discovery, schema browsing, result handling, and the CLI. The graph reflects README capabilities and sampled query and connection code; wiring for unsampled subsystems is shown only where documented or clearly supported by the repository structure.

Main entry points: [`sqlit/domains/connections/app/connection_flow.py`](https://github.com/maxteabag/sqlit/blob/main/sqlit/domains/connections/app/connection_flow.py) (Connection flow), [`sqlit/domains/query/ui/mixins/query.py`](https://github.com/maxteabag/sqlit/blob/main/sqlit/domains/query/ui/mixins/query.py) (SQL editor), [`sqlit/domains/query/app/query_service.py`](https://github.com/maxteabag/sqlit/blob/main/sqlit/domains/query/app/query_service.py) (Query service), [`sqlit/domains/connections/providers`](https://github.com/maxteabag/sqlit/tree/main/sqlit/domains/connections/providers) (Database providers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry and shell"]
  node_cli["CLI commands<br/>[cli.py]"]
  node_shell["TUI shell<br/>[main.py]"]
  node_settings[("Settings<br/>[settings.py]")]
end

subgraph group_connections["Connections"]
  node_conn_ui["Connection screens<br/>[screen.py]"]
  node_conn_flow["Connection flow<br/>[connection_flow.py]"]
  node_discovery["Discovery"]
  node_conn_manager["Connection manager"]
  node_session["Sessions and tunnels<br/>[session.py]"]
  node_provider["Database providers"]
  node_conn_store[("Saved connections<br/>[connections.py]")]
end

subgraph group_query["Query workflow"]
  node_query_editor["SQL editor<br/>[query.py]"]
  node_query_execution["Query execution UI<br/>[query_execution.py]"]
  node_query_service["Query service<br/>[query_service.py]"]
  node_query_history[("History and library<br/>[history.py]")]
  node_autocomplete["SQL completion<br/>[completion.py]"]
  node_vim["Vim editing"]
end

subgraph group_explorer["Schema explorer"]
  node_explorer["Schema tree<br/>[builder.py]"]
  node_schema_service["Schema service<br/>[schema_service.py]"]
end

subgraph group_results["Results"]
  node_results_ui["Result viewing<br/>[results.py]"]
  node_result_tools["Filter and export<br/>[results_filter.py]"]
end

node_user(("Terminal user"))
node_database[("Database")]
node_cloud_docker(("Cloud and Docker"))

node_user -->|"uses TUI"| node_shell
node_user -->|"runs commands"| node_cli
node_shell -->|"opens picker"| node_conn_ui
node_cli -->|"requests connection"| node_conn_flow
node_conn_ui -->|"selects connection"| node_conn_flow
node_conn_flow -->|"discovers targets"| node_discovery
node_cloud_docker -.->|"provides targets"| node_discovery
node_conn_flow -->|"loads and saves"| node_conn_store
node_conn_flow -->|"connects"| node_conn_manager
node_conn_manager -->|"creates session"| node_session
node_session -->|"uses provider"| node_provider
node_provider -->|"connects and executes"| node_database
node_shell -->|"loads preferences"| node_settings
node_user -->|"edits SQL"| node_query_editor
node_query_editor -->|"uses modal editing"| node_vim
node_query_editor -->|"requests completion"| node_autocomplete
node_query_editor -->|"executes SQL"| node_query_execution
node_cli -->|"executes SQL"| node_query_service
node_query_execution -->|"runs query"| node_query_service
node_query_service -->|"dispatches execution"| node_provider
node_query_service -->|"records queries"| node_query_history
node_query_execution -->|"displays results"| node_results_ui
node_user -->|"browses schema"| node_explorer
node_explorer -->|"loads schema"| node_schema_service
node_schema_service -->|"requests metadata"| node_provider
node_user -->|"filters or exports"| node_result_tools
node_results_ui -->|"offers actions"| node_result_tools

click node_cli "https://github.com/maxteabag/sqlit/blob/main/sqlit/cli.py"
click node_shell "https://github.com/maxteabag/sqlit/blob/main/sqlit/domains/shell/app/main.py"
click node_settings "https://github.com/maxteabag/sqlit/blob/main/sqlit/domains/shell/store/settings.py"
click node_conn_ui "https://github.com/maxteabag/sqlit/blob/main/sqlit/domains/connections/ui/screens/connection_picker/screen.py"
click node_conn_flow "https://github.com/maxteabag/sqlit/blob/main/sqlit/domains/connections/app/connection_flow.py"
click node_discovery "https://github.com/maxteabag/sqlit/tree/main/sqlit/domains/connections/discovery"
click node_conn_manager "https://github.com/maxteabag/sqlit/blob/main/sqlit/core/connection_manager.py"
click node_session "https://github.com/maxteabag/sqlit/blob/main/sqlit/domains/connections/app/session.py"
click node_provider "https://github.com/maxteabag/sqlit/tree/main/sqlit/domains/connections/providers"
click node_conn_store "https://github.com/maxteabag/sqlit/blob/main/sqlit/domains/connections/store/connections.py"
click node_query_editor "https://github.com/maxteabag/sqlit/blob/main/sqlit/domains/query/ui/mixins/query.py"
click node_query_execution "https://github.com/maxteabag/sqlit/blob/main/sqlit/domains/query/ui/mixins/query_execution.py"
click node_query_service "https://github.com/maxteabag/sqlit/blob/main/sqlit/domains/query/app/query_service.py"
click node_query_history "https://github.com/maxteabag/sqlit/blob/main/sqlit/domains/query/store/history.py"
click node_autocomplete "https://github.com/maxteabag/sqlit/blob/main/sqlit/domains/query/completion/completion.py"
click node_vim "https://github.com/maxteabag/sqlit/tree/main/sqlit/domains/query/editing"
click node_explorer "https://github.com/maxteabag/sqlit/blob/main/sqlit/domains/explorer/ui/tree/builder.py"
click node_schema_service "https://github.com/maxteabag/sqlit/blob/main/sqlit/domains/explorer/app/schema_service.py"
click node_results_ui "https://github.com/maxteabag/sqlit/blob/main/sqlit/domains/results/ui/mixins/results.py"
click node_result_tools "https://github.com/maxteabag/sqlit/blob/main/sqlit/domains/results/ui/mixins/results_filter.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_shell,node_settings,node_user toneBlue
class node_conn_ui,node_conn_flow,node_discovery,node_conn_manager,node_session,node_provider,node_conn_store,node_database toneAmber
class node_query_editor,node_query_execution,node_query_service,node_query_history,node_autocomplete,node_vim toneMint
class node_explorer,node_schema_service toneRose
class node_results_ui,node_result_tools,node_cloud_docker toneIndigo
```

## Components

### Entry and shell

- [CLI commands](https://github.com/maxteabag/sqlit/blob/main/sqlit/cli.py): `sqlit/cli.py`
- [TUI shell](https://github.com/maxteabag/sqlit/blob/main/sqlit/domains/shell/app/main.py): `sqlit/domains/shell/app/main.py`
- [Settings](https://github.com/maxteabag/sqlit/blob/main/sqlit/domains/shell/store/settings.py): `sqlit/domains/shell/store/settings.py`

### Connections

- [Connection screens](https://github.com/maxteabag/sqlit/blob/main/sqlit/domains/connections/ui/screens/connection_picker/screen.py): `sqlit/domains/connections/ui/screens/connection_picker/screen.py`
- [Connection flow](https://github.com/maxteabag/sqlit/blob/main/sqlit/domains/connections/app/connection_flow.py): `sqlit/domains/connections/app/connection_flow.py`
- [Discovery](https://github.com/maxteabag/sqlit/tree/main/sqlit/domains/connections/discovery): `sqlit/domains/connections/discovery`
- [Connection manager](https://github.com/maxteabag/sqlit/blob/main/sqlit/core/connection_manager.py): `sqlit/core/connection_manager.py`
- [Sessions and tunnels](https://github.com/maxteabag/sqlit/blob/main/sqlit/domains/connections/app/session.py): `sqlit/domains/connections/app/session.py`
- [Database providers](https://github.com/maxteabag/sqlit/tree/main/sqlit/domains/connections/providers): `sqlit/domains/connections/providers`
- [Saved connections](https://github.com/maxteabag/sqlit/blob/main/sqlit/domains/connections/store/connections.py): `sqlit/domains/connections/store/connections.py`

### Query workflow

- [SQL editor](https://github.com/maxteabag/sqlit/blob/main/sqlit/domains/query/ui/mixins/query.py): `sqlit/domains/query/ui/mixins/query.py`
- [Query execution UI](https://github.com/maxteabag/sqlit/blob/main/sqlit/domains/query/ui/mixins/query_execution.py): `sqlit/domains/query/ui/mixins/query_execution.py`
- [Query service](https://github.com/maxteabag/sqlit/blob/main/sqlit/domains/query/app/query_service.py): `sqlit/domains/query/app/query_service.py`
- [History and library](https://github.com/maxteabag/sqlit/blob/main/sqlit/domains/query/store/history.py): `sqlit/domains/query/store/history.py`
- [SQL completion](https://github.com/maxteabag/sqlit/blob/main/sqlit/domains/query/completion/completion.py): `sqlit/domains/query/completion/completion.py`
- [Vim editing](https://github.com/maxteabag/sqlit/tree/main/sqlit/domains/query/editing): `sqlit/domains/query/editing`

### Schema explorer

- [Schema tree](https://github.com/maxteabag/sqlit/blob/main/sqlit/domains/explorer/ui/tree/builder.py): `sqlit/domains/explorer/ui/tree/builder.py`
- [Schema service](https://github.com/maxteabag/sqlit/blob/main/sqlit/domains/explorer/app/schema_service.py): `sqlit/domains/explorer/app/schema_service.py`

### Results

- [Result viewing](https://github.com/maxteabag/sqlit/blob/main/sqlit/domains/results/ui/mixins/results.py): `sqlit/domains/results/ui/mixins/results.py`
- [Filter and export](https://github.com/maxteabag/sqlit/blob/main/sqlit/domains/results/ui/mixins/results_filter.py): `sqlit/domains/results/ui/mixins/results_filter.py`

### Other components

- **Terminal user**
- **Database**
- **Cloud and Docker**

## Connections

- Terminal user → TUI shell: uses TUI
- Terminal user → CLI commands: runs commands
- TUI shell → Connection screens: opens picker
- CLI commands → Connection flow: requests connection
- Connection screens → Connection flow: selects connection
- Connection flow → Discovery: discovers targets
- Cloud and Docker → Discovery: provides targets
- Connection flow → Saved connections: loads and saves
- Connection flow → Connection manager: connects
- Connection manager → Sessions and tunnels: creates session
- Sessions and tunnels → Database providers: uses provider
- Database providers → Database: connects and executes
- TUI shell → Settings: loads preferences
- Terminal user → SQL editor: edits SQL
- SQL editor → Vim editing: uses modal editing
- SQL editor → SQL completion: requests completion
- SQL editor → Query execution UI: executes SQL
- CLI commands → Query service: executes SQL
- Query execution UI → Query service: runs query
- Query service → Database providers: dispatches execution
- Query service → History and library: records queries
- Query execution UI → Result viewing: displays results
- Terminal user → Schema tree: browses schema
- Schema tree → Schema service: loads schema
- Schema service → Database providers: requests metadata
- Terminal user → Filter and export: filters or exports
- Result viewing → Filter and export: offers actions