NLSQL - Natural Language to SQL CLI Tool

Convert natural language questions to SQL queries through a command-line interface.

NLSQL Demo

nlsql-demo.mp4

Installation

1. Clone the repository:

git clone https://github.com/TharaneshA/nlsql.git
cd nlsql

2. Install dependencies:

pip install -r requirements.txt

3. Install the package locally:

pip install -e .

🔧 Setting Up NLSQL with Your Local Database

To use NLSQL with your local database, you need to create a database connection profile. This allows the CLI to connect to your MySQL, PostgreSQL, or SQLite database and translate natural language into SQL queries.

---

✅ Step 1: Create a Database Profile

Run the following command to start the profile creation wizard:

nlsql profile create <profile-name>

Replace <profile-name> with something meaningful like my_local_db.

📋 Step 2: Enter Connection Details

You'll be prompted to enter your database connection information:

Prompt	Example (MySQL)	Example (SQLite)
Database type	MySQL	SQLite
Host	localhost	(leave blank)
Port	3306	(leave blank)
Database name	nlsql_demo	/path/to/your/database.db
Username	root	(leave blank)
Password	your_password	(leave blank)
Connection options	(optional)	(optional)

💡 Tip: For SQLite, you can use :memory: to create an in-memory database.

🔁 Step 3: Set Active Profile

After creating a profile, set it as the active one:

nlsql profile use <profile-name>

🧪 Step 4: Test the Connection

You can test the database connection by listing tables:

nlsql list tables

💡 Example: MySQL Setup

nlsql profile create my_mysql_db

# Prompts:
# Database type: MySQL
# Host: localhost
# Port: 3306
# Database name: nlsql_demo
# Username: root
# Password: your_password

nlsql profile use my_mysql_db
nlsql list tables

💡 Example: SQLite Setup

nlsql profile create my_sqlite_db

# Prompts:
# Database type: SQLite
# Host: (leave blank)
# Port: (leave blank)
# Database name: ./nlsql_demo.db
# Username: (leave blank)
# Password: (leave blank)

nlsql profile use my_sqlite_db
nlsql list tables

🤖 AI Provider Configuration

NLSQL supports multiple AI providers for natural language to SQL translation. You can configure your preferred AI service using the interactive setup process.

🔧 Setting Up Your AI Provider

1. Run the configuration command:

nlsql config setup

2. Select your preferred AI provider from the available options:

• Gemini (Google)
• OpenAI (GPT-4)
• Anthropic (Claude)
• Grok (Coming soon)

3. Enter your API key for the selected provider

🔄 Changing AI Provider

To switch or update your AI provider configuration:

nlsql config set

This will launch an interactive menu where you can:

• Select a different AI provider
• Update API keys
• View current configuration

🔐 Notes on Security & Config

• 🔒 API keys and passwords are stored in plain text inside config files. For secure environments, consider using environment variables.
• 📁 Profiles are stored in: ~/.nlsql/profiles/
• ✅ The active profile is stored in: ~/.nlsql/active_profile.txt
• 🔑 Environment variables for API keys:
  • GEMINI_API_KEY
  • OPENAI_API_KEY
  • ANTHROPIC_API_KEY
  • GROK_API_KEY

Usage

Managing Profiles

• List profiles: nlsql profile list
• Create profile: nlsql profile create <name>
• Switch profile: nlsql profile use <name>
• Edit profile: nlsql profile edit <name>
• Delete profile: nlsql profile delete <name>

Database Operations

• Connect to database: nlsql connect
• List tables: nlsql list tables
• Show table schema: nlsql describe <table-name>
• Cache database schema: nlsql cache-schema

Querying

Basic query:

nlsql query "Show me all users from New York" -x

Query Options:

Option	Description
--edit, -e	Edit SQL before execution
--execute, -x	Execute the query
--save <name>	Save query for later use
--format <format>	Output format (table/json/csv)
--export <file>	Export results to file
--explain	Show query execution plan

Saved Queries

• List saved queries: nlsql saved list
• Run saved query: nlsql run <query-name>
• Delete saved query: nlsql saved delete <query-name>

History

• View query history: nlsql history

Configuration

• List config: nlsql config list
• Set config value: nlsql config set KEY=VALUE
• Unset config value: nlsql config unset KEY

Examples

1. Create and use a database profile:

nlsql profile create mydb
nlsql profile use mydb

2. Query with natural language:

nlsql query "Find all orders placed in the last 7 days" -x

3. Save and reuse a query:

nlsql query "Show top 10 customers by order value" --save top_customers
nlsql run top_customers

4. Export query results:

nlsql query "List all products with low stock" --format csv --export low_stock.csv

License

This project is licensed under the MIT License - see the LICENSE file for details.