Aix-DB: A LangGraph and MCP Data Assistant for Text2SQL and ChatBI

What Aix-DB solves, and for whom

The gap Aix-DB targets is the distance between a business question typed in plain language and a chart a non-engineer can read. The README describes the project as an intelligent data analysis system built on large language models and RAG, implementing conversational data analysis (ChatBI) for data extraction and visualization. That is the pitch: ask in natural language, get SQL, get results, get a chart.

The audience is narrower than the pitch. The supported data source list is MySQL, PostgreSQL, Oracle, SQL Server, ClickHouse, Dameng DM, Apache Doris, StarRocks, plus CSV and Excel. If your data lives in one of those, the project is aimed at you. If it lives in Snowflake, BigQuery or Databricks, the README does not claim support, and the repository topics do not suggest it either.

There is a second audience the README addresses explicitly: people who want agent orchestration rather than a chat box. The core capability list includes MCP multi-agent and Skill mode, and the description frames the project as LangChain/LangGraph plus an MCP Skills multi-agent collaboration architecture. That positions Aix-DB as a reference implementation of agentic data analysis, not only an end-user tool.

The six-stage pipeline from question to chart

The README documents the data-question flow as six numbered steps, and the sequence is worth reading closely because it explains where the project spends its complexity.

Step one is user input in natural language. Step two is LLM intent understanding, where the model parses intent and extracts entities and query conditions. Step three is RAG knowledge retrieval: embedding plus BM25 hybrid retrieval, combined with a Neo4j graph to fetch relevant table structures and business knowledge. Step four is SQL generation through a Text2SQL engine with syntax validation and optimization. Step five executes the SQL against the target data source. Step six generates ECharts or AntV charts.

The Neo4j step is the interesting design choice. Table schemas and business context are stored as a graph rather than as flat documents, which lets the retrieval step pull related tables and not just similar text chunks. That is a real architectural commitment: it means a Neo4j instance is part of the intended deployment, and the quality of the graph determines the quality of the generated SQL. The README does not describe how the graph is populated or kept in sync with schema changes.

The stack underneath is layered: Vue 3 and TypeScript in the front end with ECharts and AntV, a Sanic async API gateway with RESTful endpoints and JWT authentication, an intelligence layer holding the LLM service, Text2SQL agent, RAG engine and MCP multi-agent collaboration, and a storage layer spanning relational, vector, graph and file stores. pyproject.toml pins sanic>=25.0.0,<25.4.0, langchain>=1.2.7, langgraph>=1.0.7, langchain-mcp-adapters>=0.1.9, mcp>=1.12.2, py2neo, langchain-chroma and rank-bm25, which matches the described architecture.

Installing Aix-DB with Docker and running a first query

The README recommends Docker deployment, and the command it gives is a single docker run with environment variables and volume mounts. The image reference in the README is truncated mid-tag, so check README_en.md or the releases page for the full tag before running it. The Makefile names the version as 1.2.4, matching the latest release v1.2.4 from 2026-04-11.

The published form of the command looks like this, with the image name completed from the Makefile's VERSION value:

docker run -d \
  --name aix-db \
  --restart unless-stopped \
  -e TZ=Asia/Shanghai \
  -e SERVER_HOST=0.0.0.0 \
  -e SERVER_PORT=8088 \
  -e SERVER_WORKERS=2 \
  -e LLM_MAX_TOKENS=65536 \
  -p 18080:80 \
  -p 18088:8088 \
  -p 15432:5432 \
  -p 9000:9000 \
  -p 9001:9001 \
  apconw/aix-db:1.2.4

What the reader should notice is how much the container carries. Port 18080 maps to the web interface on port 80, 18088 maps to the Sanic API on 8088, 15432 maps to a PostgreSQL instance on 5432, and 9000 and 9001 map to MinIO. The README's full command also mounts ./volume/pg_data, ./volume/minio/data and five log directories, and adds host.docker.internal:host-gateway so the container can reach services on the host. That host mapping matters if your source database runs on the same machine.

The README also shows Langfuse tracing variables set to disabled by default:

-e LANGFUSE_TRACING_ENABLED=false \
-e LANGFUSE_SECRET_KEY= \
-e LANGFUSE_PUBLIC_KEY= \
-e LANGFUSE_BASE_URL= \

Leave them disabled unless you already run a Langfuse instance; the README does not explain what the empty keys do when tracing is on.

If you prefer to build locally, the Makefile splits the image into an application image and a base image, with build-base, build-base-cache, push-base and push-base-aliyun targets. The base image is meant to be rebuilt only when pyproject.toml, uv.lock, package.json or pnpm-lock.yaml change. The Python requirement is >=3.11,<3.12, so a local source install is pinned to a single minor version.

