The complete architectural journey: How PeopleWorksGPT transforms conversational questions into precise database queries across five different database engines
Databases speak SQL. Humans speak... well, human. PeopleWorksGPT is the universal translator that makes this conversation possible, natural, and incredibly powerful.
Unlike traditional query builders that require learning specific syntax or clicking through endless menus, PeopleWorksGPT understands questions like "Show me the top 10 customers by revenue this quarter" and instantly translates them into optimized SQL queries - regardless of whether you're using SQL Server, MySQL, PostgreSQL, Oracle, or SQLite.
Natural language is inherently ambiguous. "Last quarter" could mean many things. The system must understand context, intent, and business logic to generate the correct query.
The AI must know your database structure: which tables exist, how they relate, which columns contain what data, and how to join them properly to answer questions.
Different databases speak different SQL dialects. A query that works in SQL Server might fail in PostgreSQL. The system must adapt to each database's unique syntax.
Every natural language query goes through a sophisticated five-step process that ensures accuracy, security, and optimal performance.
| 01 |
Session Initialization & Context Setup
The system creates or retrieves a conversation session, loading the complete
database schema including table names, column definitions, data types, constraints,
and foreign key relationships. This context is essential for understanding what
data is available and how it's structured.
|
| 02 |
Intelligent Table Selection
Using AI reasoning, the system analyzes the question and identifies which tables
from the database schema are likely to contain relevant information. This critical
step reduces complexity and improves query accuracy by focusing only on pertinent data.
|
| 03 |
Schema Detail Retrieval
For the selected tables, the system retrieves complete CREATE TABLE scripts including
column definitions, data types, constraints, primary keys, and relationship information.
This provides the AI with the precise schema structure needed to generate accurate joins
and column references.
|
| 04 |
SQL Query Generation
The AI constructs a SQL query using the schema information and the natural language
question. It applies database-specific syntax rules, optimizes for performance, and
ensures the query only references valid tables and columns. Security filters prevent
INSERT, UPDATE, or DELETE operations.
|
| 05 |
Query Validation & Execution
The generated SQL is validated by the database provider, normalized for the specific
database engine, and executed with proper error handling. Results are returned as a
DbDataReader for efficient data streaming and presentation.
|
PeopleWorksGPT supports five different database engines through a sophisticated provider pattern that abstracts database-specific operations while maintaining optimal performance for each platform.
Defines the contract that all database providers must implement, ensuring consistent behavior across all database engines.
public interface IDatabaseGptProvider : IDisposable
{
string Name { get; }
string Language { get; }
Task<IEnumerable<string>> GetTablesAsync(
IEnumerable<string> includedTables,
IEnumerable<string> excludedTables,
CancellationToken cancellationToken = default
);
Task<string> GetCreateTablesScriptAsync(
IEnumerable<string> tables,
IEnumerable<string> excludedColumns,
CancellationToken cancellationToken = default
);
Task<string?> GetQueryHintsAsync(
CancellationToken cancellationToken = default
);
Task<string> NormalizeQueryAsync(
string query,
CancellationToken cancellationToken = default
);
Task<DbDataReader> ExecuteQueryAsync(
string query,
CancellationToken cancellationToken = default
);
}
Each database engine has its own provider implementation that handles dialect-specific SQL syntax, schema queries, and optimization strategies.
| Database | Provider Class | SQL Dialect | Key Features |
|---|---|---|---|
| SQL Server | SqlServerDatabaseGptProvider | T-SQL | 2008 R2+ compatibility, relationship detection |
| MySQL | MySqlDatabaseGptProvider | MySQL SQL | INFORMATION_SCHEMA queries, charset support |
| PostgreSQL | NpgsqlDatabaseGptProvider | PostgreSQL | Advanced types, schema namespaces |
| Oracle | OracleDatabaseGptProvider | PL/SQL | ALL_TAB_COLUMNS, sequence support |
| SQLite | SqliteDatabaseGptProvider | SQLite SQL | Lightweight, file-based, pragma queries |
Dependency injection makes it seamless to configure any database provider with just a few lines of code.
// SQL Server
services.AddDatabaseGpt(options =>
{
options.UseSqlServer(connectionString);
});
// MySQL
services.AddDatabaseGpt(options =>
{
options.UseMySql(connectionString);
});
// PostgreSQL
services.AddDatabaseGpt(options =>
{
options.UseNpgsql(connectionString);
});
User Question: "Show me the top 10 customers by total revenue this year, including their contact information and order count"
Database: Northwind Sample Database (SQL Server)
Available Tables: Customers, Orders, Order Details, Products, Employees
| ๐ |
User Input
|
|||||||||||||||||||||||||
| ๐ฏ |
AI Table Selection Result
The AI analyzes the question and identifies the necessary tables:
Why these tables?
|
|||||||||||||||||||||||||
| ๐ |
Schema Information Retrieved
|
|||||||||||||||||||||||||
| โก |
Generated SQL Query
Query Analysis:
|
|||||||||||||||||||||||||
| ๐ |
Query Results
|
|||||||||||||||||||||||||
The system maintains conversation context across multiple queries. If you ask "Show me customers" followed by "Filter those from Germany", it understands "those" refers to the previous customer query and builds upon it.
var conversationExists = await chatGptClient
.ConversationExistsAsync(sessionId, cancellationToken);
if (!conversationExists) {
// Initialize new session with schema
} else {
// Continue existing conversation
}
Built-in protection prevents malicious queries. Only SELECT statements are allowed - the system explicitly rejects INSERT, UPDATE, DELETE, DROP, or any other data modification commands.
if (query == "NONE") {
throw new InvalidSqlException(
$"The question '{question}' requires an INSERT, " +
"UPDATE or DELETE command, that isn't supported."
);
}
Administrators can include or exclude specific tables and columns, controlling what data users can access through natural language queries. Perfect for hiding sensitive information or focusing on specific datasets.
services.AddDatabaseGpt(options =>
{
options.UseSqlServer(connectionString);
options.IncludedTables = new[]
{
"dbo.Customers",
"dbo.Orders"
};
options.ExcludedColumns = new[]
{
"SSN",
"CreditCard"
};
});
Developers can hook into the query generation process at multiple points: when starting, when tables are identified, and when SQL is generated. This enables logging, auditing, custom validation, or query modification.
var options = new NaturalLanguageQueryOptions
{
OnStarting = async (sp) =>
{
var logger = sp.GetService<ILogger>();
logger.LogInformation("Query starting...");
},
OnCandidateTablesFound = async (args, sp) =>
{
Console.WriteLine($"Tables: {args.Tables}");
},
OnQueryGenerated = async (args, sp) =>
{
Console.WriteLine($"SQL: {args.Query}");
}
};
The system automatically discovers foreign key relationships between tables and includes this information in the AI context, enabling the generation of accurate JOIN statements without manual configuration.
### Key Relationships:
dbo.Orders (CustomerID) joined with
dbo.Customers (CustomerID)
dbo.OrderDetails (OrderID) joined with
dbo.Orders (OrderID)
dbo.OrderDetails (ProductID) joined with
dbo.Products (ProductID)
Built on Polly, the system implements retry policies, circuit breakers, and timeout handling to ensure reliability even when facing transient failures, database timeouts, or AI API issues.
private readonly ResiliencePipeline pipeline =
pipelineProvider.GetPipeline(
nameof(DatabaseGptClient)
);
await pipeline.ExecuteAsync(async ct =>
{
var tables = await GetTablesAsync(...);
var query = await GetQueryAsync(...);
return await provider.ExecuteQueryAsync(query);
}, cancellationToken);
Actual measurements from production workloads across different database engines and query complexities.
| Query Complexity | Tables Involved | AI Processing | DB Execution | Total Time |
|---|---|---|---|---|
| Simple (single table) | 1 | 2.1s | 0.05s | 2.15s |
| Moderate (2-3 joins) | 2-3 | 2.8s | 0.15s | 2.95s |
| Complex (4+ joins, aggregates) | 4-6 | 3.5s | 0.45s | 3.95s |
| Advanced (subqueries, CTEs) | 5-8 | 4.2s | 0.80s | 5.00s |
The same natural language question generates database-specific SQL optimized for each platform's unique syntax and capabilities.
"Show me the top 5 products by total sales, including product name and category"
| Database | Generated SQL |
|---|---|
| SQL Server |
|
| MySQL |
|
| PostgreSQL |
|
| Oracle |
|
| SQLite |
|
NoTableFoundException:
"No available information in the provided
tables can be useful for the question
'What is the weather today?'."
When the AI determines that none of the available database tables contain relevant information to answer the question, it gracefully fails with a clear explanation.
InvalidSqlException:
"The question 'Delete all old customers'
requires an INSERT, UPDATE or DELETE command,
that isn't supported."
Security protection prevents data modification commands, ensuring the system is strictly read-only for business intelligence and reporting purposes.
DatabaseGptException:
"An error occurred while executing the query.
See the inner exception for details."
Inner: SqlException
"Invalid column name 'CustomerNam'.
Did you mean 'CustomerName'?"
Database-specific errors are wrapped with context, preserving the original exception details for debugging while providing a consistent error handling experience.
// Automatic retry with exponential backoff
var pipeline = new ResiliencePipelineBuilder()
.AddRetry(new RetryStrategyOptions
{
MaxRetryAttempts = 3,
Delay = TimeSpan.FromSeconds(1),
BackoffType = DelayBackoffType.Exponential
})
.Build();
Network timeouts, temporary database unavailability, and AI API rate limits are handled automatically through intelligent retry mechanisms.
// Startup.cs / Program.cs
services.AddDatabaseGpt(options =>
{
options.UseSqlServer(Configuration.GetConnectionString("DefaultConnection"));
options.SystemMessage = "Consider fiscal year starts in July";
});
// Controller
[ApiController]
[Route("api/[controller]")]
public class QueryController : ControllerBase
{
private readonly IDatabaseGptClient _databaseGpt;
public QueryController(IDatabaseGptClient databaseGpt)
{
_databaseGpt = databaseGpt;
}
[HttpPost("ask")]
public async Task<IActionResult> Ask([FromBody] QueryRequest request)
{
var result = await _databaseGpt.ExecuteNaturalLanguageQueryAsync(
request.SessionId,
request.Question
);
var data = await ReadDataAsync(result.DataReader);
return Ok(new
{
query = result.Query,
data = data
});
}
}
AI-powered query optimization that analyzes execution plans and suggests index improvements or query rewrites for better performance.
Automatically suggest and generate appropriate chart types (bar, line, pie) based on query results and data characteristics.
Support queries that span multiple databases, automatically handling cross-database joins and data federation scenarios.
Automated generation of test queries based on schema, helping validate database structure and identify potential issues.
Interactive tutorials that teach SQL through natural language, showing how questions translate to queries with detailed explanations.
Accept questions in multiple human languages (Spanish, French, German, etc.) while generating correct SQL for any database engine.
PeopleWorksGPT demonstrates that the barrier between business users and their data doesn't have to be technical knowledge - it can be as simple as asking a question. By combining AI understanding with solid software engineering, we've created a system that makes databases accessible to everyone.
| Component | Technology | Purpose |
|---|---|---|
| Backend Framework | .NET 8 / C# 12 | High-performance, cross-platform application development |
| AI Integration |
Multi-Provider Support: โข Anthropic (Claude) โข OpenAI (GPT-4) โข Google (Gemini) โข Grok โข OpenRouter โข Groq |
Natural language understanding and SQL generation across multiple AI providers |
| Database Access | Dapper + ADO.NET | Fast, lightweight ORM with direct SQL execution |
| Resilience | Polly | Retry policies, circuit breakers, timeout handling |
| Dependency Injection | Microsoft.Extensions.DependencyInjection | Loose coupling, testability, provider registration |
| Database Providers |
Microsoft.Data.SqlClient MySql.Data Npgsql Oracle.ManagedDataAccess Microsoft.Data.Sqlite |
Native database connectivity for all supported engines |