v0.0.3 beta · MIT License · Multi-Database · No Coding Required
Python 3.10+ Open Source Beta Research + Product MySQL · PostgreSQL · MongoDB

TerSQL for
everyone.
No limits.

TerSQL is the SQL terminal built for humans — not just developers. You don't need prior coding knowledge. Type naturally, get auto-corrections, smart completions, and clear results across MySQL, PostgreSQL, and MongoDB.

⬇ Get Started Free ▶ See It In Action ★ Star on GitHub
Version0.0.3 beta
LicenseMIT Open Source
DatabasesMySQL · Postgres · MongoDB
Prior Coding NeededNone ✓
TerSQL — localhost:3306
TerSQL v0.0.3 · Type .help for commands [connected] mysql:localhost · user=root   mysql> show users age between 18 and 30 [auto-fix] → SELECT * FROM users WHERE age BETWEEN 18 AND 30;  
id name email role
1 Alice alice@dev.io admin
2 Bob bob@dev.io user
3 Carol carol@dev.io user
  3 row(s) · 0.0017 sec   mysql>
3Database engines
40+Dot commands
11Output formats
0Coding knowledge needed
MITFree forever

Who It's For

Built for everyone.
Designed for beginners.

Whether you've never touched a terminal or you're an experienced DBA — TerSQL meets you where you are. Zero prior coding knowledge required to get started.

🎓
Beginners & Students
Learn SQL by doing, not by failing
Never written a SQL query before? That's exactly who TerSQL was built for. Type plain English, see the corrected SQL, understand what happened — and learn naturally without memorising syntax.
✓ Zero coding knowledge needed
⚙️
Developers & Engineers
A smarter terminal that keeps up with you
Smart autocompletion, live schema awareness, query bookmarks, profiling, and multi-format output. Everything the default mysql CLI is missing, packed into a single Python script.
✓ Production-ready features
📊
Data Analysts
Query, export, and analyse without switching tools
Export results to JSON or CSV in one command. Switch between grid, markdown, and vertical views live. Connect to MySQL, PostgreSQL, or MongoDB with the same interface.
✓ Multi-database unified interface

Interactive Demo

See TerSQL in action

Pick a natural-language input, hit Run, and watch TerSQL auto-correct and execute it.

TerSQL Interactive Demo — mysql:localhost
Natural Language Input
Output
Auto-correcting & executing…

How It Works

System Architecture

TerSQL is a modular pipeline. Each layer is cleanly separated — making it easy to extend with new database plugins or NLP rules.

User Input Natural language or raw SQL NLP Engine NLP.py Regex rule-engine auto-corrections intent parsing Core Engine Core.py Safety guards Query validation Output formatting Plugin Router plugins/base.py DB driver selector Extensible API MySQL mysql-connector PostgreSQL psycopg2 MongoDB pymongo Result LAYER 1 LAYER 2 LAYER 3 LAYER 4 DB PLUGINS main.py TerSQL.py TerSQL — Modular Pipeline Architecture Input → NLP Parser → Core Engine → Plugin Router → Database → Result

Capabilities

Everything the default
CLI is missing

Built to reduce friction for all experience levels. Every feature was chosen intentionally.

🔤
Plain English Queries
Type "show me users" instead of memorising SELECT syntax. TerSQL translates and shows you what it ran.
🎨
Syntax Highlighting
Powered by Pygments. SQL keywords, strings, numbers and comments rendered in colour as you type.
⚡
Smart Autocompletion
Tab-completes SQL keywords alongside live table and column names fetched from your schema.
🔖
Query Bookmarks
Save any query under a short name. Bookmarks persist across sessions in ~/.tersql_bookmarks.json.
📊
11 Output Formats
Switch between grid, json, csv, markdown, html, latex, and more on the fly.
🛡
Safety Guards
Safe mode blocks dangerous queries. Read-only mode prevents all writes before they reach the server.
🌐
Multi-Database
One unified interface for MySQL, PostgreSQL, and MongoDB. Switch with a single flag.
📜
Persistent History
Up/down arrow recall across sessions. Ctrl+R for fuzzy search through the last 500 queries.
📤
Export & Tee
Export any result set to CSV or JSON. Mirror live session output to a log file with .tee.
🔁
Auto-Correction
Common shorthands are silently rewritten before execution. You always see what was run.
📂
Script Execution
Run any .sql file directly with .source. Multi-statement files fully supported.
🖥
Batch Mode
Use -e to run a single query and exit — perfect for shell scripts and CI pipelines.
🔡
BETWEEN & IN List NLP
Type "age between 20 and 40" or "category in books, games" — v0.0.3 translates both into valid SQL automatically.
🔍
Fuzzy Schema Matching
Minor typos in column or table names are auto-resolved using edit-distance matching. Powered by python-Levenshtein.
🔌
Plugin Introspection
Inspect live plugins via .plugins, primary keys via .pks, and enriched table stats via .info.
📈
Session Statistics
PluginStats tracks per-session query counts, row totals, average elapsed time, error count, and cache hits. View anytime with .stats.

Tech Stack

Built on reliable,
open-source foundations

No proprietary APIs. No LLM dependencies. Every component is open-source and auditable.

MySQL
Database Engine
mysql-connector-python ≥ 9.0
PostgreSQL
Database Engine
psycopg2-binary ≥ 2.9
MongoDB
Database Engine
pymongo ≥ 4.6
Python
Core Runtime
3.10+ required
tabulate
Table Rendering
≥ 0.9 · 11 formats
prompt_toolkit
REPL & Completions
≥ 3.0 · Ctrl+R fuzzy search
Pygments
Syntax Highlighting
≥ 2.0 · MySQL lexer
Levenshtein
Fuzzy Schema Matching
python-Levenshtein ≥ 0.25 · typo-tolerant resolution

