Last updated: 2026-02-12

SQL Notebooks

Combine executable SQL cells with Markdown documentation in a Jupyter-compatible notebook. Run queries inline, share temp tables across cells, and build self-documenting database runbooks. Use the AI Chat Sidebar powered by Claude CLI or Codex CLI to add, edit, and execute cells with natural language.

Overview

SQL Notebooks provide a vertical, cell-based workspace where each SQL code cell has its own editor and inline results. Markdown cells let you add headings, lists, and formatted documentation between queries. All code cells share a single pinned database session, so temp tables and session variables persist across the entire notebook.

Common use cases include operational runbooks, incident response playbooks, training materials, data migration scripts, and self-documenting database workflows.

Creating a Notebook

Open a new notebook from the main toolbar:

1. Click the More dropdown in the toolbar
2. Select New Notebook
3. A new tab opens with one empty SQL code cell

To open an existing .ipynb file, use More > Open Notebook or drag the file into the app window.

Opened and saved notebooks also appear in the Scripts panel for quick re-opening, with a cell-count preview (for example: “3 code cells, 2 markdown cells”).

Notebook Toolbar

The notebook toolbar at the top of each tab provides:

• Connection selector — choose which database connection all cells use
• Database selector — pick the active database
• Run All — execute all code cells top-to-bottom sequentially
• Restart Session — release the pinned connection and clear session state (temp tables, variables)
• Clear All Outputs — remove results from every code cell
• Save — save the notebook as .ipynb
• AI Chat — open the AI sidebar (powered by Claude CLI or Codex CLI) to add, edit, and execute cells with natural language

Code Cells

Each code cell contains a Monaco editor with IntelliSense, auto-height sizing (3–20 visible lines), and a left gutter showing the execution order number.

Running a Cell

Execute a cell by clicking the Run button in the gutter or pressing Ctrl+Enter (Windows/Linux) / Cmd+Enter (macOS). Results appear inline below the cell as a data grid, messages panel, and status line showing duration and row count.

Shared Session

All code cells execute on a single pinned database connection. A temp table created in cell 1 is readable in cell 2. Session variables and SET options also persist. Click Restart Session to release the connection and start fresh.

Inline Results

After execution, results appear directly below the cell:

• Data grid for SELECT queries (first 500 rows displayed inline)
• Messages panel for all queries (errors, row counts, informational messages)
• Status line showing execution time and affected rows
• Collapse/expand toggle, clear output, and copy/export actions per cell

Markdown Cells

Markdown cells provide formatted documentation between code cells. They toggle between Edit mode (raw Markdown with a formatting toolbar) and Preview mode (rendered HTML).

Formatting Toolbar

The toolbar above the Markdown editor provides one-click formatting:

• Bold, Italic
• Heading levels (H1–H6)
• Bulleted and numbered lists
• Code blocks, links, images, horizontal rules

Click a cell in Preview mode to switch to Edit. Click outside (or press Escape) to return to Preview.

Cell Management

Add, reorder, and manage cells using the toolbar and keyboard shortcuts.

Adding Cells

Click the + button between cells or at the bottom of the notebook. Choose Code (SQL) or Markdown.

Reordering

Drag cells by the grip handle in the gutter, or use Move Up / Move Down buttons in the cell toolbar.

Converting

Convert between Code and Markdown using the cell toolbar button or keyboard shortcuts (Y for Code, M for Markdown in command mode).

Deleting

Delete a cell from the cell toolbar or press DD (double-D) in command mode. Cells with content show a confirmation dialog.

Run All

Click Run All to execute every code cell from top to bottom. A progress indicator shows which cell is running. By default, execution stops on the first error. Enable Continue on error to run all cells regardless.

Use Stop Execution to cancel the current cell and skip remaining cells. The Run From Here action in the cell toolbar runs the current cell and all cells below it.

Keyboard Shortcuts

Notebooks use two modes: Command mode (cell selected, blue border) and Edit mode (typing in editor, green border). Press Enter to enter Edit mode, Escape to return to Command mode.

Saving & Opening Notebooks

Notebooks save as .ipynb (Jupyter Notebook v4 format) for compatibility with Jupyter, VS Code, and other notebook tools.

Save Modes

• Rich (default) — includes cell outputs in the file for sharing complete results
• Clean — strips outputs for smaller files and cleaner version control diffs

Opening .ipynb Files

Use More > Open Notebook to open any .ipynb file. Jam SQL Studio handles files from:

• Azure Data Studio SQL Notebooks
• Polyglot Notebooks (SQL and JavaScript cells preserved; C#, F#, PowerShell cells imported as Markdown)
• Standard Jupyter notebooks with SQL kernels

Connection Behavior

Each notebook binds to one connection and database. When the connection changes:

• Existing cell outputs are marked with a stale badge (results from previous connection)
• The pinned session is released and a new one acquired on the next run
• The execution counter resets

If the connection is disconnected, a banner appears between the toolbar and cells.

Session Persistence

Notebook state persists across app restarts: cell sources, cell order, connection selection, file path, and markdown edit state are all restored. Cell outputs are not persisted in sessions (re-run cells after restarting the app). Outputs are only saved when writing to an .ipynb file.

Closing a notebook with unsaved changes shows a confirmation dialog with Save, Don't Save, and Cancel options.

Supported Databases

SQL Notebooks work with all engines: SQL Server, Azure SQL, PostgreSQL, MySQL, MariaDB, and SQLite.