wrenai
Wren AI CLI and Python SDK — semantic SQL layer for 20+ data sources.
Translate natural SQL queries through an MDL (Modeling Definition Language) semantic layer and execute them against your database. Powered by Apache DataFusion.
Installation
pip install wrenai # Core (DuckDB included)
pip install 'wrenai[postgres]' # PostgreSQL
pip install 'wrenai[mysql]' # MySQL
pip install 'wrenai[bigquery]' # BigQuery
pip install 'wrenai[snowflake]' # Snowflake
pip install 'wrenai[clickhouse]' # ClickHouse
pip install 'wrenai[trino]' # Trino
pip install 'wrenai[mssql]' # SQL Server
pip install 'wrenai[databricks]' # Databricks
pip install 'wrenai[redshift]' # Redshift
pip install 'wrenai[spark]' # Spark
pip install 'wrenai[athena]' # Athena
pip install 'wrenai[oracle]' # Oracle
pip install 'wrenai[memory]' # Schema & query memory (LanceDB)
pip install 'wrenai[memory-onnx]' # Same, torch-free (onnxruntime instead of PyTorch)
pip install 'wrenai[ui]' # Browser-based profile form (starlette + uvicorn)
pip install 'wrenai[main]' # memory + interactive prompts + ui
pip install 'wrenai[all]' # All connectors + main
Requires Python 3.11+.
Quick start
1. Initialize a project — scaffolds a YAML-based MDL project:
mkdir my-project && cd my-project
wren context init
This creates wren_project.yml, models/, and views/. Edit wren_project.yml to set your data_source and add models under models/:
# wren_project.yml
schema_version: 2
name: my_project
catalog: wren
schema: public
data_source: postgres
# models/orders/metadata.yml
name: orders
table_reference:
schema: mydb
table: orders
columns:
- name: order_id
type: integer
- name: customer_id
type: integer
- name: total
type: double
- name: status
type: varchar
primary_key: order_id
Already have an MDL JSON? Import it directly:
wren context init --from-mdl path/to/mdl.json
2. Configure a connection profile:
# Browser form (recommended, requires wrenai[ui])
wren profile add my-db --ui
# Interactive terminal prompts
wren profile add my-db --interactive
# Import from an existing connection file
wren profile add my-db --from-file connection_info.json
3. Build the manifest:
wren context build
This compiles YAML files into target/mdl.json. The CLI auto-discovers this file when you run queries from within the project directory.
4. Run queries:
wren --sql 'SELECT order_id FROM "orders" LIMIT 10'
wren walks up from the current directory to find wren_project.yml and uses target/mdl.json. You can also pass --mdl path/to/mdl.json explicitly.
For the full CLI reference and per-datasource connection field reference, see docs/cli.md and docs/connections.md.
4a. (Optional) Aggregation queries with cubes — define cubes under cubes/,
then query them with a structured input instead of writing GROUP BY SQL by hand:
wren cube list
wren cube describe revenue
wren cube query --cube revenue --measures total --time-dimension "order_date:month"
The translator produces DATE_TRUNC / GROUP BY / WHERE clauses for you and
runs them through the same engine path as wren --sql. See the
Cube guide for full YAML structure
and the CLI reference for all
flags.
5. (Optional) Configure security policy — create ~/.wren/config.json:
{
"strict_mode": true,
"denied_functions": ["pg_read_file", "dblink", "lo_import"]
}
| Key | Default | Description |
|---|---|---|
strict_mode |
false |
When true, every table in a query must be defined in the MDL. Queries referencing undeclared tables are rejected before execution. |
denied_functions |
[] |
List of function names (case-insensitive) that are forbidden in queries. |
6. (Optional) Index schema for semantic search (requires wrenai[memory],
or wrenai[memory-onnx] for a torch-free install):
wren memory index # index MDL schema
wren memory fetch -q "customer order price" # fetch relevant schema context
wren memory store --nl "top customers" --sql "SELECT ..." # store NL→SQL pair
wren memory recall -q "best customers" # retrieve similar past queries
wren memory watch # auto-reindex on schema/query changes
memory-onnx runs the same weights through onnxruntime instead of PyTorch, so
it produces the same vectors and existing indexes stay valid -- it is a much
smaller install, not a different index. When both extras are present, onnx is
used; set WREN_EMBEDDING_BACKEND=sentence-transformers to override, and
wren memory status reports which one is live.
7. (Optional) Build a shareable GenBI app — turn the context layer into a
browser-side dashboard (powered by wren-core-wasm) and deploy it to Vercel or
Cloudflare Pages. The CLI owns the build instruction + deterministic state; an
agent authors the app from it:
wren genbi build sales --prompt "orders dashboard" --data-mode snapshot # print build instruction
# agent authors apps/sales/ from the instruction (mdl.json + data/*.parquet)
wren genbi register sales --data-mode snapshot # record the app
wren genbi verify sales # preflight (files, MDL, data, secret scan)
wren genbi open sales # local preview
wren genbi deploy sales --provider vercel # ship a shareable URL (preview; --prod for production)
Tokens come from the env / .env (VERCEL_TOKEN / CLOUDFLARE_API_TOKEN),
never CLI flags; Cloudflare needs wrangler installed. See the
GenBI guide and the
CLI reference.
8. (Optional) Serve an MCP server — expose the project's query, schema, and knowledge tools to Claude Desktop/Code, Cursor, or any MCP client. Runs in-process against the compiled MDL — no ibis-server, no separate service:
wren serve mcp # stdio (default) — client spawns this as a child process
wren serve mcp --transport http --port 8080 # local Streamable HTTP for other clients
Requires wren context build to have already run and the mcp extra:
pip install 'wrenai[mcp]'. See the
MCP guide and the
CLI reference for
the full tool/resource list and client wiring.
Connection profiles
Profiles let you store named connection configurations in ~/.wren/profiles.yml and switch between them easily — useful when working across multiple databases or environments.
# Add a profile (browser form, interactive prompts, or file import)
wren profile add prod --ui # opens http://localhost:<port>
wren profile add staging --interactive # terminal prompts
wren profile add local --from-file conn.json # import existing file
# List and switch profiles
wren profile list # * marks the active profile
wren profile switch prod
# Inspect a profile (sensitive fields masked)
wren profile debug prod
# Remove a profile
wren profile rm old-profile --force
The --ui flag opens a browser-based form that auto-derives fields from each datasource's schema — including file upload for BigQuery credentials, variant selection for Databricks/Redshift, and sensible defaults for all 20+ supported sources. Requires pip install 'wrenai[ui]'.
Once a profile is active, wren uses it automatically:
wren profile switch prod
wren --sql 'SELECT COUNT(*) FROM "orders"' # connects using prod profile
Python SDK
import base64, orjson
from wren import WrenEngine, DataSource
manifest = { ... } # your MDL dict
manifest_str = base64.b64encode(orjson.dumps(manifest)).decode()
with WrenEngine(manifest_str, DataSource.mysql, {"host": "...", ...}) as engine:
result = engine.query('SELECT * FROM "orders" LIMIT 10')
print(result.to_pandas())
Development
Prerequisites: just and uv. (Rust + Cargo are only needed for the
local-engine recipes below.)
Standard setup (no Rust toolchain)
just install # uv sync — pulls the prebuilt wren-core-py wheel from PyPI
just lint # Ruff format check + lint
just format # Auto-fix
just install is a plain uv sync: it installs the locked prebuilt wren-core-py engine binding and the development tools from uv's default dev dependency group. No compilation required. This is enough for all Python-side development. Use just install-extra <extra> or just install-all for data-source extras.
Engine development (changing the Rust core)
Only needed when you modify ../wren-core-py (or ../wren-core) and want
core/wren to run against your local build. Requires Rust + Cargo.
just install-local # uv sync + build the local wheel + overlay it into .venv
just use-local-core # rebuild + re-overlay after each subsequent Rust change
The run recipes (just test*, just lint, just dev) use uv run --no-sync,
so they never revert a locally overlaid engine back to the lockfile version. If
dependencies change, re-run an install recipe first.
| Command | What it runs | Docker needed |
|---|---|---|
just test-unit |
Unit tests (engine, CTE rewriter, field registry, profiles) | No |
just test-duckdb |
DuckDB connector tests | No |
just test-postgres |
PostgreSQL connector tests | Yes |
just test-mysql |
MySQL connector tests | Yes |
just test-starrocks |
StarRocks connector tests (needs the mysql extra) |
Yes |
just test |
All tests | Yes |
Profile web tests (test_profile_web.py) require wrenai[ui]:
uv sync --extra ui
uv run --no-sync pytest tests/test_profile_web.py -v
Publishing
./scripts/publish.sh # Build + publish to PyPI
./scripts/publish.sh --test # Build + publish to TestPyPI
./scripts/publish.sh --build # Build only
Package rename: wren-engine → wrenai
Starting with the 0.7.0 release, this PyPI distribution is renamed from
wren-engine to
wrenai to align with the Wren AI
brand. The legacy wren-engine project on PyPI is frozen at 0.6.x and
will not receive further updates.
What stays the same
- The Python import path:
import wren(and submodules underwren.*) - The
wrenCLI entrypoint and every subcommand (wren query,wren context,wren profile,wren memory, …) - All extras (
postgres,mysql,bigquery, …,memory,ui,main,all) - Configuration files under
~/.wren/(profiles, memory, config)
Only the name you type after pip install is different.
Migration
pip uninstall wren-engine
pip install wrenai # or: pip install "wrenai[<extras>]"
wren --version # should print: wrenai X.Y.Z
If your project pinned wren-engine in a requirements.txt,
pyproject.toml, or lockfile, replace it with wrenai and re-lock.
License
Apache-2.0
Metadata
Release files for wrenai 0.17.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| wrenai-0.17.0.tar.gz | 804.4 kB | Without provenance | Details for wrenai-0.17.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| wrenai-0.17.0-py3-none-any.whl | Python 3 | none | any | Details for wrenai-0.17.0-py3-none-any.whl |
Total release size: 1.2 MB
Release files / wrenai-0.17.0.tar.gz
| Download URL | wrenai-0.17.0.tar.gz |
|---|---|
| Size | 804.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
72bbb251969a27cccdb1d0ecacdf92929fcb162cab45ac7bdc205ac23c1ef95d
|
|
BLAKE2b-256 checksum How to use checksums |
5969b30a575404c4bc710cecd833855efafb32cf9d6794da16bc81453e46cccd
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Release files / wrenai-0.17.0-py3-none-any.whl
| Download URL | wrenai-0.17.0-py3-none-any.whl |
|---|---|
| Size | 372.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
08ae60112cd83379e0bd15adc6aeb928b3a16abeb263c23ba5ac616b8ccbc345
|
|
BLAKE2b-256 checksum How to use checksums |
3821820153303f9dcd05b1fc2cc831d6df8044431f6037dc3a515fd017123a82
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Security for wrenai 0.17.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.