SQL-first dashboard authoring with automatic chart recommendations and visual editing. Write queries, inspect the inference, adjust panels, and explore data through interactive dashboards.
Development status: the latest repository release tag is v0.2.11; the
development branch contains later, unreleased changes. The project is under active development.
Security work in progress: author routes now require authentication and viewer data requests validate the share's scope, password session and revocation. HTTP analytical queries now run in a separate catalog with execution budgets; external sources and local views require future dataset adapters. Use a controlled local environment and test data; do not expose this build to an untrusted network. The CLI now defaults to
127.0.0.1and leaves Quack disabled. See the implemented authorization policy. See analytical isolation, limits and compatibility. See parameter contracts and quality checks. See the audit and remediation plan.
The next stage combines SQL authoring with visual dashboard design over reusable datasets. A visual query builder, governed metrics, and team permissions are planned capabilities, not features already delivered.
The accepted project resource direction commits SQLviz to reusable datasets/measures, an on-demand project library, dependency navigation, exportable definitions, analytical APIs and alerts. These modules are planned for implementation in small increments integrated with the Studio sequence; their acceptance does not mean they are already delivered.
The accepted Studio direction provides three authoring levels on the same visual: automatic inference, a Visual Builder, and expert native ECharts JSON options. Dataset definitions, reusable visuals and dashboard panel instances will be separate. Manual canvas geometry is now an internal core module; its persistence and UI are next. Drag/resize, the complete Visual Builder, expert editor and reusable dataset persistence are planned, not implemented features. The minimum dataset/visual contract precedes the complete three-level authoring workflow. See the accepted authoring decision. The Studio delivery plan defines the current sequence and completion criteria; the canvas contract states what exists. The first S1 increment replaces delimiter splitting with backend DuckDB syntax analysis for Run, statement counts and editor focus. Stable panel reconciliation, atomic script commits and verified Run completion are now implemented; see the script parsing contract.
The expanded, planned inference architecture adds scoped SQL AST analysis, lineage, evidence and explicit ambiguity. The visual target covers all 23 core ECharts series families through typed data bindings and shape adapters; GL and custom extensions require their own compatibility and resource checks. These are design goals, not newly supported chart identifiers. See semantic inference and the capability matrix.
An analytical BI matrix is also a central planned module: hierarchical row/column axes, measures, context-aware totals, field drag-and-drop and a dedicated grid renderer. Its first workflow belongs to S3/S4, before broad chart expansion. The current flat table does not implement it. The Studio plan breaks dashboard panel drag/resize into six increments.
The architecture report v2 assessment
checks semantic modeling, Rill, Polars and materialization proposals against the
repository. It distinguishes optional Quack serving from current HTTP execution
and confirms that .sqlviz uses DuckDB. These recommendations preserve the
Studio sequence and do not introduce a new engine or storage migration.
Start with the documentation index, target architecture, and current delivery plan.
Workspace navigation can be hidden completely, uses a modal on narrow screens, and provides dashboard search. The editor exposes command search and focus mode. Preview and workspace viewers switch from the dashboard title with integrated search, without opening the sidebar or reducing the dashboard canvas. Filters are edited in a temporary panel and applied together; failed updates retain confirmed data and criteria. A compact logo button at the top left opens or closes the library; appearance and secondary actions remain under view options. The logo reveals the open/close icon on hover or keyboard focus; touch devices keep that action icon visible in the same button. See implemented behavior and validation. See reader context, architecture and limits. Screen-fit page layouts and broader visual customization remain planned.
Dashboard deletion now removes its panels, share links and saved filters in one transaction, with rollback and protection against concurrent child creation. See the implemented integrity policy.
Folder destinations are validated transactionally, including concurrent moves
and deletion. Explicit null detaches a folder or dashboard to root; omission
preserves placement. See folder integrity.
The current explorer still displays flat groups.
Manual panel dimensions are validated before saving: 1–12 columns and 120–900 px. The editor displays confirmed sizes and preserves the chart when a save is rejected. See dimension contracts and learning limits.
Dashboard composition now validates typed inference results before calling the engine, rejects invalid requests with 422, and preserves presentation labels and manual dimensions. See the composition contract. Dashboard PATCH now validates strict fields, distinguishes omission from explicit clearing, preserves exact SQL drafts, and commits all changes atomically. See the dashboard PATCH contract. Basic panel PATCH now validates name/SQL/order, preserves visual settings and commits atomically. Panel and dashboard deletion also conflict with active panel edits. See the basic panel contract. Presentation PATCH now validates titles and axis labels and commits them atomically. The editor confirms saved text and retains failed drafts for retry, including axis labels edited on the chart. See presentation contracts and reset behavior. Manual chart choices now use supported identifiers, atomic confirmation and honest retry when refresh fails; reset clears the choice instead of pinning the current recommendation. See chart override behavior. The remaining dimension review belongs to S1 in the Studio delivery plan.
Author executions now publish inference and dashboard classification in one short transaction, conditional on the captured SQL and manual chart choice. Concurrent edits return a safe conflict instead of saving obsolete inference. Author Run carries a separate definition reference through execution and composition, rejecting incompatible SQL, panel sets and response references. Run success now requires server-signed execution/composition receipts and an atomic definition check; draft PATCH cannot forge last-run metadata. See inference publication and its limits. See Run definition references. See verified Run completion and limits. Workspace reload now verifies persisted SQL bindings against native parsing, preserves newer drafts and loads definitions before restoring compatible cached results. It never executes queries automatically. See snapshot reload and recovery limits. Draft generations and an internal conditional writer are implemented in S1.1c.2c.3a; existing PATCH and Run commits advance the same durable counter. See draft revisions and limits. The draft API, autosave integration and lost-response recovery remain next in 3b–d. The current UI still uses legacy autosave without an expected revision.
Six packages in one monorepo:
| Package | Current responsibility |
|---|---|
sqlviz-core |
Shared domain types, source/rendering contracts, version lookup |
sqlviz-inference |
SQL analysis, recommendation pipeline, visual specs and layout |
sqlviz-storage |
DuckDB project files, migrations, overrides, auth/share helpers and learning persistence |
sqlviz-api |
FastAPI application factory, HTTP routes and SPA hosting |
sqlviz-cli |
Project creation/opening and local server startup |
sqlviz-web |
SvelteKit/Svelte 5 editor and viewers, ECharts rendering |
The API executes analytical queries through an app-local QueryService in a separate DuckDB catalog. Legacy local data tables are projected without attaching the project or migrating its file. Source contracts do not yet imply production-ready connectors.
- Python 3.12+ (CI matrix: 3.12/3.13; local review: 3.13).
- Node.js 24.21.0 and npm (
.node-version, shared by CI and local review). - uv.
git clone https://github.com/eribertocz/sqlviz.git
cd sqlviz
uv sync --all-packages
cd packages/sqlviz-web
npm ciThis is a uv workspace. Use uv sync --all-packages; plain uv sync does not
install all five Python members required by the API and tests.
From the repository root, start the demo API on the port expected by Vite:
uv run sqlviz --host 127.0.0.1 --port 4000 --no-browserDemo mode uses an in-memory project and bypasses admin login. In a second terminal:
cd packages/sqlviz-web
npm run devOpen http://localhost:5173. The frontend proxies /api to port 4000.
sqlviz_api.main exposes create_app(connection); it has no module-level app
for uvicorn sqlviz_api.main:app.
For a persistent test project, replace the API command with:
uv run sqlviz local-demo.sqlviz --host 127.0.0.1 --port 4000 --no-browserThe CLI prompts for an admin password when creating a project. Author API routes require that login; shared viewers use credentials limited to their share. Source adapters and operational hardening remain pending, as described above.
Both demo and persistent projects listen on 127.0.0.1 by default. LAN binding
requires an explicit --host 0.0.0.0; the security limitations above still
apply. Normal startup does not install extensions or start a Quack service.
Quack is a separate, optional database service enabled with --quack. It requires
a preinstalled compatible extension and SQLVIZ_QUACK_TOKEN with at least 32
characters after trimming surrounding whitespace. Its credential grants database
access independently of SQLviz login/share permissions. See the
startup policy, configuration and verification.
From packages/sqlviz-web:
npm run check
npm test
npm run buildThe static build is written to packages/sqlviz-api/src/sqlviz_api/static/dist.
After building, the CLI serves the UI and API together at http://127.0.0.1:4000.
Build the frontend first: Python HTTP tests exercise the real login SPA and
static assets. CI builds it in the frontend job and passes that artifact to both
Python jobs, so a clean checkout does not depend on a local dist directory.
Then, from the repository root:
uv run pytest
uv run ruff check packages/
uv run mypy packages/sqlviz-core/src packages/sqlviz-inference/src packages/sqlviz-storage/src packages/sqlviz-api/src packages/sqlviz-cli/srcThe audit records the measured baseline, including existing type errors and frontend warnings. Passing functional tests does not establish the security of this build.
The development API is at http://127.0.0.1:4000/api/v1; FastAPI exposes its
OpenAPI document at /openapi.json and interactive documentation at /docs.
Main resources include dashboards, panels, folders, authentication and shares.
Python distribution versions derive from git through hatch-vcs, but an already installed editable environment can retain stale version metadata. The audit also records hardcoded API/project versions that still need consolidation. Version of the product, API contracts and project schema are separate concepts.
See CHANGELOG.md for delivered changes. Historical design plans are not a substitute for release notes or the current code.