DataStoria: an AI-native ClickHouse console that runs your SQL in the browser

Who DataStoria is for, and the problem it addresses

ClickHouse work tends to split across three tools. You write SQL in one client, read system tables in another, and paste query text into a chat window when you want help. DataStoria puts those in a single console. The README describes it as an AI-native ClickHouse console covering "cluster diagnostics, query generation, evidence-based optimization, intelligent visualization."

The audience is a person who already operates ClickHouse and wants faster answers about it. The System Log Inspector section of the README lists timeline views, topology graphs, Materialized Views and ZooKeeper states. That is operator-facing material, not a beginner tutorial. The AI features assume you can judge a suggested query, because the README says the model "inspects schema, validates SQL, collects evidence, and recommends concrete ClickHouse performance improvements." A suggestion you cannot evaluate is not much use.

The project also ships a hosted instance at datastoria.app, so you can look at the interface before deciding whether to run it yourself. The repository is not archived, and the last push was on 2026-07-21, so the codebase has moved recently. There are no retrieved releases, which means version pinning for the Docker image is not documented in the README.

How the browser-to-cluster architecture actually works

The README makes one architectural claim that shapes everything else: "All SQL queries run directly from your browser to your ClickHouse server." DataStoria is a Next.js 16 and React 19 application, so there is a server component to it, but the query path bypasses that server. Your ClickHouse endpoint and credentials live in the browser session, and the app server never sees the result set.

The AI path follows the same split. The README states that for AI-generated visualizations, "the model produces SQL and chart specs while your browser fetches and renders the data locally." So the model returns a query and a chart description, and the data fetch happens client-side. That is why the visualization feature can cover time series, bar, pie and table views without shipping your rows to a model provider.

The practical consequence is network topology. If your ClickHouse cluster is only reachable from inside a VPC, a browser tab on a laptop will not connect to it, and the whole design stops working. The Docker image runs the Next.js app on port 3000, but that does not proxy queries. You still need a path from the browser to the cluster.

Agent SKILLs are the other mechanism worth noting. The README describes a "skill-based agent architecture that saves tokens across multi-turn conversations" and points at the Official ClickHouse Agent Skills repository. The package.json confirms this at build time: a sync:skills script runs before dev and as part of the dependency build step, and the repository has an external/ directory holding submodules. The build compiles several of those submodules locally (number-flow, vizlayer, cmdk) rather than consuming them from a registry.

Installing DataStoria and connecting a first cluster

The quickest route is the published Docker image. The README gives a single command and states that the image supports both linux/amd64 and linux/arm64, so it runs natively on Intel, AMD, Apple Silicon and ARM servers.

docker run -d -p 3000:3000 frankchen021/datastoria:latest

After that, open http://localhost:3000 in a browser. You should see the console, and from there you point it at your ClickHouse instance. Remember that the query connection is made by the browser, not by the container, so localhost:3000 being reachable is not sufficient on its own.

Building from source takes more steps. The README lists Node.js v22 or later and pnpm as prerequisites, and the clone command includes --recurse-submodules, which matters because the build compiles vendored packages from external/.

git clone --recurse-submodules https://github.com/FrankChen021/datastoria.git
cd datastoria
npm install --force
npm run dev

The README notes that npm install is run with --force, and the dev script starts six concurrent processes (the app plus five vendored package watchers) with an 8 GB Node heap. Expect a heavy local process tree. Configuration lives in .env, copied from .env.example. Two keys are worth setting early: NEXT_PUBLIC_APP_URL for SEO, and NEXT_PUBLIC_BASE_PATH if you deploy behind a reverse proxy context path. The .env.example warns that basePath is applied at build time only, so it must be set when running npm run build and when building the Docker image.

cp .env.example .env

The AI features need a model provider key, and the README points to doc/dev/llm-provider-api-key.md for that. Supported providers listed in the README include OpenAI, Anthropic Claude, Google Gemini, GitHub Copilot, OpenRouter, Groq, Cerebras and Nebius. GitHub Copilot uses a device flow sign-in, so an existing Copilot subscription can drive the chat features.

Where DataStoria is the wrong choice

The browser-to-cluster design is also its sharpest constraint. Any environment where the analyst's browser cannot open a connection to the ClickHouse HTTP endpoint is unsupported by construction. That covers air-gapped workstations, clusters behind a bastion host, and many managed ClickHouse offerings that restrict source IPs. There is no documented server-side query proxy to fall back on, and the README does not describe one.

