SQL Studio

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

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

Features

Editor

• SQL syntax highlighting for PostgreSQL, ClickHouse, T-SQL, MySQL, SQLite, and generic .sql
• 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 Selection and Run All in File (Cmd+Shift+Enter / Ctrl+Shift+Enter); Cancel Query from the 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
• Format SQL and statement splitting via sqlglot, per dialect
• Warns when no connection is selected or the chosen connection is not active; warns before an unbounded SELECT on a large table, with Run, don't warn again to turn the check off
• Cursor Agent actions: Ask Agent to Explain Query, Ask Agent to Fix/Optimize Query

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-derived layout, column-level relationships, draggable routing, click-to-highlight with red animated flow child→parent, pan/zoom/autofit, Fit to view, Copy DBML, Open in dbdiagram.io) and Get DBML (copy to clipboard)
• Context menu on schema objects: Object Description, Sample Data, Export Data…, Copy Name, Create SQL Query, Generate SELECT
• Click a table or view to preview data in the same results UI as query output — with paging and Load all rows, like a regular query

Results

• Resizable columns with content-based default widths, drag to reorder, hide a column, sort
• Remembered layout — column order, hidden columns, widths, and sorting are restored per query (LRU over the most recent queries, sqlStudio.rememberedTableLayouts); Reset layout returns the current query's columns to their original state
• Row filter over the loaded rows: =, !=, ~ / !~ (contains), in (…) / not in (…), >, >=, <, <=, is null / is not null, is empty / is not empty, combined with AND / OR; one-click clear; the counter reads <matched> of <total> rows
• Right-click a column → Filter values lists the distinct values of low-cardinality columns; picking one appends column=value
• Pagination with a page-size selector and Load all rows; server or client fetch mode (sqlStudio.fetchMode, sqlStudio.serverPageSize)
• Refresh re-runs the same SQL without leaving the panel, preserving the filter, the current view, sorting, and column order
• The toolbar shows the query that produced the results, expandable in a scrollable hover popover
• Copy row (Cmd+Alt+C), copy value (Cmd+C), copy column name
• CSV / Excel export that matches the grid — honors the active filter, sort order, hidden columns, and reordered columns
• Formatted query errors (summary, database error code, collapsible stack trace)

Charts

• line, bar (columns or horizontal scroll for many categories), scatter, area, pie, heatmap; type picker icons
• X/Y column pickers, optional series, aggregation, and Value labels (Off / Value / Percent) drawn on bars, lines, and pie slices
• Pie charts open with smart defaults; many categories get a scrollable legend; pinch or Ctrl/Cmd + scroll to zoom
• The row filter is shared with the table view, and switching Table ↔ Chart preserves the table's scroll position

Connections

• Connection dialog (webview) with dialect-specific fields, optional tags, and Test connection
• Passwords stored encrypted via VS Code SecretStorage (OS keychain)
• ClickHouse Native (TCP, 9000) and HTTP (8123) drivers
• Microsoft SQL Server via ODBC (pyodbc)
• Accent colors follow the editor theme, overridable with sqlStudio.accentColor / sqlStudio.chartAccentColors
• Cursor Agent integration (rules template, MCP stub)

Screenshots

Query results (table) — Database Explorer, SQL editor and the SQL Results panel with sorting, an expression filter, pagination (Rows 1–10, page size, Load all rows), Refresh and CSV/Excel export:

Results filter — expression syntax over the loaded rows (col=value, col in (a,b), col is null/empty, AND / OR); the toolbar reports how many of them match:

Grid context menu — copy a row, a value or a column name, hide a column, or pick values for a column filter from the loaded rows:

Query results (chart) — line, bar, scatter, area, pie and heatmap over result columns, with X/Y column pickers, optional series, aggregation and value labels. Pie charts with many categories use a scrollable legend; pinch-to-zoom (trackpad pinch or Ctrl/Cmd + scroll) works on the chart area and trackpad scroll on the legend:

Pie charts group by a label column and label slices with values or percentages:

ER diagram — right-click a schema or database → View ER Diagram: DBML-derived layout with column-level relationships, pan and zoom, draggable tables, click-to-highlight, Fit to view, Copy DBML and Open in dbdiagram.io:

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 — leo@levragulin.ru

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.