Jupyter for SQL

Run SQL like a notebook — right inside VS Code and Cursor.

Open any .sql file as a Jupyter-style notebook: split queries into cells, run them one at a time, and see results as rich inline tables with sorting, filtering, charts, and one-click export. No Python, no Jupyter, no extra tooling required.

Supports Trino · PostgreSQL · MySQL · SQLite · MSSQL out of the box.

What it looks like

• SQL cells separated by -- %% markers, each with its own inline result table
• Cell numbers — [1], [2], [3]… shown in the left gutter after each run, just like Jupyter. Numbers are position-based so they're always stable for referencing
• Toolbar per result — filter, sort, export to CSV / Excel / clipboard, toggle charts and data bars
• CodeLens actions above every cell — add a LIMIT, beautify SQL, or open an AI fix prompt with one click
• Schema sidebar — browse catalogs, schemas, tables, and columns; click a column to insert its name
• Query history — every execution logged with connection, timing, and row count
• Cursor-optimised — schema, active cell, and full notebook structure are automatically written to .cursor/rules/ so Cursor AI always knows your tables, columns, and which cell you're editing

Quick Start

1. Install

Search Jupyter for SQL in the VS Code or Cursor Extension Marketplace, or install the .vsix directly.

2. Add a connection

Click the database icon in the activity bar → + → fill in the form.

Passwords are stored in VS Code SecretStorage (your OS keychain). They are never written to settings.json.

Example connections in settings.json (host + non-sensitive fields only):

"sqlNotebook.connections": [
  {
    "name": "Trino Prod",
    "driver": "trino",
    "host": "trino.example.com",
    "port": 443,
    "catalog": "awsdatacatalog",
    "schema": "analysis",
    "user": "me",
    "ssl": true
  },
  {
    "name": "Local Postgres",
    "driver": "postgres",
    "host": "localhost",
    "port": 5432,
    "database": "mydb",
    "user": "postgres"
  },
  {
    "name": "SQLite Dev",
    "driver": "sqlite",
    "database": "/path/to/file.db"
  }
]

3. Open any .sql or .sqlnb file

Both open as notebooks automatically. The active connection is shown in the status bar — click it to switch.

Tip: Use .sqlnb if you want outputs that survive window reloads and Cursor AI edits with zero flicker. Use .sql if you want a clean plain-text file that's easy to commit and diff.

Writing Notebooks

Cell separators — -- %%

-- %% Daily revenue
SELECT DATE(created_at) AS day, SUM(total) AS revenue
FROM orders
WHERE created_at >= CURRENT_DATE - INTERVAL '30' DAY
GROUP BY 1 ORDER BY 1

-- %% Top 10 customers
SELECT customer_id, COUNT(*) AS orders, SUM(total) AS spend
FROM orders
GROUP BY customer_id
ORDER BY spend DESC
LIMIT 10

-- %% [md]
## Analysis notes
Customers with spend > $5,000 qualify for the enterprise tier.

Each -- %% block becomes an independent cell. A -- [md] suffix creates a markdown cell.

Semicolon-delimited files (existing SQL files work too)

SELECT * FROM users LIMIT 10;

SELECT count(*) FROM orders WHERE status = 'PAID';

Variables — -- @var

-- @var schema = analytics
-- @var days   = 30

SELECT *
FROM {{schema}}.events
WHERE event_date >= CURRENT_DATE - INTERVAL '{{days}}' DAY
LIMIT 100

Define once at the top of any cell; reference with {{name}} anywhere in the notebook.

Per-cell connection override

-- @connection Staging Postgres
SELECT * FROM users LIMIT 5

Overrides the active connection for that cell only.

Result Table

Every successful query renders an interactive table with:

Export

Charts

Click Chart in the toolbar to toggle a visualisation:

• Line / area chart — auto-selected when a date, time, or timestamp column is detected on the x-axis. Great for trends over time.
• Bar chart — used for all other numeric data.

CodeLens Actions

Small action buttons appear above every SQL cell:

Output Persistence (.sqlnb — Jupyter-style)

Save your notebook as .sqlnb instead of .sql to get full Jupyter-style output persistence: results are embedded directly in the file and come back instantly after a window reload or a Cursor AI edit — zero flicker, zero re-running.

myanalysis.sqlnb   ← results embedded in the file, survive everything
myquery.sql        ← clean plain SQL, outputs stored in a session cache

How it works

When you save a .sqlnb file the extension appends a single base64-encoded line at the bottom of the file containing all cell outputs. On the next open, VS Code hands that data directly to the serializer — outputs are restored in the same parse as the SQL cells, before the screen renders. There is no async restore step and no separate sidecar file.

When Cursor AI edits a cell's SQL, the next reload compares the stored SQL against the new SQL. If they differ, an amber "SQL changed — re-run to refresh" stale banner is shown on the preserved output automatically.

When to use each format

Multi-cell notebook awareness

The extension automatically maintains three live context files in .cursor/rules/:

This means when you ask Cursor "add a join to cell 2 using customer_id from the first result", it already knows which lines to edit, what columns are available from previous results, and what's been run. No copy-pasting output.

Output persistence while Cursor edits

When Cursor AI rewrites a cell's SQL, VS Code normally clears the notebook outputs. This extension preserves them:

• .sqlnb files — zero flicker. Outputs are embedded in the file and restored synchronously with the cells. Cursor AI edits are detected on reload; changed cells show an amber stale banner automatically.
• .sql files — outputs are kept in a session-scoped in-memory cache and a sidecar file next to your .sql. A ~100ms async restore runs after each reload.
• Auto-reload — a file-system watcher (scoped to the exact file path, so it works anywhere on disk) automatically reloads the notebook when Cursor AI writes changes directly to the file. No more manual close-and-reopen.
• Stale banner — if the SQL changed since last run, the output shows an amber "SQL changed — re-run to refresh" banner rather than disappearing.
• Session-scoped — the in-memory cache clears when Cursor is closed and reopened.

Fix errors instantly

When a query fails, click 🔴 Fix Error above the cell. Cursor chat opens with your SQL and error pre-loaded — just send the message.

Query optimisation hints

After execution the extension analyses your SQL and timing. If it spots subqueries in IN(), slow runtimes (>5s), or cartesian joins, a hint CodeLens appears. Click it to get an AI-assisted rewrite.

Connection Sidebar

The SQL Notebook panel in the activity bar has two views:

Connections

• Browse all configured connections, grouped by label (Prod / Staging / Dev)
• Expand a connection to see schemas → tables → columns
• Click any column to insert its name at the cursor
• Right-click a connection: Set Active · Edit · Test · Refresh Schema · Disconnect · Delete

Query History

• Every execution logged with connection name, timing, row count, and success/fail status
• Click any entry to open the SQL in an editor for review or re-use
• Clear all history with the trash icon

Commands

Access via Cmd+Shift+P (macOS) / Ctrl+Shift+P (Windows/Linux):

Supported Drivers

All driver packages are bundled lazily — only the one you actually use is loaded. Cold start stays fast regardless of which drivers are installed.

Security

Settings

Local Development

git clone https://github.com/sujhan/sql-notebook-multi-driver
cd sql-notebook-multi-driver
npm install
npm run compile          # type-check only (tsc --noEmit)
# Press F5 in VS Code / Cursor to open the Extension Development Host

To build and package:

npx vsce package --no-dependencies    # → jupyter-style-sql-x.y.z.vsix

See DEVELOPMENT.md for a full architecture guide.

Changelog

See CHANGELOG.md for the full version history.