Where Aix-DB gets in your way

The first limitation is the licence. The repository has a LICENSE file and the README renders a licence badge pointing at it, but the licence identifier is not stated anywhere in the repository files or the README. For a tool that connects to production databases and reads table schemas, an unstated licence is a blocker before procurement, not a detail to resolve later.

The second is the bundled stack. The recommended deployment runs PostgreSQL, MinIO and Nginx inside the same container as the application, exposed on 15432, 9000 and 9001. On a laptop that is convenient. In an environment with an existing managed Postgres and an existing object store, you are running duplicates, and the README does not document a mode that points Aix-DB at external instances instead.

The third is the Neo4j dependency in the retrieval path. The architecture description says RAG combines embedding and BM25 retrieval with a Neo4j graph for table structures and business knowledge. If the graph is empty or stale, the retrieval step degrades, and the README does not document how the graph is built or refreshed. A Text2SQL system that silently loses schema context produces plausible SQL against the wrong tables, which is worse than an error.

The fourth is documentation asymmetry. The README is in Simplified Chinese with an English translation at README_en.md, and the Chinese README is truncated before the end of the docker command. There is a SECURITY.md and a docs/ directory with mkdocs configuration in pyproject.toml, but nothing in the README describes rollback, backup, or what happens to the bundled Postgres volume on upgrade.

Aix-DB against DB-GPT and Wren AI

The obvious comparison is DB-GPT, which people search for alongside Aix-DB. Both are open source, both do Text2SQL over relational databases, and both are self-hosted. The difference in approach is the orchestration layer. Aix-DB is built on LangChain and LangGraph with an MCP Skills multi-agent architecture, and the README's core capability list includes MCP multi-agent and Skill mode as first-class features. That makes Aix-DB a better fit if your interest is in composing agents and skills over data, or if you already have MCP servers you want to reuse, since pyproject.toml depends on mcp and langchain-mcp-adapters.

Wren AI takes a different route. Its approach centers on a semantic layer that defines models and metrics, so the language model translates questions into queries against defined semantics rather than inferring meaning from raw schema. Aix-DB's retrieval path instead combines embedding and BM25 search with a Neo4j graph of table structures and business knowledge. Both try to solve the same problem, grounding SQL generation in context, but a semantic layer is explicit and version-controlled while a retrieval graph is inferred and needs to be maintained.

If your organization already has dbt models or a metrics layer, Wren AI's direction will feel closer to what you have. If you want a LangGraph-native multi-agent system you can extend with your own MCP skills, Aix-DB's structure is the closer match. Neither choice removes the need to verify how each tool handles schema changes.

Maintenance, release cadence and upgrade cost

The last push to the default branch was on 2026-08-30, and the repository is not archived. The most recent release is v1.2.4 from 2026-04-11, preceded by v1.2.3 on 2026-02-10 and v1.2.2 on 2026-01-30. So the release cadence over the visible window is roughly one release every six to eight weeks, with commits continuing after the last tagged release.

Upgrade cost depends on which layer changed. The Makefile separates the base image from the application image and instructs that the base image be rebuilt only when pyproject.toml, uv.lock, package.json or pnpm-lock.yaml change. That is a sensible split: dependency-only upgrades are rare and expensive, application upgrades are frequent and cheap. If you build your own images from this Makefile, you inherit that split. If you pull apconw/aix-db:1.2.4 directly, you inherit whatever the maintainer published.

The awkward part is persistence. The README's docker run mounts ./volume/pg_data into /var/lib/postgresql/data and ./volume/minio/data into /data. Those volumes hold the bundled Postgres and MinIO state, which is where Aix-DB's own metadata, conversation history and uploaded files live. The README does not document a migration step between versions, so the safe assumption is that you back up those two directories before changing the image tag. Nothing in the README describes a downgrade path.

On licence: the repository includes a LICENSE file and the README shows a licence badge, but no identifier appears in the README or the repository files. Treat the licence as unverified until you read the file itself. This is not legal advice; it is a statement that the public documentation is silent.

Editorial conclusion

Aix-DB suits teams that already run MySQL, PostgreSQL, Oracle, SQL Server, ClickHouse, Doris or StarRocks and want a self-hosted conversational layer over them without writing their own Text2SQL pipeline. Skip it if you need a documented licence before procurement, if you cannot run a container that bundles PostgreSQL, MinIO and Nginx, or if your warehouse is not on the supported list. Verify first: the LICENSE file contents, the full docker run command in README_en.md, and whether the version tag you pull matches v1.2.4 in the Makefile.

Frequently asked questions

Official sources

1. apconw/Aix-DB on GitHub
2. Issues
3. README
4. Releases