Aix-DB: a LangGraph and MCP stack for natural-language querying of eight database engines

The gap Aix-DB fills between a BI dashboard and a raw SQL prompt

Most text-to-SQL demos stop at a generated statement. Aix-DB is aimed at the next four steps: retrieving the right schema context, validating the SQL, running it against a real engine, and drawing the result. The target user is a team that already has a relational or OLAP warehouse and wants a conversational layer on top of it without sending schema metadata to a third-party service. The README frames this as ChatBI, conversational data analysis, and lists the core surface as intelligent Q&A, data Q&A (Text2SQL), table Q&A, deep questioning, visualisation, MCP multi-agent mode and a Skill mode. The supported engine list is the most concrete part of the pitch: MySQL, PostgreSQL, Oracle, SQL Server, ClickHouse, DM (达梦), Apache Doris, StarRocks, plus CSV and Excel files. That spread matters because most open text-to-SQL projects assume PostgreSQL or SQLite and leave dialect differences to the user. Aix-DB claims the dialect handling is internal. The README does not say how each dialect is handled, so treat that claim as unverified until you read the connector code.

The six-stage pipeline the README documents

The README publishes a numbered flow with a module for each step, which is more than most projects of this kind offer. Step one is natural-language input. Step two is LLM intent parsing, which extracts entities and query conditions. Step three is the retrieval stage: a hybrid of embedding search and BM25, combined with a Neo4j graph that supplies table structures and business knowledge. Step four is SQL generation with syntax validation and optimisation. Step five executes against the target data source. Step six produces ECharts or AntV charts. The Neo4j component is the design decision worth noting. Business knowledge (metric definitions, join paths, column aliases) lives in a graph rather than in a flat vector store, which means retrieval can follow relationships instead of relying on cosine similarity alone. The cost is operational: you now run a graph database alongside your warehouse. The README does not describe how the graph is populated, whether ingestion is automatic from schema introspection or manual, or how the graph is kept in sync when a table is altered. That is the largest undocumented area in the pipeline.

Layered architecture: Vue 3, Sanic, LangGraph, and four storage classes

The architecture section splits into four layers. The front end is Vue 3 with TypeScript, ECharts and AntV. The API gateway is Sanic, an async Python framework, exposing REST endpoints with JWT authentication. The intelligence layer holds the LLM service, the Text2SQL agent, the RAG retrieval engine and the MCP multi-agent coordination. The storage layer covers relational databases, vector databases, graph databases and file storage. The repository's primary language is listed as JavaScript, which is consistent with a Vue front end carrying most of the file count, but the Sanic gateway and the LangGraph agents are Python. If you plan to contribute, expect to work across both. The MCP Skills framing means the agent capabilities are packaged as discrete skills rather than as one monolithic prompt chain, and the README shows a separate Skill mode alongside a standard mode in its demo table. What the README does not specify is the transport used between the MCP components, nor whether skills run in-process or as separate services. Verify that before you plan a deployment topology.

Getting it running: the documented docker run command and its flags

The README recommends Docker and gives one command. It starts a container named aix-db with restart unless-stopped, sets TZ to Asia/Shanghai, SERVER_HOST to 0.0.0.0, SERVER_PORT to 8088 and SERVER_WORKERS to 2. It disables Langfuse tracing with LANGFUSE_TRACING_ENABLED=false and leaves LANGFUSE_SECRET_KEY, LANGFUSE_PUBLIC_KEY and LANGFUSE_BASE_URL empty, which tells you tracing is opt-in and off by default. VITE_ENABLE_PAGE_AGENT is set to false and LLM_MAX_TOKENS to 65536. Five ports are published: 18080 to 80 for the web interface, 18088 to 8088 for the API, 15432 to 5432 for PostgreSQL, and 9000 and 9001 for MinIO. Six volumes are mounted from a relative ./volume directory covering pg_data, minio/data, and logs for supervisor, nginx, aix-db, minio and postgresql. The --add-host host.docker.internal:host-gateway flag lets the container reach a database running on the host. Note that the image reference in the supplied README is truncated mid-string, so copy the full tag from the repository rather than from this article. Also note that the command does not set a database password or an LLM API key, which means first-run configuration happens through the web interface or through environment variables the README does not list.

Where the approach breaks: schema drift, dialect edge cases and the licence gap

Three limitations stand out from the material. First, the retrieval layer depends on a Neo4j graph that the README never explains how to populate or refresh. If the graph is built once and a column is renamed, the hybrid retrieval will keep returning stale context and the generated SQL will reference a column that no longer exists. There is no described invalidation mechanism. Second, dialect coverage is asserted but not evidenced. Oracle, SQL Server and DM have materially different pagination, date arithmetic and identifier quoting rules, and the README gives no statement about how the Text2SQL engine selects the right dialect or how it validates a statement before execution. Third, and most practically, the licence is unknown in the supplied material. The README renders a licence badge that links to a LICENSE file on the master branch, but the licence identifier is not present in the repository metadata I was given. For a component that will sit between your users and your production warehouse, that is a blocker to resolve before adoption, not after. The README also does not describe a read-only enforcement mode for the generated SQL, which is the control most teams will ask about first.

How Aix-DB differs from Vanna and from hosted text-to-SQL APIs

Vanna is the closest open comparison in this space. Its approach is training-centric: you feed it DDL, documentation and example question-SQL pairs, it stores them in a vector store, and retrieval is similarity search over that flat index. Aix-DB instead keeps business knowledge in a Neo4j graph and combines graph traversal with an embedding plus BM25 hybrid search. The practical difference is that Vanna's context is a bag of similar documents, while Aix-DB's context can be reached by following declared relationships between tables and metrics. That helps on joins across many tables, which is where flat retrieval usually fails. It costs you a graph database to run and a schema-to-graph mapping to maintain. Hosted text-to-SQL APIs are the other alternative, and the difference there is data residency: Aix-DB is self-hosted, so schema metadata and query results stay inside your network. The trade is that you own the LLM endpoint, the vector store, the graph store and the upgrades.

Release cadence, upgrade cost and what the licence question means for shipping

The release history shows v1.2.2 in late January 2026, v1.2.3 in February and v1.2.4 in April, with the last push to master in late August 2026. That is a steady minor-version cadence over roughly three months, which suggests active maintenance, though the gap between the April release and the August push is worth noting if you depend on tagged releases rather than master. Upgrade cost is dominated by the mounted volumes. The documented command persists PostgreSQL data under ./volume/pg_data and MinIO objects under ./volume/minio/data, so the application database and any uploaded CSV or Excel files survive a container replacement. The Neo4j graph is not among the mounted paths in the documented command, which raises the question of whether graph state is rebuilt on start or lost. Confirm that before you load business knowledge into it. On licensing: I cannot state the terms because the identifier is not in the material I have. If your organisation requires an approved licence before deployment, read the LICENSE file on the master branch first. This is a factual gap in the review, not legal advice, and it is the single item most likely to stop an adoption.

Editorial conclusion

Adopt Aix-DB if you already run one of the supported engines (MySQL, PostgreSQL, ClickHouse, Doris, StarRocks, Oracle, SQL Server, DM) and want a self-hosted ChatBI layer whose retrieval stage you can inspect, rather than a hosted text-to-SQL API. Do not adopt it if you need a stated licence before you ship, or if your warehouse is outside that engine list, since the README gives no plugin interface for adding one. Verify two things first: the contents of the LICENSE file on the master branch, and whether the pg_data, minio/data and logs volumes referenced in the documented docker run command survive an image upgrade, because the command as written mounts them from a relative ./volume path.

Official sources

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