sql-preview

SQL Preview

A fast SQL workspace for VS Code and MCP-enabled AI agents.

Run SQL in VS Code, manage database profiles securely, inspect results in a high-performance grid, and expose governed database tools to Claude, Cursor, Copilot, and other Model Context Protocol clients.

Why SQL Preview?

SQL Preview is built for the workflow where humans and agents both need real database context:

• Query from the editor: open a .sql file, press Cmd+Enter or Ctrl+Enter, and inspect results without leaving VS Code.
• Manage real connection profiles: create, test, select, and migrate database connections from the SQL Preview panel.
• Give agents governed access: expose read-only MCP tools for running queries, listing schemas and tables, describing columns, and inspecting shared result tabs.
• Stay local-first: there is no hosted SQL Preview service and no bundled AI model. Credentials stay in your VS Code Secret Storage or your local daemon profile configuration.

Highlights

• Connection manager with dynamic connector forms, active profile selection, legacy settings migration, and per-connection password actions.
• Tabbed result grid powered by AG Grid with sorting, filtering, column type display, adjustable density, TSV copy, and full CSV export.
• Daemon-backed execution so heavy queries do not block the editor and results can be shared across VS Code, browser, and MCP surfaces.
• MCP server for Claude Desktop, Cursor, Copilot, and other MCP clients, with safe mode enabled by default for read-only operation.
• Multi-surface sessions so agent-triggered and editor-triggered work can be inspected through the same local daemon without tab ID collisions.
• Transparent telemetry that is off by default, opt-in only, and never sends SQL text, results, credentials, hostnames, database names, schema/table/column names, file paths, usernames, or raw errors.

Supported Databases

SQL Preview ships connector metadata and setup forms for:

Database	Connector
PostgreSQL	postgres
MySQL	mysql
SQLite	sqlite
DuckDB	duckdb
Trino / Presto	trino
Snowflake	snowflake
BigQuery	bigquery
SQL Server	mssql

Trino/Presto and PostgreSQL are bundled into the extension build. Native and cloud-provider connectors are lazy-loaded and may require their driver runtime in the active environment; SQL Preview reports guided missing-driver errors instead of failing silently.

Quick Start: VS Code

• Install SQL Preview from the VS Code Marketplace or OpenVSX.
• Run SQL Preview: Manage Connections from the Command Palette.
• Add a connection profile, set its password, test it, and make it active.
• Open a .sql file and press Cmd+Enter on macOS or Ctrl+Enter on Windows/Linux.

Results open in the SQL Preview panel at the bottom of the editor. To force a new tab, run SQL Preview: Run Query in New Tab.

Migrating from Legacy Settings

If you previously configured sqlPreview.host, sqlPreview.port, sqlPreview.user, sqlPreview.catalog, sqlPreview.schema, or sqlPreview.databasePath, open SQL Preview: Show Welcome Guide or SQL Preview: Manage Connections. SQL Preview can import those settings into a named connection profile and keep passwords in VS Code Secret Storage.

Quick Start: MCP Agents

From VS Code

• Run SQL Preview: Manage Connections and confirm your active connection.
• Open the SQL Preview settings panel and enable the MCP server.
• Keep safe mode enabled unless you explicitly want agents to run mutating SQL.
• Configure HTTP-capable MCP clients with the local endpoint shown in the panel, typically:

{
  "mcpServers": {
    "sql-preview": {
      "url": "http://localhost:8414/mcp"
    }
  }
}

You can also open the Extensions view, search @mcp SQL Preview, and install the server into your user profile or current workspace from the MCP gallery.

Standalone Server

For Claude Desktop, Cursor, CI jobs, or any headless MCP client, use the standalone server:

{
  "mcpServers": {
    "sql-preview": {
      "command": "npx",
      "args": ["-y", "sql-preview", "--stdio"],
      "env": {
        "SQL_PREVIEW_CONNECTIONS": "[{\"id\":\"analytics\",\"name\":\"Analytics\",\"type\":\"postgres\",\"host\":\"localhost\",\"port\":5432,\"user\":\"analyst\",\"database\":\"warehouse\",\"password\":\"YOUR_PASSWORD\"}]"
      }
    }
  }
}

The MCP server exposes tools for:

Tool	What it does
run_query	Execute SQL and return typed JSON rows
list_connectors	Return supported connector types and setup schemas
list_connections	List configured connection profiles without secrets
save_connection	Add or update a connection profile
test_connection	Validate saved or unsaved connection settings
list_schemas	List schemas for a connection
list_tables	List tables within a schema
describe_table	Return column names and types
get_tab_info	Inspect daemon result tab state
cancel_query	Cancel a running query
close_tab	Close a daemon result tab

Safe mode is on by default and restricts agents to read-only statements such as SELECT, SHOW, DESCRIBE, EXPLAIN, WITH, and connector-specific metadata queries.

See the full Claude Desktop setup guide and daemon URL reference for advanced configuration.

Configuration

Most users should use SQL Preview: Manage Connections instead of editing settings JSON by hand.

Setting	Default	Description
sqlPreview.activeConnectionId	empty	Connection profile used for VS Code query execution
sqlPreview.maxRowsToDisplay	500	Max rows shown in the grid; full export is still available
sqlPreview.fontSize	0	Results grid font size in px; 0 inherits from the editor
sqlPreview.rowHeight	normal	Grid density: compact, normal, or comfortable
sqlPreview.tabNaming	file-sequential	Result tab naming strategy
sqlPreview.alwaysRunInNewTab	false	Always open query results in a new tab
sqlPreview.mcpEnabled	false	Enable the local MCP server for agent access
sqlPreview.mcpSafeMode	true	Restrict MCP query execution to read-only statements
sqlPreview.telemetry.enabled	false	Opt in to anonymous product telemetry
sqlPreview.telemetryHost	https://us.i.posthog.com	Advanced PostHog-compatible telemetry endpoint

Legacy connection settings such as sqlPreview.host, sqlPreview.port, sqlPreview.user, sqlPreview.catalog, sqlPreview.schema, and sqlPreview.databasePath remain available for migration and backward compatibility.

Passwords and Secrets

Passwords entered through the VS Code connection manager are stored per connection in VS Code Secret Storage, backed by the operating system keychain. They are not written to settings.json or sent to the webview.

Use these commands when needed:

• SQL Preview: Set Connection Password
• SQL Preview: Clear Connection Password
• SQL Preview: Manage Connections

Telemetry

SQL Preview telemetry is off by default. If enabled, events are anonymous, allowlisted, and used to improve setup, connector reliability, query workflows, MCP adoption, and product quality. SQL Preview never sends SQL text, query results, credentials, hostnames, database/schema/table/column names, file paths, workspace names, usernames, environment variables, process arguments, raw error messages, or stack traces.

Use SQL Preview: Show Telemetry Status to inspect the effective telemetry state.

Architecture

SQL Preview uses a local daemon model:

VS Code extension / MCP client / browser surface
        |
        v
SQL Preview daemon on localhost
        |
        v
Database connector
        |
        v
Your database

The daemon owns connection profiles, query execution, result tabs, MCP transports, and browser/VS Code projections. That lets editor sessions and agent sessions share the same local state while keeping credentials and execution on your machine.

Release Notes

See Changelog.md for the full release history.

Contributing

Contributions are welcome, especially new connector support, reliability improvements, and documentation fixes. See CONTRIBUTING.md for setup instructions and development workflow.

Found a bug? Open an issue on GitHub.

License

MIT (c) 2026 Mehul Fadnavis