A developer-first command-line toolkit to inspect, diagnose, optimize, and safely manage your SQL databases.
Note: SQL Doctor is an early-stage project under active development.
I'm actively testing it across different database engines and query patterns, but edge cases and bugs are expected. If you hit a query that parses oddly, an execution plan that renders weirdly, or an unhandled engine difference, please open an issue with the details so I can fix it!
As a software developer, I built SQL Doctor to solve the common database problems I run into every day:
- Struggling to understand why a query is slow — SQL Doctor analyzes query performance, visualizes execution plans, and identifies bottlenecks.
- Checking whether two databases have the same structure — SQL Doctor compares them side-by-side and clearly highlights missing or mismatched tables, columns, and indexes.
- Dealing with poorly chosen data types or oversized columns — SQL Doctor inspects your actual data records and recommends better, more compact definitions based on real statistics.
- Worrying about what could break when applying a migration — SQL Doctor checks for potential data loss, table locks, and compatibility issues beforehand.
- Knowing something is wrong with a database but not knowing where — SQL Doctor runs a full diagnostic across schema health, performance, indexes, data quality, and referential integrity.
It gives you clear, deterministic answers straight in your terminal without needing heavy GUI clients or cloud dashboards. And if you want conversational assistance, you can optionally connect your own Gemini API key for query explanations and natural-language query generation.
I built this tool with production safety in mind:
- Read-only by default: Database inspections and health checks run in read-only mode wherever the database engine supports it.
- Passwords are never displayed: Credentials are saved in your local user directory (
~/.sql-doctor/) with restricted permissions and masked on screen. - Zero telemetry: SQL Doctor does not call home, does not track your database, and has no tracking backend. It runs entirely on your machine.
- User-owned AI keys: I don't provide a shared API key or proxy your requests through any external server. You configure your own Gemini API key. Nothing touches an LLM unless you explicitly pass the
--aiflag or runsql-doctor ask. - Never runs destructive AI queries automatically: If you ask AI to write a query and it generates a
DELETE,UPDATE, orDROP, SQL Doctor warns you in bold red text and requires interactive confirmation before anything touches your database.
Make sure you have Go installed (version 1.26 or modern Go with modules):
git clone https://github.com/sql-doctor/sql-doctor.git
cd sql-doctor
go build -o sql-doctor ./cmd/sql-doctorOnce compiled, move the binary somewhere in your $PATH:
# Move to local bin
sudo mv sql-doctor /usr/local/bin/
# Check installation
sql-doctor --helpYou can build the .exe directly in PowerShell or Command Prompt:
# In PowerShell:
go build -o sql-doctor.exe ./cmd/sql-doctor
# Test it:
.\sql-doctor.exe --helpTo use it from anywhere on Windows, add the folder containing sql-doctor.exe to your User PATH environment variable, or move it to a directory already on your PATH (like C:\Users\<YourUser>\go\bin).
SQL Doctor works out of the box with MySQL, MariaDB, PostgreSQL, and SQLite.
# SQLite (Local file)
sql-doctor connect --type sqlite --file ./my-app.db --name my-local-db --save
# PostgreSQL
sql-doctor connect --type postgres --host localhost --port 5432 --user postgres --password mysecret --database shop_db --name local-pg --save
# MySQL / MariaDB
sql-doctor connect --type mysql --host 127.0.0.1 --port 3306 --user root --password mysecret --database shop_db --name local-mysql --save
# Or run directly against a database URL without saving:
sql-doctor --db-url "postgres://user:pass@localhost:5432/shop_db" db tablesTo see your saved connections or switch between them:
# List saved connections
sql-doctor connections
# Switch active connection
sql-doctor connections --use local-pg
# Quick connectivity test
sql-doctor pingRun a quick diagnostic across your whole database. It checks for tables missing primary keys, unindexed foreign keys, redundant indexes, and sampled data anomalies:
sql-doctor doctorOutput gives you a composite health score, along with critical issues and remedies:
Overall Database Health Score:
[███████████████░░░░░] 76 / 100 [NEEDS ATTENTION]
• Schema Quality: 70 / 100
• Data Cleanliness: 86 / 100
Critical Issues Detected:
CRITICAL [legacy_items] Missing Primary Key: Table does not have a defined Primary Key.
CRITICAL [orders.tracking_code] Duplicate Candidate Key Values
Warnings:
WARNING [orders] Unindexed Foreign Key: Column 'user_id' lacks a covering index.
Profile slow queries to see execution time, rows examined vs returned, and unindexed table scans:
# Profile a query and get a score
sql-doctor query analyze "SELECT * FROM users WHERE email LIKE '%@gmail.com'"
# Print an execution plan tree in plain English
sql-doctor query explain "SELECT u.name, o.amount FROM users u JOIN orders o ON u.id = o.user_id WHERE o.amount > 100"
# Get composite index recommendations (Equality -> Range -> Sort)
sql-doctor query optimize "SELECT * FROM users WHERE status = 'active' AND age > 21 ORDER BY created_at DESC"Don't guess what column type you should have used. SQL Doctor samples actual records and checks value lengths, patterns (like UUIDs, ISO dates, and booleans), and recommends tighter types:
sql-doctor schema datatypes usersExample recommendation:
INFO Column 'user_uuid'
Current Type: VARCHAR(255)
Suggested Type: CHAR(36) or UUID (Confidence: 95%)
Observed Stats: All values match standard UUID regex (fixed length 36).
Rationale: Storing in fixed CHAR(36) or native UUID reduces variable-length overhead.
Find broken referential integrity before your app hits a foreign key error:
sql-doctor db relationshipsThis lists all foreign keys (plus inferred relationships like user_id -> users.id) and counts any orphan records pointing to missing parents.
Need to verify if your staging database matches production?
sql-doctor db diff production stagingThis compares tables, columns, data types, nullability, defaults, and indexes, and generates the exact ALTER TABLE and CREATE TABLE migration SQL to sync them.
Before running a migration script on production, check it for destructive commands or locking hazards:
sql-doctor migration check ./migrations/2024_add_user_field.sqlCatches issues like:
DROP TABLEorDROP COLUMNALTER TABLE ... ADD COLUMN NOT NULLwithout aDEFAULT(which rewrites the table or fails on populated tables)- Incompatible type changes that trigger exclusive metadata locks
Quick static checks without needing a live connection:
# Lint for anti-patterns (SELECT *, implicit joins, cartesian products, non-sargable functions)
sql-doctor lint "SELECT * FROM users, orders WHERE users.id = orders.user_id"
# Format and pretty-print SQL
sql-doctor format "select id,name from users where status='active' and age>21 order by name asc"If you want AI explanations or natural-language query generation, add your own Gemini API key:
# Configure your API key
sql-doctor config set-ai-key <your-api-key>
# Verify configuration
sql-doctor config ai
# Ask questions grounded in your schema
sql-doctor ask "Which tables store customer billing records?"
# Generate queries
sql-doctor ask "Write a query to find the top 5 customers by revenue this year"Every single command supports the --json flag. You can pipe the output into jq or plug it into your CI/CD pipelines:
sql-doctor doctor --json
sql-doctor query analyze "SELECT * FROM users" --json
sql-doctor migration check ./migration.sql --jsonI built SQL Doctor as an individual developer for other developers. Database engineering has endless quirks across versions, engines, and edge cases, and I'd love your help making it better!
Good places to jump in:
- Found a bug? Open an issue with your database version and query.
- Want a new lint rule? Adding rules in the AST linter is straightforward.
- Want to add a database engine? I'd love drivers for SQL Server, Oracle, or CockroachDB!
- Feedback & ideas: Let me know what feels rough or could be diagnosed better.
👉 Check out the Contributor Guide (DEVELOPMENT.md) for how the codebase is organized, how to add drivers, and how to run tests locally.
SQL Doctor is open source software released under the MIT License.