Giving an AI agent raw access to your production database is like handing an intern the master key to the vault. You get speed, but you lose control. Yasin Yaman, a data consultant working with on-premises infrastructure, released Truejoin to solve this exact problem. The open-source Apache 2.0 gateway allows AI agents to query live databases without needing their own database accounts, effectively acting as a secure, auditable intermediary.
The Three Pillars of Truejoin
Truejoin addresses three critical failures in standard text-to-SQL implementations: excessive data visibility, inaccurate joins, and missing audit trails. The tool connects to PostgreSQL, MySQL/MariaDB, SQL Server, and Oracle, serving data via three interfaces: MCP (Model Context Protocol) with 18 tools, a REST API with typed OpenAPI schemas, and analytical SQL via in-memory DuckDB. Crucially, every query runs under the caller's specific row rules and column masks, generating a single audit event that records who asked, which tables were touched, and which columns were masked, without storing the raw SQL.
Query Rewriting Over Result Filtering
The core innovation is proactive query rewriting. Instead of filtering results after the factβwhich can leak data through aggregates or aliasesβTruejoin rewrites the query before execution. It replaces each named table with a subquery that enforces the caller's row conditions and masks. This ensures that aliases, joins, CTEs, and aggregates only see the restricted view. The system fails closed, refusing queries that cannot be wrapped, and applies the same logic to model-written SQL as it does to human-written queries.
Benchmarking Against Model Hallucinations
Yaman benchmarked the approach using a banking-shaped schema and the qwen2.5-coder:7b model. The results highlight the danger of letting models write SQL from raw DDL. When models wrote SQL from the DDL, they achieved only 8 correct answers out of 16 held-out questions, with a 31.2% hallucination rate. Using an approved catalog dropped hallucinations to 18.8%. However, the 'approved terms' approach, which uses no model at query time for straightforward questions, achieved 12 correct answers with 0% hallucination. Only questions the vocabulary couldn't parse were sent to the model, and those answers were explicitly marked as model-written.
Key Takeaways
- Truejoin is an open-source (Apache 2.0) data gateway that supports PostgreSQL, MySQL, SQL Server, and Oracle.
- It uses query rewriting to enforce row-level security and column masking, preventing data leaks through aggregates or aliases.
- The tool offers MCP, REST, and DuckDB analytical interfaces, all running from a single Python process.
- Benchmarks show that using an approved semantic catalog significantly reduces hallucinations compared to raw DDL prompts.
- Version 1.0.0 is currently in development and available via source, not yet on PyPI.
The Bottom Line
This is the kind of infrastructure glue we need. Stop giving agents root access; give them a governed lens. Truejoin's approach to semantic catalogs over raw DDL is a smart, practical step toward trustworthy AI agents.