Updated documentation to reflect the architectural changes:
- Changed all ai_* variables to genai-* variables
- Changed LOAD MYSQL VARIABLES to LOAD GENAI VARIABLES
- Clarified that NL2SQL queries run on MySQL module, not Admin
- Updated ARCHITECTURE.md to document async/non-blocking architecture
- Added LOAD GENAI VARIABLES TO RUNTIME after variable changes
- Changed stats_ai_nl2sql_cache to SHOW STATUS LIKE 'genai-nl2sql%'
Key corrections in README.md:
- Variables now use genai-* prefix (genai-nl2sql_enabled, etc.)
- Commands use LOAD GENAI VARIABLES instead of LOAD MYSQL VARIABLES
- Added note that NL2SQL queries are on MySQL module, not Admin interface
Key corrections in ARCHITECTURE.md:
- Updated system flow diagram to show async socketpair path
- Added detailed async flow explanation
- Documented that MySQL threads are NOT blocked during LLM calls
Related to: https://github.com/ProxySQL/proxysql-vec/pull/13
**Important**: NL2SQL uses an **asynchronous, non-blocking architecture**. The MySQL thread is not blocked while waiting for the LLM response. The request is sent via socketpair to the GenAI module, which processes it in a worker thread and delivers the result asynchronously.
@ -27,8 +27,8 @@ NL2SQL (Natural Language to SQL) is a ProxySQL feature that converts natural lan
```sql
-- Via admin interface
SET ai_nl2sql_enabled='true';
LOAD MYSQL VARIABLES TO RUNTIME;
SET genai-nl2sql_enabled='true';
LOAD GENAI VARIABLES TO RUNTIME;
```
### 2. Configure LLM Provider
@ -40,31 +40,31 @@ ProxySQL uses a **generic provider configuration** that supports any OpenAI-comp
Ollama is used via its OpenAI-compatible endpoint:
```sql
SET ai_nl2sql_provider='openai';
SET ai_nl2sql_provider_url='http://localhost:11434/v1/chat/completions';
SET ai_nl2sql_provider_model='llama3.2';
SET ai_nl2sql_provider_key=''; -- Empty for local Ollama
LOAD MYSQL VARIABLES TO RUNTIME;
SET genai-nl2sql_provider='openai';
SET genai-nl2sql_provider_url='http://localhost:11434/v1/chat/completions';
SET genai-nl2sql_provider_model='llama3.2';
SET genai-nl2sql_provider_key=''; -- Empty for local Ollama
LOAD GENAI VARIABLES TO RUNTIME;
```
**Using OpenAI:**
```sql
SET ai_nl2sql_provider='openai';
SET ai_nl2sql_provider_url='https://api.openai.com/v1/chat/completions';
SET ai_nl2sql_provider_model='gpt-4o-mini';
SET ai_nl2sql_provider_key='sk-...';
LOAD MYSQL VARIABLES TO RUNTIME;
SET genai-nl2sql_provider='openai';
SET genai-nl2sql_provider_url='https://api.openai.com/v1/chat/completions';
SET genai-nl2sql_provider_model='gpt-4o-mini';
SET genai-nl2sql_provider_key='sk-...';
LOAD GENAI VARIABLES TO RUNTIME;
```
**Using Anthropic:**
```sql
SET ai_nl2sql_provider='anthropic';
SET ai_nl2sql_provider_url='https://api.anthropic.com/v1/messages';
SET ai_nl2sql_provider_model='claude-3-haiku';
SET ai_nl2sql_provider_key='sk-ant-...';
LOAD MYSQL VARIABLES TO RUNTIME;
SET genai-nl2sql_provider='anthropic';
SET genai-nl2sql_provider_url='https://api.anthropic.com/v1/messages';
SET genai-nl2sql_provider_model='claude-3-haiku';
SET genai-nl2sql_provider_key='sk-ant-...';
LOAD GENAI VARIABLES TO RUNTIME;
```
**Using any OpenAI-compatible endpoint:**
@ -72,37 +72,39 @@ LOAD MYSQL VARIABLES TO RUNTIME;
This works with **any** OpenAI-compatible API (vLLM, LM Studio, Z.ai, etc.):
```sql
SET ai_nl2sql_provider='openai';
SET ai_nl2sql_provider_url='https://your-endpoint.com/v1/chat/completions';
SET ai_nl2sql_provider_model='your-model-name';
SET ai_nl2sql_provider_key='your-api-key'; -- Empty for local endpoints
LOAD MYSQL VARIABLES TO RUNTIME;
SET genai-nl2sql_provider='openai';
SET genai-nl2sql_provider_url='https://your-endpoint.com/v1/chat/completions';
SET genai-nl2sql_provider_model='your-model-name';
SET genai-nl2sql_provider_key='your-api-key'; -- Empty for local endpoints
LOAD GENAI VARIABLES TO RUNTIME;
```
### 3. Use NL2SQL
```sql
-- In your SQL client, prefix your query with "NL2SQL:"
mysql> SELECT * FROM runtime_mysql_servers WHERE variable_name='ai_nl2sql_enabled';
-- Verify NL2SQL is enabled (run this in the Admin interface)
SHOW VARIABLES LIKE 'genai-nl2sql%';
-- Query converted to SQL
-- Use NL2SQL in your MySQL client (MySQL module, not Admin)
mysql> NL2SQL: Show top 10 customers by revenue;
```
**Important**: NL2SQL queries are executed in the **MySQL module** (your regular SQL client), not in the ProxySQL Admin interface. The Admin interface is only for configuration.
Rene Cannao
4 months ago