SQL Notebook Studio

Jupyter-style SQL notebooks for VS Code.
Write SQL in cells, see results in a fast grid, chart them in one click, and let AI write, fix and explain your queries.

Install · Quick start · Features · Connect · AI · Settings · FAQ

Run a notebook, sort the results and switch to a chart

Why SQL Notebook Studio

One notebook for every database. MySQL, MariaDB, PostgreSQL and SQL Server. SQLite and DuckDB are built in, so you can start with no server at all.
Results you can work with. A virtual grid that stays fast with 10,000+ rows. Sort, filter, copy, export, and switch to a chart in one click.
AI that knows your schema. Write SQL from plain words, fix errors, optimize slow queries and explain results. Use OpenAI, Anthropic, OpenRouter or a local model through Ollama.
Plain-text notebooks. .sqlnb files are readable SQL, so they diff and review well in Git.
Safe by default. Passwords stay in VS Code's secret storage. Production connections confirm every write. Read-only connections block them.

Install

From the Marketplace: search for SQL Notebook Studio in the Extensions view, or run:

code --install-extension kgptalkie.sql-notebook-studio

From a file: download the .vsix for your system, then in VS Code open Extensions → ··· → Install from VSIX…

Quick start

Open the SQL Notebook Studio view in the activity bar.
Click Open Sample Notebook. It uses a small shop database that ships with the extension.
Press Run All, or Ctrl+Enter in a cell.

To make your own notebook, run SQL Notebook Studio: New SQL Notebook, or right-click a .sql file and choose Open as SQL Notebook.

Features


Notebooks	SQL, Markdown and AI cells. Several statements per cell, each with its own result tab. Stop works on every database.
Results grid	Virtual scrolling, sort (Shift+click for more columns), filter per column (`>10`, `a..b`, `!x`, `null`), resize and pin columns, value viewer for long text and JSON.
Charts	Bar, line, area, scatter and pie. Pick X and Y, stack series, save the chart with the cell.
Explorer	Connections, schemas, tables, views and columns with types and keys. Select Top 100 and Describe in one click.
Autocomplete	Tables, views, columns, schemas and keywords from the live schema. Fuzzy and case-blind: `slt` finds `SELECT`, `EMP` finds `employees`. `alias.` lists that table's columns.
Capital keywords	SQL keywords turn into capitals as you type, using the keyword list of the cell's database. Your table, column and alias names, strings and comments stay as you wrote them. One Ctrl+Z undoes it.
Variables	`{{name}}` asks for a value once per session. `${env:NAME}` reads an environment variable.
Export	Copy as TSV, CSV, Markdown or JSON. Export results to CSV or JSON, and notebooks to HTML (with charts), PDF or Markdown.
Safety	Confirms `DROP`, `TRUNCATE`, and `UPDATE` or `DELETE` without `WHERE`. Production tags and read-only connections.

A notebook with SQL and Markdown cells and a results grid

A line chart of monthly revenue

Autocomplete

Autocomplete for tables, aliases and columns

Connect to a database

Click + in the view and fill in the form. Or click Paste connection string: if you already copied one, it is filled in for you.

Add a connection by pasting a connection string, test it, save it, then browse tables

Database	Notes
MySQL / MariaDB	SSL/TLS, SSH tunnel
PostgreSQL	SSL/TLS, SSH tunnel
SQL Server	SQL login, Windows (NTLM) or Microsoft Entra ID
SQLite	Built in. A file or in memory
DuckDB	Built in. A file or in memory. Query CSV and Parquet directly

SSL/TLS with CA, client certificate and key.
SSH tunnel with password, key file or SSH agent.
Connection strings: mysql://, postgres://, Server=…;Database=…, or a file path.
Each notebook remembers its connection. A single cell can use another one from its status bar.

The connection form, filled in from a connection string and tested

Connection explorer with tables, columns and types

AI

AI is optional and off until you set it up: run SQL Notebook Studio: Configure AI. It works through LangChain, so every provider behaves the same.

Provider	What you need
OpenAI	API key
Anthropic	API key
OpenRouter	API key
Ollama	Ollama running locally. No key, nothing leaves your machine
Custom	Any OpenAI-compatible URL

Feature	What it does
AI cell	Write what you want in plain words. The SQL appears in the next cell, ready to run.
Fix with AI	On an error, shows the cause and a corrected query. Apply it in one click.
Explain	Explains a query step by step.
Optimize	Reads the query plan and suggests a faster query or an index.
Explain result	Summarizes what the rows show. Asks before it sends any rows to a cloud provider.

