ProvSQL Studio
Web UI for ProvSQL: provenance inspection, circuit visualisation, and on-the-fly semiring evaluation.
ProvSQL is a PostgreSQL extension that adds (m-)semiring provenance and uncertainty management to PostgreSQL, transparently rewriting queries to track provenance as circuit tokens. ProvSQL Studio is a small Flask app that lets you point a browser at a ProvSQL-enabled database and inspect that provenance interactively, without writing the query-wrapping boilerplate by hand.
Website: https://provsql.org/ – Documentation: https://provsql.org/docs/user/studio.html
Inspection modes
Two complementary modes share the same UI (query box, result table, sidebar):
Where mode highlights the source cells that contributed to each output value. Hover a result cell and the contributing cells of the underlying provenance-tracked relations light up in the sidebar. The query is wrapped automatically with
provsql.where_provenance, so no explicitwhere_provenance(...)call is needed.Circuit mode renders the provenance DAG behind a result’s UUID or aggregate token. Click a UUID cell to load its DAG, hover to highlight a subtree, click to pin a node and open the inspector. Frontiers expand on demand so deep circuits stay readable. An evaluation strip targets the pinned node (or the root) and runs provenance evaluation in various semirings, probability computation through various methods, or PROV-XML export, with the result rendered inline.
A schema panel and a configuration panel round out the UI; see the documentation for the full feature reference.
Install
pip install provsql-studio
Requires Python 3.10+ and a PostgreSQL database with the ProvSQL
extension installed (see the
extension installation guide).
Studio 1.0.x targets ProvSQL extension 1.4.0 or newer; the startup
check refuses to launch against an older extension unless
--ignore-version is passed.
Connecting
Launch Studio with a DSN:
provsql-studio --dsn postgresql://user@localhost:5432/mydb
Without --dsn, libpq’s standard environment variables (PGDATABASE,
PGSERVICE, DATABASE_URL…) are honoured. If neither is set,
Studio connects to the postgres maintenance database and offers an
in-page database picker.
The browser reaches the UI at http://127.0.0.1:8000/. Override the
bind address and port with --host and --port. Per-request size
caps, statement timeout, and search path are tunable on the CLI
(--max-circuit-nodes, --max-sidebar-rows, --max-result-rows,
--statement-timeout, --search-path) and through the Config panel;
the panel persists its settings to
~/.config/provsql-studio/config.json.
Documentation
The full Studio user guide, including screenshots, the configuration reference, the compatibility matrix, and worked examples, lives at:
https://provsql.org/docs/user/studio.html
For the underlying ProvSQL SQL API (add_provenance,
create_provenance_mapping, view_circuit, provenance_evaluate,
and the rest), see https://provsql.org/docs/.
License
MIT: see LICENSE.
Contact
https://github.com/PierreSenellart/provsql
Pierre Senellart pierre@senellart.com
Bug reports and feature requests are preferably sent through the Issues feature of GitHub.