SQL Studio

Write SQL, explore database schemas, run queries, and browse results in VS Code and Cursor.

Русская документация: README.ru.md

Features

• SQL syntax highlighting for PostgreSQL, ClickHouse, T-SQL, MySQL, SQLite, and generic .sql
• Database Explorer — lazy schema tree (schemas/databases → tables, views, functions → columns)
• Connection tags — color-coded labels on connections (edit in the connection dialog or Manage Tags); shown in Explorer description and composite icons
• Schema object filter — inline filter on schema/database nodes to search tables, views, and functions by name; Edit Filter / Reset Filter when active
• Context menu on schema/database: View ER Diagram (DBML, column-level relationships, draggable routing, click-to-highlight with red animated flow child→parent, pan/zoom/autofit) and Get DBML (copy to clipboard)
• Context menu on schema objects: Object Description, Sample Data, Export Data, Create SQL Query, Generate SELECT
• Click a table or view to preview data in the same results UI as query output
• Create SQL Query — new editor from Command Palette or connection context menu
• Run queries: Cmd+Enter / Ctrl+Enter (works when focus is outside the editor if one SQL file is open)
• Run All in File: Cmd+Shift+Enter / Ctrl+Shift+Enter; Cancel Query from editor toolbar while a query runs
• Show Execution Plan: Shift+Cmd+E / Shift+Ctrl+E (EXPLAIN per dialect; PostgreSQL optional sqlStudio.explainAnalyze); Results panel shows Tree, Table, and Raw views with search, metrics, and copy actions
• Warns when no connection is selected or the chosen connection is not active before running SQL
• Results panel: resizable columns (content-based default widths), sort, filter, pagination, copy row/value
• Charts: line, bar (columns or horizontal scroll for many categories), scatter, area, pie, heatmap; type picker icons; CSV/Excel export
• Formatted query errors (summary, database error code, collapsible stack trace)
• Connection passwords stored encrypted via VS Code SecretStorage (OS keychain)
• Connection dialog (webview) with dialect-specific fields and optional tags
• ClickHouse Native (TCP, 9000) and HTTP (8123) drivers
• Microsoft SQL Server via ODBC (pyodbc)
• Cursor Agent integration (rules template, MCP stub)

Screenshots

Query results (table) — sort, filter, pagination, export:

Query results (chart) — pie, bar, scatter, heatmap from result columns. Pie charts with many categories use a scrollable legend; pinch-to-zoom (trackpad pinch or Ctrl/Cmd + scroll) on the chart area and trackpad scroll on the legend:

Supported databases

Requirements

• VS Code 1.85+ or Cursor 0.40+
• Node.js 18+ — only for building from source
• uv — required at runtime; the extension spawns the Python backend with uv run

# Install uv (macOS/Linux)
curl -LsSf https://astral.sh/uv/install.sh | sh

uv --version

If the backend fails to start, set SQL Studio: Uv Path in settings to the full path from which uv.

Installation

From VS Code Marketplace

1. Open Extensions (Cmd+Shift+X / Ctrl+Shift+X)
2. Search for SQL Studio
3. Click Install
4. Ensure uv is installed (see Requirements)
5. Reload the window if prompted

From a .vsix file

git clone https://github.com/levragulin/cursor-sql-studio.git
cd cursor-sql-studio
just install && just package
# Install cursor-sql-studio-0.1.0.vsix via Extensions → ⋯ → Install from VSIX…

See README.ru.md for detailed Cursor-specific install notes (drag & drop, CLI).

Quick start

1. Open the SQL Studio activity bar → Database Explorer
2. Click + (Add Connection) or run SQL Studio: Add Connection
3. Choose database type, fill host/port/credentials, click Test connection, then Save
4. Right-click the connection → Set Active Connection
5. Open or create a .sql file, pick the connection in the status bar
6. Press Cmd+Enter / Ctrl+Enter to run the query at the cursor

Keyboard shortcuts

Connection fields by dialect

ClickHouse: Native vs HTTP

Port 9000 does not work with the HTTP driver — select Native in the Driver field.

Microsoft SQL Server

Connections use pyodbc and a system ODBC driver. Without it, test and queries fail with Install Microsoft ODBC Driver for SQL Server.

Verify: odbcinst -q -d should list ODBC Driver 18 for SQL Server (or 17/13).

T-SQL files use extension .tsql and language SQL (Microsoft SQL Server). Table preview uses SELECT TOP N.

Working with the explorer

Settings

Privacy and security

• No telemetry — the extension does not send usage data to the author or third parties.
• Credentials — passwords are stored only in VS Code SecretStorage (encrypted by the OS). They are not written to settings, logs, or MCP responses.
• Queries — SQL runs directly between your machine and the database you configure. The Python backend runs locally via uv.
• Use read-only connections when exploring production data.

Cursor Agent

Templates in the repository:

• .cursor/rules/sql-agent.mdc — rules for .sql files in your workspace
• .cursor/mcp.json — MCP server template (sql-studio-mcp, stub)

Copy sql-agent.mdc into your project's .cursor/rules/ to enable agent-aware SQL editing.

Architecture

Backend layout (flat package under python/):

python/
├── sql_studio/          # Python package (server, drivers, dialect, export)
├── tests/               # pytest
├── pyproject.toml
└── uv.lock

Backend command (spawned automatically):

uv run --directory python sql-studio-server

Development

just install && just build && just test
just package   # builds .vsix

Press F5 in VS Code/Cursor for Extension Development Host.

Details: CONTRIBUTING.md, python/README.md, AGENTS.md.

Support

• GitHub Issues — bugs and feature requests
• Security reports — do not open public issues for vulnerabilities

Author

Lev Ragulin — [email protected]

Disclaimer

This software is provided as is, without warranty. You use SQL Studio at your own risk, including when connecting to production databases or running data-modifying statements.

License

The Beerware License (Revision 42) — retain the notice; optional beer if we meet in person.