#SQL Notebooks

JustyBase integrates with the VS Code Notebook API to provide interactive SQL notebooks. Notebooks let you combine executable SQL cells, inline results, and rich visualizations in a single document — ideal for ad-hoc analysis, reproducible reports, and collaborative data exploration.

#Creating a Notebook

A new notebook opens with a starter SQL cell pre-populated.

#Cell Types

#Executing Cells

#Cell Toolbar Button

Each SQL cell has a toolbar with Execute (▶) and Stop (⬛) buttons.

• Click Execute on a cell to run its SQL
• Results appear inline as an HTML table directly below the cell
• Click Stop to cancel a running query

#Execution Order

Cells execute sequentially in the order you click them. Each cell's execution is independent — results are not shared between cells.

#Cancellation

Click the Stop button in the cell toolbar during execution. The query is cancelled at the database level and the cell shows an inline error message.

#Inline Results

After execution, each cell displays:

1. Row count — shown in the cell output header
2. HTML table — the result data rendered as a formatted table with:
   • Alternating row colors
   • Sticky column headers
   • NULL values displayed in italic gray
   • Row numbers
   • Row-limit indicator when the configured limit is reached
   • Records-affected count for DML statements

#Multiple Result Sets

If your SQL produces multiple result sets (e.g., multiple SELECT statements), each result set appears as a separate table with its own heading.

#Full Grid Panel

Click the Full Grid button in the cell's status bar (the bar below the cell showing cell language and execution time) to open the full interactive grid in a separate webview panel.

#IntelliSense in Notebooks

SQL cells in notebooks have the same language support as regular .sql files:

• Code completions (Ctrl+Space) — tables, columns, views, functions, keywords
• Hover tooltips — column types, table descriptions
• Diagnostics — real-time linting and parser validation with error codes (NZ001, SQL003, etc.)
• Signature help — function parameter hints
• Code formatting — format all SQL in a cell via Shift+Alt+F
• Go to Definition — for CTEs, subquery aliases, and temp tables

The language server (LSP) activates for notebook cells automatically.

#Connection Handling

Notebooks use the same connection infrastructure as regular SQL files:

• Per-cell connections — a cell's assigned connection is used first, so two cells in one notebook may execute against different profiles
• Global fallback — when a cell has no assigned connection, execution falls back to the globally active connection
• Per-cell database — an explicit database assigned to the cell takes precedence over the selected profile's default database
• Ephemeral context — notebook-cell connection and database selections are held only for the current session; they are not written to the notebook or restored after the session closes
• Cancellation — each cell execution is independent; cancelling one cell does not affect others

Important: Each notebook cell execution opens a new database connection and closes it after completion. Persistent connections (per-tab keep-connection) do not apply to notebook cells.

#File Format

Notebooks are stored as plain JSON (.sqlnb / .nzsql-nb):

{
  "cells": [
    {
      "language": "sql",
      "value": "SELECT * FROM SYSTEM..TABLES LIMIT 10;",
      "kind": 2
    }
  ]
}

• kind: 2 = Code cell
• kind: 1 = Markdown cell
• The JSON format is human-readable and version-control friendly

#Settings

#Limitations

• Cell variable sharing (piping results between cells) is not supported
• Notebook export (e.g., exporting all cells and results as a report) is not yet implemented — use the Full Grid panel for individual result export