NoteX

Interactive notebooks for SQL and PowerShell — with Git integration and structured execution logging.

NoteX is a VS Code extension built for data engineers, DBAs, and DevOps professionals who need a unified notebook environment for SQL Server and PowerShell workflows. Author runbooks, execute code against local or remote targets, log every execution, and keep scripts version-controlled — all without leaving VS Code.

Features

Notebook Builder

• Create, rename, delete, and organize notebooks in folders via the NoteX Activity Bar panel
• Move, reorganize, and re-parent notebooks and folders via the tree view context menu
• Seven cell types: Header, Rich Text, Code Block, Section, Table, Divider, and Spacer
• Section cells — collapsible grouping containers; add cells directly inside a section or drag existing cells in/out
• Table cells — editable grids with add/remove row and column controls
• Move cells up/down with per-cell ↑/↓ buttons
• Collapse/expand individual cells or use toolbar Collapse All / Expand All
• Auto-save with configurable delay

Rich Text Editing

• Rich-text Text cells with a context-sensitive formatting toolbar (appears on focus)
• Paragraph styles (Normal, Heading 1–4, Code), font size, bold, italic, underline, strikethrough
• Text and highlight color pickers, bullet/numbered lists, indent/outdent, alignment controls

Code Blocks

• Syntax-highlighted editor with line numbers for SQL and PowerShell
• Per-block name and optional inline notes (rich-text annotation panel)
• Last-execution status badge (✅/❌ with duration)
• ▶ Run to execute a single block; ⏹ Stop to cancel a running execution
• ▶ Run All across the notebook with an optional Stop on error toggle
• Live execution timer while a block is running
• Output tabs: Results, Messages, Errors, Metadata
• Export results as CSV or JSON directly from the output panel
• Target one or more named SQL connections per block (multi-connection execution)

SQL Execution

• Execute SQL against SQL Server (on-premises or Azure SQL) using named connections
• Authentication modes: Windows, SQL Server, Azure AD, and Connection String
• View tabular results, PRINT messages, errors, and row counts inline
• Passwords stored securely via VS Code SecretStorage (OS keychain — never written to disk)
• Test any connection from the Connections view or Command Palette

PowerShell Execution

• Execute PowerShell locally or via PSRemoting (WinRM)
• Remote connections with current-user (pass-through) or credential authentication
• WinRM authentication methods: Default, Negotiate, NegotiateWithImplicitCredential, Kerberos, CredSSP
• Optional custom port and SSL (HTTPS) for remote connections
• Full stdout/stderr output displayed per block

Git / File Mapping

• Map any code block to an external .sql or .ps1 file in a Git-tracked folder
• 💾 Save to File — push cell content back to the mapped file on demand
• File change detection with configurable sync modes: Prompt, Auto-reload, Read-only, or None
• Optional auto-commit after notebook save with a customizable commit message template

Execution Logging

• Every code block execution generates a structured JSON log file
• Logs capture notebook/cell IDs, code, output, errors, duration, status, and environment metadata (hostname, VS Code version)
• Human-readable audit.log appended per execution — ideal for compliance and review
• Configurable retention by file count and age; optional exclusion of code or output from logs
• View logs via Ctrl+Shift+P → NoteX: View Execution Logs

Getting Started

Requirements

• VS Code ^1.85.0
• For SQL execution: network access to a SQL Server instance
• For PowerShell execution: pwsh or powershell on PATH; WinRM configured for remote targets

First Use

1. Open a workspace folder in VS Code (File → Open Folder)
2. Click the NX icon in the Activity Bar
3. Click + to create your first notebook
4. Add cells using the toolbar: H (Header), T (Text), { } (Code Block), [ ] Section, ⊞ (Table)
5. For SQL blocks: configure a connection via the Connections view → Manage SQL Connections
6. Click ▶ Run on a code block to execute

Interface Overview

Cell Types

Code Block Languages

SQL Connections

Add a connection via the Connections view → database icon, or:

Ctrl+Shift+P → NoteX: Manage SQL Connections

• Passwords stored in OS keychain via VS Code SecretStorage (never written to disk)
• Use NoteX: Test Connection to validate before executing
• SQL cells can target multiple connections simultaneously — results are returned per connection

Git / File Mapping

Map a code block to an external .sql or .ps1 file:

1. Click 📎 Map File in the code block toolbar
2. Select the file
3. Choose a sync mode

• Use 💾 Save to File in the code block toolbar to push cell content back to the mapped file on demand
• Enable notex.git.autoCommit to stage and commit mapped files automatically on notebook save
• Commit message template supports {cellName}, {notebookTitle}, and {timestamp} placeholders

Execution Logs

Logs are stored at:

<workspace>/.notex/notebooks/<NotebookName>/logs/
  block-<cellId>-<timestamp>.log.json

Each JSON log captures: notebook/cell IDs, code, output, errors, duration, status, and environment (hostname, VS Code version, NoteX version).

A human-readable audit.log is also appended per execution — useful for compliance, review, and change tracking.

View logs: Ctrl+Shift+P → NoteX: View Execution Logs

Settings

Notebook File Format

Notebooks are stored as plain JSON (.notex files) inside a named folder in your workspace. They are human-readable, diff-friendly, and safe to commit to Git.

<workspace>/
  .notex/
    notebooks/
      My Runbook/
        notebook.notex
        logs/

Troubleshooting

Extension not visible in Activity Bar

• Ensure a workspace folder is open (File → Open Folder)
• Check the NoteX output channel for errors

SQL connection fails

• Verify server name, port 1433 is reachable, and credentials are correct
• Enable notex.sql.trustServerCertificate: true for self-signed certs

PowerShell execution fails

• Confirm pwsh is installed and on PATH (pwsh --version in a terminal)
• For remote targets, verify WinRM is enabled on the target machine

License

MIT