Only the schema (table and column names) is sent with your request, unless you allow result data.

AI cell: plain words in, SQL out

An AI cell writes SQL with local Ollama, then the SQL runs

Fix an error, then explain the result

Fix with AI corrects a failing query, then Explain result summarizes it

Fix with AI shows the cause and a corrected query

Explain result describes what the rows show

The `.sqlnb` format

A notebook is plain SQL with comment markers, so it reads well in any editor and in a Git diff:

-- sqlnb v1 {"connection":"Sample Shop"}
-- %% md
-- ## Top products
-- %% sql
SELECT name, price
FROM products
ORDER BY price DESC;

Settings

Setting	Default	What it does
`sqlNotebook.results.maxRows`	`10000`	Rows kept per result
`sqlNotebook.queryTimeoutSeconds`	`0`	Query timeout. `0` means none
`sqlNotebook.saveResults`	`false`	Save results in the notebook file
`sqlNotebook.confirmDestructive`	`production`	When to confirm risky statements
`sqlNotebook.editor.uppercaseKeywords`	`true`	Turn SQL keywords into capitals as you type
`sqlNotebook.autocomplete.keywordCase`	`upper`	Case of inserted keywords: `upper`, `lower`, or `auto` to follow what you type
`sqlNotebook.export.maxRows`	`500`	Rows per result in exported files
`sqlNotebook.ai.provider`	`openai`	AI provider
`sqlNotebook.ai.model`		Model name, for example `qwen3.8:27b` for Ollama
`sqlNotebook.ai.baseUrl`		Custom or Ollama URL
`sqlNotebook.ai.allowResultData`	`false`	Send rows to AI without asking
`sqlNotebook.ai.runGeneratedSql`	`false`	Run SQL from an AI cell at once

FAQ

Do I need a database server to try it? No. The sample notebook runs on the built-in SQLite. DuckDB is built in too.

Where are my passwords stored? In VS Code's secret storage (your OS keychain). Never in settings or in the notebook file.

Can I use AI without sending data to the cloud? Yes. Choose Ollama and run a local model. Nothing leaves your machine.

How does it know which words are SQL keywords? Each notebook has a connection, so it knows the database: the toolbar shows it, for example Sample Shop · SQLite. The keyword list for MySQL, PostgreSQL, SQL Server, SQLite or DuckDB comes from the sql-formatter library, so it stays current with that project. Names in your database are never changed, so a column called name or status stays as it is. To turn it off, run SQL Notebook Studio: Toggle Uppercase Keywords or untick the setting.

Can I open my existing .sql files? Yes. Right-click a .sql file and choose Open as SQL Notebook. Each statement becomes a cell.

Which platforms are supported? Windows, macOS and Linux (x64 and arm64), including Alpine.

Can't connect, or a connection stops working? See TROUBLESHOOTING.md: error messages and fixes for each database, for example SQL Server letting only one notebook connect at a time.

Development

npm install
npm run build        # bundle the extension, renderer and webview
npm test             # unit and driver tests
npm run package:all  # one .vsix per platform in vsix/

Press F5 in VS Code to start an Extension Development Host.

Releasing. Raise version in package.json, add the changes to CHANGELOG.md, commit, then push a matching tag:

git tag v1.0.1
git push origin v1.0.1

The Publish workflow tests, builds the 8 platform packages and publishes them to the Marketplace. It uses Trusted Publishing, so no token is stored anywhere.

Contributing

Bug reports and ideas are welcome in Issues. For a pull request, please open an issue first so we can agree on the change.

License

You can use, change and share this code, also in commercial work. If you publish it, or a work based on it, keep the NOTICE file with it and credit SQL Notebook Studio by KGP Talkie with a link to this repository.

Third-party software included in the extension is listed in THIRD-PARTY-NOTICES.txt.

Trademarks

The license covers the code, not the names. "SQL Notebook Studio", "KGP Talkie" and the SQL Notebook Studio logo are not licensed for use by forks. If you publish a fork, give it your own name and logo.

Made by KGP Talkie · If it helps you, please ⭐ the repo and rate it on the Marketplace.

SQL Notebook Studio

KGP Talkie

SQL Notebook Studio

Why SQL Notebook Studio

Install

Quick start

Features

Autocomplete

Connect to a database

AI

AI cell: plain words in, SQL out

Fix an error, then explain the result

The .sqlnb format

Settings

FAQ

Development

Contributing

License

Trademarks

The `.sqlnb` format