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 follows your VS Code telemetry setting and can be turned off at any time. Crash reports carry redacted stack traces, with file paths reduced to their extension and usernames removed. It never sends SQL text, results, credentials, hostnames, database names, schema/table/column names, workspace names, or raw driver error messages. The separately controlled replay capability masks every rendered character and input.

Supported Databases

SQL Preview ships connector metadata and setup forms for:

Database	Connector
PostgreSQL	postgres
MySQL	mysql
SQLite	sqlite
DuckDB	duckdb
Trino / Presto	trino
Elasticsearch	elasticsearch
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

Recommended: stdio

• Run SQL Preview: Manage Connections and confirm your active connection.
• Open the SQL Preview settings panel and enable the MCP server (sqlPreview.mcpEnabled). This is required and ships off — the daemon serves no MCP surface until you turn it on.
• Keep safe mode enabled unless you explicitly want agents to run mutating SQL.
• Point your MCP client at the stdio server:

{
  "mcpServers": {
    "sql-preview": {
      "command": "npx",
      "args": ["-y", "sql-preview", "--stdio"]
    }
  }
}

This bridges to the daemon the VS Code extension is already running, so agent queries and sessions show up in the results grid alongside anything you run from the editor. It works with every MCP client — including ones that cannot send custom HTTP headers, such as Claude Desktop — and it needs no credential in your config, because the bridge reads the daemon's access token itself.

Launching this bridge yourself is treated as asking for MCP, so it works even when the editor setting is off. If you want to refuse MCP everywhere, including this bridge, set "mcp": { "enabled": false } in ~/.sql-preview/daemon.json.

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.

Advanced: HTTP

The daemon requires an authorization token on every non-public route, so an HTTP client must send it. Use this when your client supports custom headers (Cursor and VS Code do):

{
  "mcpServers": {
    "sql-preview": {
      "url": "http://localhost:8414/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}

The settings panel offers this snippet with the token already filled in — copy it from there rather than assembling it by hand. The token also lives at ~/.sql-preview/auth-token; treat it like a password, since it authorizes access to your connections and query results.

Upgrading from 0.6.x? Two things changed. A bare {"url": "http://localhost:8414/mcp"} config no longer connects — switch to the stdio config above (recommended) or add the Authorization header. And sqlPreview.mcpEnabled now genuinely gates the surface: with it off, /mcp returns 404, because the route is not registered rather than being registered and refused. Previously the setting only decided whether the daemon started eagerly, so HTTP MCP answered whether or not you had enabled it.

Standalone / stdio Server with its own connections

For CI jobs or any client that should not share the editor's daemon, the standalone server can carry its own connection profiles:

{
  "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\"}]"
      }
    }
  }
}

--stdio first checks whether a shared daemon is already listening on the configured port (--port, then SQL_PREVIEW_MCP_PORT, SQL_PREVIEW_PORT, or MCP_PORT; default 8414) — for example, one started by the VS Code extension — and, if so, bridges to it, so the agent's queries and sessions still appear in the VS Code grid exactly like the HTTP form above. If no shared daemon is reachable, it falls back to starting its own embedded, isolated daemon exactly as before. Pass --embedded or set SQL_PREVIEW_EMBEDDED=1 to force the isolated daemon unconditionally, which is recommended for CI and other headless runs that shouldn't depend on (or interfere with) a locally running instance. The MCP initialize response explicitly reports SQL Preview isolation mode: shared or isolated in its standard instructions field. Agents can use that protocol signal to tell whether their query sessions are visible in the user's editor; stderr is not required for detection.

The VS Code extension currently resolves its daemon from SQL_PREVIEW_MCP_PORT or port 8414, while the daemon itself also accepts SQL_PREVIEW_PORT, MCP_PORT, and daemon.json. If those resolve differently, SQL Preview now warns with both endpoints before starting another daemon. This is detection, not automatic correction: align the settings or remove the custom port.

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	Serve the local MCP surface for agent access. Off means /mcp is not registered (404)
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 enabled by default when VS Code telemetry is enabled, and you can turn it off at any time with sqlPreview.telemetry.enabled. Events are anonymous and allowlisted, and are used to improve setup, connector reliability, query workflows, MCP adoption, and product quality.

When something crashes, SQL Preview sends a redacted stack trace so the failure can be diagnosed without asking you for logs. Before anything leaves your machine, file paths are reduced to their extension (<path>/*.sql) and usernames are removed; paths that point at code keep only the part from node_modules/ or the build directory onward. If redaction fails for any reason, the report is dropped rather than sent.

SQL Preview never sends SQL text, query results, credentials, hostnames, database/schema/table/column names, workspace names, environment variables, process arguments, or raw driver error messages. A driver's error message can embed table names, column names, and literal data values, so crash reports carry the error's type and its stack — not the message text.

Session replay is separately feature-flagged and disabled by default. When it is enabled, it covers only the VS Code results webview and masks every rendered character and input; it does not record SQL, results, or other displayed content.

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