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

1. Install SQL Preview from the VS Code Marketplace or OpenVSX.
2. Run SQL Preview: Manage Connections from the Command Palette.
3. Add a connection profile, set its password, test it, and make it active.
4. 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 (+ 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

1. Run SQL Preview: Manage Connections and confirm your active connection.
2. Open the SQL Preview settings panel and enable the MCP server.
3. Keep safe mode enabled unless you explicitly want agents to run mutating SQL.
4. 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