WrenAI: A Governed Text-to-SQL Engine That Treats Context as Code

The Problem: Agents That Guess at SQL Without Business Context

A raw LLM agent can write SQL, but it does not know that 'revenue' means net of returns in your company, or that a particular join is the approved one. Schemas do not carry that meaning. WrenAI addresses this by adding a governed semantic layer, called MDL, plus an AI context layer that includes tribal knowledge buried in docs and chat threads. The intended user is a developer or data team building agents with tools like Claude Code or Cursor who wants those agents to produce not just plausible SQL but trustworthy dashboards. The README is explicit about who should skip it: anyone who only needs a one-off chart from a single CSV, or anyone happy with ungoverned guesses.

How It Works: MDL Planning, Dry-Plan Validation, and Structured Errors

The architecture rests on a few named mechanisms. Schema-aware retrieval pulls the relevant tables and columns for a question. MDL planning then uses the semantic model to map business terms to physical schema. A dry-plan validation step checks the generated SQL plan before execution, and structured errors with hints are returned when something fails. The README also lists row limits and value profiling. The key design choice is that the semantic layer is not a prompt hack; it is versionable files. Definitions, examples and memory are written as reviewable YAML and Markdown files. This is a concrete data flow: the agent recalls MDL context and past queries, writes governed SQL, and executes it via `wren query`.

Getting It Running: CLI First, Agent Drives the Rest

Installation is via pip. A bundled `jaffle_shop` sample lets you start without a database of your own. The README shows: pip install wrenai for the core, and pip install "wrenai[postgres,memory]" to add per-datasource and memory extras. The workflow is agent-driven: you install the CLI, install a one-file discovery stub for your AI client, and then let the agent handle the rest. Workflow guides are served on demand from inside the CLI, which means the instructions always match the installed version. That is a practical touch, because it avoids the common problem of stale documentation. If you are in mainland China and pip is slow, the README suggests `pip install wrenai -i https://pypi.tuna.tsinghua.edu.cn/simple`, and setting `HF_ENDPOINT=https://hf-mirror.com` if HuggingFace model downloads time out.

The Open-Core Boundary: What Is Free vs. What Costs Money

The repository license is marked NOASSERTION in the metadata, and the root carries LICENSE-APACHE-2.0, LICENSE-AGPL-3.0 and LICENSE-CC-BY-4.0 alongside LICENSE. The README states that the core engine, SDK, and skills are under Apache-2.0 and that it runs without the vendor. The team-wide path is different: Git Sync turns the same project repo into a governed deployment in Wren Cloud or a self-hosted installation, including air-gapped. The project's homepage is its open-core page, which is where to check which features sit outside the Apache-2.0 core. If your compliance regime requires row- or column-level controls, confirm where they live before adopting.

Deployment and the Wasm Dashboard Path

One distinctive feature is the ability to deploy dashboards from an answer. The README describes turning any answer into a shareable, browser-side dashboard then shipping it to your own Vercel or Cloudflare Pages account with one command. This is a different model from a traditional BI tool where dashboards live inside the vendor's UI. Here the dashboard is generated and deployed to infrastructure you control. The README describes it as a browser-side app, so rendering happens client-side, which is worth testing with very large result sets.

A Real Alternative: A Bare Semantic Layer or a Raw LLM Agent

The README's own comparison table gives the alternatives. A raw LLM agent writes SQL but is often wrong and knows nothing about business definitions. A traditional BI tool can generate dashboards but requires manual work and does not work through your own agents. A bare semantic layer, like a pure MDL store, gives you definitions but not non-schema knowledge or agent-driven deployment. WrenAI sits in the middle: it adds an AI context layer on top of the semantic layer, and it adds deployment. The difference is not just feature count. A bare semantic layer is a passive store; WrenAI is an active engine that validates plans and returns structured errors. If you already have a semantic layer, the README says Wren sits on your existing stack, including existing semantic models, warehouses and transformation pipelines.

Maintenance and Upgrade Cost: What the Repo Layout Tells You

The repository holds several components side by side, including core/, sdk/ and skills/, and releases are tagged per component, such as wren and wren-core-py, so check which component a release applies to. The README states that workflow guides inside the CLI always match the installed version, which helps with documentation drift. The release cadence is active, with wren v0.17.1 on 2026-10-30, wren v0.17.0 three days earlier, and wren-core-py v0.8.2 on 2026-10-23. The project is not archived and the default branch is main. For an open-source project, the cost of upgrading depends on how much you customize the semantic layer. Since definitions live in Git, you can diff changes across versions, which is an advantage over a UI-driven tool.

The Verdict: Governed Context Is the Product, Not the SQL

WrenAI is not just another text-to-SQL wrapper. The core value proposition is that business context becomes a versionable, evidence-linked asset. The mechanisms, MDL planning, dry-plan validation, structured errors, and memory, are all in service of that. The limitations are real: an open-core boundary to check and a dependency on the agent ecosystem to drive the workflow. If you are a data engineer who wants to keep control of definitions and let agents do the heavy lifting, this is a serious candidate. If you need a team-wide deployment, Git Sync targets Wren Cloud or a self-hosted installation. The project is worth a proof of concept with your own warehouse, but only after you confirm your data source is in the 22+ list and you can live with the open-core boundary.

Editorial conclusion

Adopt WrenAI if you run AI agents against a warehouse and need business definitions, approved joins, and memory to live outside prompts, in versionable files. Skip it if you only need a quick chart from a CSV or you are comfortable letting an agent guess at SQL without guardrails. Before committing, verify that your required data source is in the 22+ list and check the open-core page for which features sit outside the Apache-2.0 core. Then test the CLI's dry-plan validation with your own schema to see if the structured errors match your team's workflow.

Frequently asked questions

Official sources

1. Canner/WrenAI on GitHub
2. Issues
3. Project website
4. README
5. Releases