Authentication is a second area to check before rollout. The README links an authentication guide covering OAuth setup for Google, GitHub and Microsoft, which implies NextAuth.js is the front door for the app itself. That is app login, not ClickHouse login. The two are separate, and the README does not describe a role model that maps app users to cluster permissions.

There is also a build-time constraint that will surprise anyone deploying under a subpath. Because NEXT_PUBLIC_BASE_PATH is baked in at build time, moving the app from / to /v2 later means rebuilding the image rather than changing an environment variable at runtime. The .env.example states this explicitly and gives the Docker build-arg form. Teams that expect twelve-factor style runtime configuration will find this rigid.

Finally, the AI features are only as good as the key you supply. The README's model is bring-your-own-key, with no bundled inference. If your organisation forbids sending schema information to an external model provider, the query generation and optimization features are effectively off, and what remains is a capable but conventional ClickHouse console.

DataStoria compared with Grafana and the ClickHouse HTTP interface

The obvious alternative for cluster monitoring is Grafana with the ClickHouse data source plugin. The approaches differ in where the intelligence sits. Grafana renders dashboards from queries you wrote in advance and stores them as configuration. DataStoria generates the query and the chart spec from a natural language request at the moment you ask, and the README describes pre-configured panels for query performance and ZooKeeper status alongside that. Grafana is the stronger choice for long-lived, versioned dashboards that many people view on a schedule. DataStoria is aimed at the exploratory moment when you do not yet know what to chart.

Against the plain ClickHouse HTTP interface or clickhouse-client, the difference is the surrounding context. A terminal client gives you a prompt and nothing else. DataStoria adds a schema explorer, one-click EXPLAIN with visual AST and pipeline views, and a dependency graph tracing Materialized Views, Distributed tables and external systems. Those are read-oriented views over system tables that you could assemble yourself, but the console does the assembly.

A third comparison the README invites is with a generic chat assistant. Pasting SQL into a chat window works, but the model has no schema access and no way to validate what it returns. The README's claim is that DataStoria's optimization path inspects schema, validates SQL and collects evidence before recommending changes. If that sequence holds in practice, the suggestions are grounded in your actual tables rather than in a guess. The README does not include evaluation results, so treat the quality claim as unverified.

Maintenance cost, licence and the code-analysis option

The build is not light. package.json shows a prebuild step that syncs skills and then builds five vendored packages from external/ before the Next.js build runs, and a postbuild step that copies resources. The dev script runs six processes concurrently. Anyone building from source is maintaining a submodule tree, so git submodule update matters on every pull. The Docker route avoids all of this, at the cost of tracking a latest tag with no documented releases.

The licence file is Apache License 2.0 according to the README, but the repository metadata reports the licence as NOASSERTION, meaning the automated detection did not confirm a match. Read the LICENSE file yourself rather than trusting either label, and note that the external/ submodules carry their own licences, which the README does not enumerate. Apache 2.0 includes a patent grant and requires attribution and a notice of changes; if you redistribute a modified build, those obligations apply to your distribution. This is not legal advice.

One optional feature deserves a separate cost estimate. The .env.example documents a code-analysis capability that lets the AI chat inspect a source repository in read-only mode. It is configured with CLICKHOUSE_CODE_REPO_LOCAL and CLICKHOUSE_CODE_REPO_REMOTE, and the example suggests pointing it at the ClickHouse source. The comment states that if the local path does not exist and the remote URL is set, the app starts cloning in the background on startup. Cloning the ClickHouse repository is a large, long-running operation, and the .env.example provides caps to bound tool output: CODE_ANALYSIS_MAX_FILE_BYTES, CODE_ANALYSIS_MAX_READ_LINES and CODE_ANALYSIS_MAX_SEARCH_RESULTS. Leave this disabled unless you actually want source-level answers, because the warmup has a real disk and time cost.

Editorial conclusion

Adopt DataStoria if you already run ClickHouse and want an editor, cluster dashboards and LLM assistance in one browser app without sending query results through a third party. Skip it if you need a server-side deployment where the browser cannot reach the cluster directly, or if you cannot supply your own model API key. Before committing, verify that the browser-to-cluster connection works from your network, check the LLM provider key document under doc/dev, and confirm the licence terms for your own distribution.

Frequently asked questions

Official sources

1. FrankChen021/datastoria on GitHub
2. Issues
3. Project website
4. README