The SQAI CLI(sql-query-ai-cli.py) tool provides a command-line interface for querying SQL databases using either direct SQL queries or natural language queries powered by LlamaIndex and Gemini.

1. Set up your environment variables:

export DATABASE_URL="postgresql://username:password@host:port/database"
export GEMINI_API_KEY="your-gemini-api-key"  # Required for NL queries only

2. Activate your virtual environment:

source venv/bin/activate

Start an interactive session where you can execute multiple queries:

python sql-query-ai-cli.py --interactive

Interactive Commands:

• sql <query> - Execute direct SQL query
• nl <query> - Execute natural language query ('nl' can be omitted)
• table <name> - Change current table
• show tables - List available tables
• help - Show help
• quit or exit - Exit the program

Example Interactive Session:

Query> table users
Table changed to: users

Query> sql SELECT COUNT(*) FROM users
=== Executing SQL: SELECT COUNT(*) FROM users ===
Found 1 records:
count
-----
150

Query> nl How many active users do we have?
=== Natural Language Query: How many active users do we have? ===
Response: Based on the data, there are 120 active users in the system.

Query> quit

Execute a single query and exit:

# Basic SQL query
python sql-query-ai-cli.py -t "users" -q "SELECT * FROM users LIMIT 5" -s

# With schema-qualified table
python sql-query-ai-cli.py -t "public.users" -q "SELECT name, email FROM public.users WHERE active = true" -s

# Simple NL query
python sql-query-ai-cli.py -t "products" -q "Show me all products with price greater than 100"

# Complex NL query
python sql-query-ai-cli.py -t "orders" -q "What is the average order value for last month?"

# Show all records from a table (direct SQL)
python sql-query-ai-cli.py -t "metadata_store" -q "SELECT * FROM metadata_store" -s

# Natural language query
python sql-query-ai-cli.py -t "sales" -q "Show me the top 10 customers by revenue this year"

The CLI tool provides helpful error messages for common issues:

• Database Connection: Clear messages when connection fails
• Missing Table: Warnings when specified table is not found
• API Key Missing: Instructions for setting GEMINI_API_KEY
• Invalid SQL: SQL syntax error details
• Network Issues: Timeout and connectivity error handling

• Interactive and single-query modes
• Direct SQL and natural language queries
• Schema-qualified table support
• Real-time table switching
• Comprehensive error handling
• Built-in help system

• Support OpenAI or other LLMs
• Query result export (CSV/JSON)
• Batch query execution
• To add

1. "Table not found" warnings

   • The tool will still attempt to query the table
   • Check table name spelling and schema qualification

2. Natural language queries not working

   • Ensure GEMINI_API_KEY is set
   • Check internet connectivity
   • Falls back to SQL interpretation if NL engine fails

3. Database connection errors

   • Verify DATABASE_URL format
   • Check database server accessibility
   • Confirm credentials are correct

Use the built-in help:

python sql-query-ai-cli.py --help

Or in interactive mode:

Query> help

• Never hardcode credentials in scripts
• Use environment variables for sensitive information
• The tool uses parameterized queries to prevent SQL injection
• Consider using database users with minimal required privileges