How explorerhq/sql-explorer works
1. Repository shape
- This is a reusable Django application, packaged as explorer, plus a test_project that demonstrates embedding it in a real site.
- The package is split into a core app and an optional enterprise-style extension under explorer/ee, with separate URLs and models for upload/database-connection features.
2. Primary runtime boundary
- The main boundary is between the Django app and the SQL data sources it connects to.
- SQL Explorer does not own the data; it sends SQL to configured databases, receives tabular results, and renders those results in the browser.
3. Core request flow
- Incoming requests enter explorer/urls.py, then fan out into view modules under explorer/views/.
- Those views coordinate forms, permissions, model persistence, query execution, and response rendering through templates in explorer/templates/explorer/.
- The core user loop is: create/edit query → run query → inspect results → optionally save, favorite, export, email, or share.
4. Domain and persistence
- The app persists operational metadata rather than analytic data: saved queries, query logs, favorites, snapshots, prompt logs, database connections, and table descriptions.
- Migrations show the historical evolution of these models, including connection support, user favorites, LLM prompt logging, and upload-related metadata.
5. Query execution and result handling
- Query-related behavior is concentrated in views/query.py, views/export.py, views/download.py, views/email.py, views/stream.py, and related helpers.
- This layer is responsible for parameterized execution, result formatting, exporting, streaming large outputs, and auxiliary actions like email delivery.
- actions.py, exporters.py, and charts.py support non-CRUD behaviors around the query result set.
6. Schema introspection and UI assistance
- schema.py plus views/schema.py provide database/schema discovery so users can see tables, columns, and inferred structure.
- The browser-side schema service and editor integrations in src/js/schemaService.js, schema.js, and codemirror-config.js feed autocomplete and query assistance.
- This is a distinct read-only introspection path from actual query execution.
7. AI assistant subsystem
- The explorer/assistant/ package is its own feature slice with models, forms, views, URLs, and utilities.
- It stores prompt history and table descriptions so the assistant can enrich prompts with relevant schema/context before calling an external LLM provider.
- The README indicates OpenAI-compatible APIs, so the external dependency here is an LLM service, not just the database backend.
8. Uploaded-data and enterprise connection handling
- explorer/ee/db_connections/ handles user-uploaded or managed data connections, especially CSV, JSON, and SQLite.
- Supporting modules for MIME detection, type inference, SQLite creation, and connection models show that uploads are converted into queryable databases rather than treated as raw files.
- This subsystem is isolated behind its own URLs and forms, making it a clear optional boundary.
9. Frontend architecture
- Frontend code lives under explorer/src/js and explorer/src/scss, with Vite integration via vite.config.mjs and the custom templatetags/vite.py.
- The UI is modular: editor/query screens, favorites, pivot table, query list, schema helper, uploads, and assistant each have dedicated JS entry points.
- Static assets are built separately from the Django backend, then consumed by templates.
10. Background and operational concerns
- tasks.py and the feature list suggest scheduled/background work for snapshots and other deferred jobs.
- telemetry.py centralizes usage/diagnostic reporting concerns, keeping them separate from query execution and UI rendering.
- permissions.py and views/auth.py define access control boundaries around who can run, save, or manage queries and connections.
11. Admin and maintenance surfaces
- admin.py and the many model templates for connections, queries, logs, and assistant records indicate a substantial Django admin/management surface.
- This is important for architecture diagrams because operational users can manage configuration and metadata without using the main query UI.
12. Packaging, deployment, and validation
- The repo is packaged for distribution (setup.py, MANIFEST.in, requirements/), containerized (Dockerfile, docker-compose.yml), and continuously tested/linted via GitHub Actions.
- docs/ and test_project/ show that the project supports both embedded use in another Django site and a standalone demo/development deployment.
Main entry points: urls.py URLs · models.py Explorer models · query.py Query UI · export.py Query ops
Components 25
Core Django app
Main reusable explorer package: query UI, execution, persistence, schema discovery, and admin surfaces.
- URLs · Top-level request routing into the app's feature surfaces.
explorer/urls.py - Query UI · Create, edit, run, and inspect SQL queries; main user loop.
explorer/views/query.py - Query ops · Auxiliary result-set actions such as export, download, email, and streaming.
explorer/views/export.py - Schema UI · Read-only database discovery and schema presentation.
explorer/views/schema.py - Lists · Query lists, logs, and other browse/manage screens.
explorer/views/list.py - Access control · Authentication and permission-sensitive boundaries for the app.
explorer/views/auth.py - Explorer models · Saved queries, logs, favorites, snapshots, prompt logs, and other operational metadata.
explorer/models.py - Forms · User input handling for queries, filters, and metadata actions.
explorer/forms.py - Schema engine · Database inspection and schema metadata assembly used by the UI and assistant.
explorer/schema.py - Exporters · Transforms query results into downloadable formats and tabular representations.
explorer/exporters.py - Actions · Non-CRUD behavior around executing, favoriting, and manipulating query results.
explorer/actions.py - Permissions · Authorization rules for running, saving, and managing explorer resources.
explorer/permissions.py - Telemetry · Usage and diagnostic reporting separated from request handling.
explorer/telemetry.py - Tasks · Deferred or scheduled work such as snapshots and other operational jobs.
explorer/tasks.py
Assistant
LLM-assisted prompt enrichment and table-description workflow.
- Assistant data · Prompt history and table-description storage for contextual LLM assistance.
explorer/assistant/models.py - Assistant UI · Assistant forms, views, and utilities that prepare context for an external LLM.
explorer/assistant/views.py - Assistant URLs · Dedicated assistant feature routes isolated from the core explorer URLs.
explorer/assistant/urls.py
Enterprise upload/db connections
Optional extension for managed or uploaded data sources.
- EE URLs · Optional URLs for the upload and managed-connection extension.
explorer/ee/urls.py - Connections · Upload-backed and managed database connections for CSV, JSON, and SQLite sources.
explorer/ee/db_connections/models.py - Connection UI · Forms and views for creating, inspecting, and deleting managed connections.
explorer/ee/db_connections/views.py - Import utils · MIME detection, type inference, and SQLite creation for uploaded data.
explorer/ee/db_connections/utils.py
Frontend assets
Bundled JavaScript, styles, and Vite integration for the browser UI.
- JS entry · Main browser entry points that wire the Django templates to interactive UI features.
explorer/src/js/main.js - Schema service · Client-side schema discovery and autocomplete support.
explorer/src/js/schemaService.js - Vite build · Frontend build integration for bundling JS and CSS into templates.
vite.config.mjs
Demo project
Standalone Django project used to embed and exercise the app.
- Demo site · Standalone Django project showing how to embed the explorer app.
test_project/settings.py
Connections 26
- URLs → Query UI: routes · Core routes dispatch query screens and execution flows.
- URLs → Query ops: routes · Routes auxiliary export, download, email, and streaming actions.
- URLs → Schema UI: routes · Routes schema discovery and schema display pages.
- URLs → Lists: routes · Routes list and management views.
- URLs → Access control: routes · Routes authentication and access-control views.
- Query UI → Forms: uses · Query screens rely on forms for validation and parameters.
- Query UI → Explorer models: persists · Reads and writes saved queries, logs, favorites, and snapshots.
- Query UI → Actions: delegates · Execution and result-set behaviors are factored into query actions.
- Query ops → Exporters: formats · Export and download responses are rendered through exporters.
- Query ops → Explorer models: records · Operational actions can store logs and related metadata.
- Schema UI → Schema engine: introspects · Schema pages build on database discovery helpers.
- Schema engine → Schema UI: feeds · Schema metadata powers the read-only schema views.
- Explorer models → Permissions: gated by · Model-level operations are constrained by permissions.
- Access control → Permissions: enforces · Authentication views apply access policy boundaries.
- Telemetry → Explorer models: observes · Telemetry records usage and diagnostic signals tied to app activity.
- Tasks → Explorer models: updates · Background work operates on persisted operational metadata.
- Assistant URLs → Assistant UI: routes · Assistant-specific routing enters the assistant feature slice.
- Assistant UI → Assistant data: reads/writes · Assistant requests store prompt history and table descriptions.
- Assistant UI → Schema engine: enriches · Schema metadata is used to build contextual prompts.
- EE URLs → Connection UI: routes · Enterprise routes separate upload and managed connection screens.
- Connection UI → Connections: persists · Connection forms and views store managed data-source metadata.
- Import utils → Connections: creates · Uploaded files are converted into queryable database-backed connections.
- JS entry → Schema service: uses · Browser entry points consume the schema service for autocomplete and assistance.
- JS entry → Vite build: built by · Frontend bundles are produced through the Vite pipeline.
- Demo site → URLs: embeds · The demo site mounts the reusable explorer app.
- Demo site → EE URLs: optionally embeds · The demo site can also exercise the enterprise extension.