SQL Notebooks

The query pad understands SQL fence blocks inside Markdown and plain SQL files. Place your cursor inside any block and press <C-CR> to run only that block. The result appears in the grid below without touching anything else in the file.

Opening a notebook

Press gn from the query pad or schema sidebar to open the notebook picker. It scans for .md and .sql files in your project directory and shows a preview of each file’s contents.

Selecting a file loads it into the query pad. The file content appears as-is, with the query pad in a read-friendly layout and SQL blocks highlighted normally.

Running a block

In a Markdown file, blocks are delimited with triple-backtick SQL fences:

Some narrative text explaining what we are about to ask.

```sql
SELECT sku, product_name, softness_score
FROM rolls
ORDER BY softness_score ASC
LIMIT 10
```

What to notice in the result.

Press <C-CR> with the cursor on any line inside the block (or on the opening fence line). That block’s SQL executes. The surrounding narrative is untouched.

Block vs buffer execution

The same <C-CR> key does two different things depending on context:

This lets you use the same key whether you are working with a notebook or a plain SQL buffer. The block-aware path takes priority when a block is detected.

Writing notebooks

Any Markdown file with ```sql blocks works as a notebook. There is no special file format or frontmatter required. A notebook typically looks like:

• A brief introduction stating the question
• One or more SQL blocks, each preceded by a sentence explaining what it asks
• A sentence after the result describing what to look for

The SQL blocks should be self-contained. Each one should run independently against the current connection without depending on side effects from previous blocks.

The demo notebook

:GripStart loads the Softrear Inc. demo notebook automatically. It covers sixteen sections of a data quality investigation: product catalog anomalies, consumer incidents, a four-hop supply chain JOIN, intelligence analysis, and a cross-database join against an attached supplier database.

The notebook lives at demo/softrear-internal.md inside the plugin directory. Open it with gn from the query pad or schema sidebar to reload it.

Plain SQL files

.sql files also load into the query pad via gn. A plain SQL file has no Markdown fences, so <C-CR> always runs the full buffer unless you use a visual selection. Use gq (load saved query) for the query history workflow; use gn for named SQL files you want to keep on disk as part of a project.

Saving the current pad content

Press <C-s> in the query pad to save the current content as a named SQL file in .grip/queries/. Use gq to load saved queries back.

To save a notebook as a file on disk, use a normal :w write:

:w notebooks/my-analysis.md

The file is plain Markdown. Open it again with gn from the query pad or schema sidebar.