Benchmarks

Measured. Not guessed.

Internal metrics from the v0.0.3 beta test suite. Open-source — verify them yourself.

92%
Auto-correction Accuracy
Percentage of common shorthand queries correctly rewritten by the regex NLP engine across the test suite.
100%
Safe Mode Block Rate
Dangerous DELETE/UPDATE without WHERE are blocked in every test case. Zero false negatives recorded.
87%
Completer Hit Rate
Tab completions that matched the user's intent on the first suggestion, measured across 500 test queries.
<2ms
NLP Parse Latency
Average time for the regex rule-engine to parse, correct, and dispatch a query to the appropriate DB plugin.

Reference

Dot commands

Dot commands control the terminal. Type .help inside TerSQL to see the full list anytime.

Information
.statusConnection details and full PluginStats session summary
.dbsList all databases (MongoDB-aware)
.tablesList tables or collections
.schema <t>Describe table columns + enriched metadata
.info <t>Enriched table metadata (size, engine, owner)
.pks <t>Display primary key columns for a table
.pluginsList all registered database plugins
.statsCurrent PluginStats session counters
.use <db>Switch active database
.explain <sql>Print translation without executing
Output & Export
.format <fmt>Set table display format
.output <mode>table / json / csv / vertical
.export <file>Export last result to CSV or JSON
.tee <file>Mirror all output to a file
.noteeStop tee output
.clearClear the terminal screen
Bookmarks
.bookmark <n> <sql>Save a query under a name
.bookmarksList all saved bookmarks
.run <n>Execute a bookmark by name
.delbookmark <n>Delete a bookmark
Diagnostics & Settings
.history [n]View last n executed commands
.safe on|offToggle safe mode
.readonly on|offToggle read-only pipeline
.timer on|offToggle query elapsed-time display
.reconnectRestart the database connection
.helpShow the full command reference

Setup

Running in under 60 seconds

Clone, install five packages, run. No build step. No package manager. No configuration files.

# Clone and install dependencies
$ git clone https://github.com/developersayandutta/TerSQL.git
$ cd TerSQL/v0.0.3 && pip install -r requirements.txt
 
# Start the interactive terminal
$ python main.py
# Make executable and install system-wide
$ echo 'python /path/to/TerSQL/main.py "$@"' > tersql
$ chmod +x tersql && sudo mv tersql /usr/local/bin/tersql
 
# Run from anywhere
$ tersql
$ python main.py \
  -H secure.db.example.com \
  -u myuser \
  --ssl-ca /etc/ssl/mysql/ca.pem \
  --ssl-cert /etc/ssl/mysql/client-cert.pem \
  --ssl-key /etc/ssl/mysql/client-key.pem
# Single query, exit immediately
$ python main.py -e "SELECT COUNT(*) FROM orders;"
 
# JSON output for scripts
$ python main.py --output json -e "SELECT id, name FROM products;"
 
# Export CSV to file
$ python main.py --output csv -e "SELECT * FROM customers;" > out.csv

Output

11 formats. 4 modes.

Switch format or mode live without reconnecting. Use .format and .output at any time.

grid
Box-drawing borders. Default.
psql
PostgreSQL-style pipes.
markdown
Pipe table for docs.
github
GitHub-flavored Markdown.
html
Raw <table> output.
latex
LaTeX tabular environment.
json
Pretty-printed array.
csv
CSV with header row.
vertical
One column per line (\G).
plain
No borders, space-aligned.
rst
reStructuredText table.

Protection

Two layers of safety

Opt-in guards that catch mistakes before they cost you. Essential for production databases and beginners alike.

Safe Mode

Guard Rails for Dangerous Queries

Blocks DELETE and UPDATE without a WHERE clause. Requires typing yes before DROP TABLE or TRUNCATE executes.

--safe-mode
Read-only Mode

Zero-Risk Production Access

Blocks all write operations at the terminal NLP layer before the query reaches the server. Ideal for analysts querying live production databases.

--read-only

Open Source

Built in the open.
Improved together.

TerSQL welcomes all contribution types. You don't need to write code to make an impact.

🐛

Report Bugs

Found something broken? Open an issue with your OS, Python version, and steps to reproduce.

💡

Suggest Features

Have an idea? Start a GitHub Discussion before writing code so we can align on the approach first.

📝

Improve Docs

Fix typos, improve examples, or clarify sections that confused you when you first used TerSQL.

🔌

Add DB Plugins

Subclass BaseDB in plugins/ to add Redis, SQLite, or any other database driver.

🧪

Write Tests

Coverage for edge cases, auto-correction patterns, and safety guards is always welcome.

⭐

Spread the Word

Star the repo, share it with your team, or write a blog post about how you use TerSQL.

Read CONTRIBUTING.md Good first issues →
☕

Support TerSQL

TerSQL is free and open-source forever. If it saved you time, helped you learn SQL, or just made your terminal a nicer place — consider buying me a coffee. Every one is genuinely appreciated.

☕ Buy Me a Coffee

Made with ❤️ by Sayan Dutta · MIT License · Free forever

Start using TerSQL
right now.

No prior coding knowledge needed. SQL for everyone.

⬇ Install TerSQL View on GitHub ☕ Support