How to Set Up Wren AI for Natural Language SQL

Wren AI is an open-source text-to-SQL platform that lets you ask data questions in plain English and receive accurate SQL in return. It supports more than 12 data sources and works with OpenAI, Anthropic Claude, Google Gemini, or a locally hosted Ollama model. The key differentiator is a semantic layer you configure once: define what your tables mean, how they relate to each other, and what ambiguous column names actually represent, and the LLM has accurate context for every query that follows. Setup takes about 30 minutes for a small schema.

What Wren AI Does and Why the Semantic Layer Matters

Most text-to-SQL tools send your raw schema to an LLM and rely on it to infer context from column names. A column named ord_amt gives the model little to work with. A semantic label of "order amount in USD, net of refunds and shipping" tells it exactly what to do with that value.

Wren AI stores this context in a structured semantic layer before any query runs. You define table relationships (which columns join to which), column descriptions, and named metrics like revenue or monthly active users. Every query then draws on that layer instead of guessing.

This approach shows up in results. The Wren AI team reports that schemas with full relationship definitions and column descriptions consistently outperform bare-schema configurations on multi-table queries. Wren AI has reached more than 13,000 GitHub stars and 10,000 active users as of early 2026, with new integrations for dbt and Databricks added over the past year.

Prerequisites

Before starting:

• Docker Desktop installed and running
• An API key from OpenAI, Anthropic, Google Gemini, or a local Ollama instance
• Read-level access to the database you want to query
• Your database hostname, port, and credentials

A laptop with 8 GB of RAM handles Wren AI comfortably on schemas under 50 tables. You do not need a separate server for initial testing.

Step 1: Install Wren AI with Docker

The recommended installation path is Docker Compose, which pulls all required services in one command.

Clone the repository:

git clone https://github.com/Canner/WrenAI.git
cd WrenAI

Copy the sample environment file:

cp .env.example .env

Open .env and set your LLM provider key:

OPENAI_API_KEY=your_key_here

For Claude, replace that line with:

ANTHROPIC_API_KEY=your_key_here

Start the stack:

docker compose up -d

The first pull downloads around 2 GB of images and takes several minutes depending on your connection speed. Once all containers are running, the Wren AI interface is available at http://localhost:3000.

Step 2: Connect Your Data Source

In the interface, go to Settings > Data Sources and click Add Data Source.

Select your database type. For PostgreSQL the required fields are hostname, port (default 5432), database name, and credentials. For BigQuery, upload a service account JSON file with roles/bigquery.dataViewer and roles/bigquery.jobUser permissions.

After saving, Wren AI tests the connection and loads your schema. Schemas with more than 100 tables can take 30 to 60 seconds to finish indexing.

Wren AI supports PostgreSQL, MySQL, BigQuery, Snowflake, DuckDB, SQLite, ClickHouse, Oracle, SQL Server, Redshift, Trino, and Presto. If your data lives in flat files rather than a live database, you can load a CSV directly through the DuckDB connector.

Step 3: Select Tables and Define Relationships

After connecting, Wren AI shows all tables in the schema. Select only the tables relevant to your analysis. Adding tables you will never query increases token usage per request and can reduce accuracy on multi-table joins.

For each pair of related tables, define the join in Modeling > Relationships. Click Add Relationship and specify:

• Source table and column
• Target table and column
• Relationship type: one-to-one, one-to-many, or many-to-many

A standard e-commerce example: orders.customer_id has a many-to-one relationship with customers.id.

Skipping this step is the most common reason multi-table questions return wrong results. If a query joins two tables incorrectly or fails entirely, the missing relationship is usually the cause.

Step 4: Add Column and Table Descriptions

This step is optional but has the largest effect on query accuracy. Navigate to Modeling > Tables, select a table, and click any column to add a plain-English description.

Useful description patterns:

• revenue: "Total transaction value in USD. Net of refunds. Does not include shipping fees."
• status: "Order status. Values: pending, processing, shipped, delivered, cancelled."
• user_id: "Unique identifier from the authentication system. Foreign key to the users table."

A practical approach is to add descriptions to the 10 columns you expect to query most before testing. Wren AI's documentation notes that schemas with complete descriptions reach consistent accuracy from the first query; sparse schemas often require two or three rephrasing attempts before the model converges on the right result.

Step 5: Ask Your First Question

With the data connected and semantic layer configured, go to the Chat view and type a question:

• "How many orders did we receive last week, broken down by status?"
• "What are the top 10 customers by total revenue this year?"
• "Show me monthly active users for the past 12 months."

Wren AI generates the SQL, displays it for review, runs it, and returns results as a table or chart. You can click Adjust Answer to correct any mismatch: describe what the result got wrong and Wren AI regenerates.

For complex analytical questions that require multiple steps, the tool handles many common patterns but may need iteration. Questions involving cohort retention windows, arbitrary date bucketing, or cross-schema joins are the most likely to require manual SQL review.

Using the dbt Integration

If your team already uses dbt Core or dbt Cloud, you can skip manual schema configuration entirely. Wren AI reads your compiled dbt manifest file and imports all metrics, dimensions, and relationships already defined in your YAML.

Connect via Settings > Integrations > dbt. You will need either the local path to your compiled manifest or a dbt Cloud API token.

Teams with an active dbt project can reach the question-asking stage in under five minutes using this path. The dbt integration is the fastest route from installation to working queries for organizations already invested in dbt.

What Wren AI Handles Less Well

Text-to-SQL tools have limits that are worth knowing before you rely on them for business-critical reports.

Multi-database joins, such as combining a Snowflake table with a live PostgreSQL source, are not supported in the current version. Analytical calculations that require intermediate aggregations, such as period-over-period retention or multi-step funnel analysis, often need manual SQL review before they are accurate. Wren AI also uses long polling rather than streaming for result delivery, which means there is a visible delay on queries that return large result sets.

For straightforward operational questions, routine monthly reporting, and exploratory slicing of existing data, Wren AI performs reliably once the semantic layer is properly configured.

If your team works primarily with exported CSV or Excel files rather than live database connections, VSLZ handles analysis from a direct file upload with no database configuration or Docker setup required.

Next Steps

Once the basic setup is running, two additions improve everyday use. First, add your most important business metrics as named calculations in the semantic layer so that "CAC" or "LTV" always resolves to the same formula regardless of who asks. Second, invite team members via Settings > Team so analysts and operations staff can ask questions without touching the configuration layer.

For teams that outgrow a self-hosted instance, Wren AI offers a cloud-hosted version with managed infrastructure and access controls. The open-source community releases updates frequently, and the GitHub repository tracks active development with new data source connectors and LLM integrations added on a regular cadence.