Jam SQL Studio Published: 2026-02-17
SQL Notebooks: Run, Document, and Share SQL
A .sql file tells you what the query does. A SQL Notebook tells you why, shows the results inline, and lets anyone re-run it with one click. This guide covers what SQL Notebooks are, when they beat traditional query files, and how to build your first one.
In This Guide
1. What Are SQL Notebooks?
SQL Notebooks are interactive documents that combine three types of content:
- SQL code cells — executable queries with inline results (data grids, messages, row counts)
- Markdown cells — formatted documentation with headings, lists, links, and code blocks
- A shared database session — temp tables, variables, and SET options persist across all cells
Think of them as a hybrid between a SQL script and a technical document. You get the executability of a query editor plus the narrative structure of a wiki page. Each cell runs independently, so you can iterate on one step without re-running the entire workflow.
Notebooks save as .ipynb files (the standard Jupyter Notebook format), making them portable across tools and easy to version-control in Git.
2. SQL Notebooks vs Traditional Query Editors
Both tools execute SQL. The difference is in how they organize and present work:
| Aspect | Query Editor (.sql) | SQL Notebook (.ipynb) |
|---|---|---|
| Structure | Single continuous file | Discrete cells with inline results |
| Documentation | SQL comments only | Rich Markdown with headings, lists, links |
| Results | Separate results panel | Inline below each cell |
| Execution | Run all or highlight selection | Run individual cells, Run All, or Run From Here |
| Sharing | Code only (results lost) | Code + documentation + saved results |
| Version control | Clean diffs | Clean diffs (use "clean save" mode to strip outputs) |
| Temp tables | Shared in one session | Shared across all cells (pinned session) |
| Best for | Quick queries, scripting | Runbooks, documentation, analysis, onboarding |
Neither replaces the other. Query editors are faster for one-off queries and script development. Notebooks shine when the work needs to be documented, shared, or re-executed by others.
3. 5 Use Cases Where Notebooks Beat .sql Files
1. Operational Runbooks
Database maintenance procedures that need to be followed step-by-step: checking replication lag, clearing old logs, rebuilding indexes, validating backups. A notebook documents the purpose of each step, shows expected results, and lets operators run each step one at a time with confidence. When something goes wrong at step 4, you know exactly where you are.
2. Team Onboarding
New team members need to understand the database schema, key tables, and common query patterns. A notebook walks them through the data model with executable examples: "Here's the Customers table, here's how orders relate to customers, here's how we calculate lifetime value." They run each cell and see real data, not static screenshots.
3. Data Migration Scripts
Migrations involve multiple steps with dependencies: create staging tables, transform data, validate counts, insert into production tables, verify results, clean up. A notebook makes each step explicit, shows intermediate results for verification, and documents rollback procedures in Markdown cells between the SQL.
4. Recurring Reports and Analysis
Monthly reports that pull metrics from multiple tables. Instead of a collection of .sql files and a README explaining the order, a single notebook contains the full analysis pipeline: extract raw data, calculate aggregates, summarize results. Re-run it next month by clicking Run All.
5. Incident Response Playbooks
When a production issue hits, you need to diagnose fast. A notebook for common incidents (high CPU, blocked queries, disk space alerts) provides diagnostic queries with explanations: "Run this to check active queries," "This shows blocking chains," "This identifies the top resource consumers." No scrambling through wiki pages during an outage.
4. Building Your First SQL Notebook
Here's how to create a notebook from scratch in Jam SQL Studio:
Step 1: Create a New Notebook
Click the More dropdown in the main toolbar and select New Notebook. A new tab opens with one empty SQL code cell ready for your first query.
Step 2: Select Your Connection
Use the connection selector in the notebook toolbar to pick which database your cells will execute against. All cells share this connection. You can switch connections later — existing results will be marked as stale.
Step 3: Add Documentation
Click the + button above the first cell and choose Markdown. Write a title and purpose for your notebook:
# Customer Analysis - Q4 2025
This notebook examines order patterns and customer
segmentation for Q4 2025 planning.Click outside the cell to see the rendered preview.
Step 4: Write and Run SQL Cells
In the SQL code cell, write your first query and press Cmd+Enter (Mac) or Ctrl+Enter (Windows/Linux) to execute. Results appear inline below the cell as a data grid with column headers, row counts, and execution time.
Add more cells below with the + button. Each cell can build on the previous one — temp tables created in cell 1 are available in cell 2.
Step 5: Save and Share
Press Cmd+S (Mac) or Ctrl+S (Windows/Linux) to save as a .ipynb file. Choose Rich mode to include results in the file (for sharing complete output) or Clean mode to strip results (for version control).
Teammates can open the .ipynb file in Jam SQL Studio, Jupyter, or VS Code. SQL cells work immediately.
5. Shared Sessions: Why Temp Tables Work Across Cells
One of the most useful features of SQL Notebooks is the shared database session. All code cells in a notebook execute on a single pinned database connection. This means:
- Temp tables persist — create a
#stagingtable in cell 1, query it in cell 5 - Variables persist —
DECLARE @threshold INT = 100in one cell is available in the next - SET options persist —
SET NOCOUNT ONapplies to all subsequent cells - Transaction control — you can begin a transaction in one cell, make changes in another, and commit or rollback in a third
This makes notebooks perfect for multi-step workflows where each step builds on the previous one. Unlike running separate queries in a query editor (which may use different connections), notebook cells share state reliably.
Click Restart Session in the notebook toolbar to release the pinned connection and start fresh. This drops all temp tables and resets session variables.
6. AI-Assisted Notebooks with Claude Code
Jam SQL Studio's AI Chat Sidebar works directly in SQL Notebooks. Click the AI button in the notebook toolbar to open a chat panel powered by your locally installed Claude Code CLI.
With the AI Chat Sidebar, Claude can:
- Add new cells — ask Claude to create SQL or Markdown cells with specific content
- Edit existing cells — describe what you want changed and Claude updates the cell content
- Execute cells — Claude can run cells and read the results to iterate on queries
- Build entire notebooks — describe your runbook and Claude creates the structure with documentation and queries
- Understand your schema — Claude auto-connects to the MCP server for live schema introspection
No extra subscription or API key is needed. The sidebar uses your existing Claude Code installation.
7. Migrating from Jupyter or Polyglot Notebooks
From Jupyter Notebooks
If you're using Jupyter with SQL extensions (ipython-sql, jupysql) for database work, Jam SQL Studio offers a more focused experience. Open your .ipynb files directly — SQL cells are preserved as code cells. You get native IntelliSense, GUI connection management, and a shared database session without configuring kernels or connection strings in code.
From Polyglot Notebooks
Polyglot Notebooks (formerly .NET Interactive) are being deprecated alongside Azure Data Studio. Jam SQL Studio opens Polyglot .ipynb files directly. SQL cells are preserved. Non-SQL cells (C#, F#, PowerShell) are imported as Markdown cells with a notice indicating the original language. No conversion tools required.
For a detailed migration walkthrough, see the Polyglot Notebooks alternative page and the Jupyter Notebooks alternative page.
8. FAQ
Which databases do SQL Notebooks support?
SQL Notebooks work with all engines supported by Jam SQL Studio: SQL Server, Azure SQL, PostgreSQL, MySQL, MariaDB, and SQLite.
Can I run JavaScript in notebook cells?
Yes. Jam SQL Studio supports JavaScript code cells in addition to SQL. JavaScript cells are useful for data transformation, calculations, or scripting logic between SQL queries.
How are notebooks saved?
Notebooks save as standard .ipynb files (Jupyter Notebook v4 format). Rich mode includes cell outputs for sharing complete results. Clean mode strips outputs for smaller files and cleaner Git diffs.
Do notebooks work with version control?
Yes. Save in Clean mode to strip outputs, giving you clean JSON diffs in Git. The notebook structure is standard JSON, so merge conflicts are manageable with standard diff tools.
What happens if a cell fails during Run All?
By default, Run All stops on the first error. Enable Continue on error to run all cells regardless. A progress indicator shows which cell is currently executing, and you can click Stop Execution to cancel at any point.
Start Building SQL Notebooks
Download Jam SQL Studio and create runbooks, onboarding guides, and self-documenting SQL workflows.