SQL Notebooks: queries, results and notes in one file

Keep the queries of an investigation, their results and the notes between them in one Jupyter file, run cell by cell or all at once, and export it to HTML or PDF.

Applies to
Edgely Database Manager
Updated

Also in the app Edgely Database Manager: Help, then Documentation (F1), SQL Notebooks

A notebook keeps the queries of an investigation, their results and the notes between them in one file. It is a Jupyter .ipynb file, so notebooks made in Azure Data Studio open as they are.

Create and open

  • File > New Notebook (or Ctrl/Cmd+K, then "notebook") opens a notebook on the open connection; with several open, you pick one. MongoDB connections cannot run notebooks and are not offered.
  • File > Open Notebook, or Cmd/Ctrl+O (which also accepts .ipynb files), opens a notebook and connects the connection it names. When that connection is not on this device, the toolbar offers Choose a connection. A file that is already open is selected instead of opened a second time.
  • Nothing runs when a notebook opens: you see the results it was saved with. A notebook that is not attached to a connection (after a restart, or when its connection was closed) offers Connect to <name> and never connects by itself.
  • Notebooks of Python or any other language are refused with the language named. Only SQL notebooks (nbformat 4) open.
  • A file of more than 1,000 cells is refused, with its number of cells: the app opens notebooks of up to 1,000 cells.

Cells

  • Add SQL cell and Add text cell are in the toolbar. Text cells are Markdown: double-click to edit, Escape to show the result. Links in a text cell open only when they are http, https or mailto addresses; an image shows its alt text, not the picture.
  • Hover a cell, or put the keyboard on it, for Run, Move up, Move down, Change to text or SQL, and Delete. A deleted cell comes back with Undo in the notice. From the keyboard, Shift + F10 or the Menu key opens the same actions as a menu, anywhere in the cell (its SQL editor included), and Alt + Up / Alt + Down (Option on a Mac) move a text cell; inside an editor those two keys move the line instead.

Running

  • Run a cell with Cmd/Ctrl+Enter in it, or its Run button. With text selected, only the selection runs. A folded block runs with the rest of the cell.
  • Run All (Cmd/Ctrl+Shift+Enter) runs the SQL cells top to bottom. It stops at the first cell that fails and says which one; the cells after it do not run.
  • Stop cancels the running query and the rest of the run.
  • A notebook has one connection and one database. The database list in the toolbar switches it on MySQL, SQL Server and Oracle; PostgreSQL shows its database as a label.
  • Commit mode, Commit and Rollback work as in a query tab and are shared with the connection's other tabs: a transaction opened in a notebook shows in the query tab on the same connection.
  • With Confirm before execute on, a cell asks before it runs, and Run All asks once for the whole run. On a connection marked Production, the Production guard asks instead (once for Run All, listing the writes), and a cell that only reads asks nothing more and opens no transaction in manual commit.
  • On SQL Server, GO separates batches, as in Azure Data Studio.

Results

  • A result sits under its cell in the same panel as the query editor: grid, filter, chart and pivot, with the row count and timing.
  • A result rebuilt from the file is never run again by the notebook: it offers no Refresh and no aggregation, because the SQL stored with it is not what you see. Run the cell to get a live result, which offers them.
  • A cell with several statements shows a summary of each.

Saving

  • Save (Cmd/Ctrl+S) and Save Script As write the .ipynb file. A notebook with unsaved changes asks Save, Discard or Cancel when its tab closes, alone or with Close Others, Close Tabs to the Right or Close All. A Save while a cell runs leaves the notebook marked changed: save again once the run is over to keep its result.
  • Save results in the file (the More actions menu in the toolbar, on by default) keeps each cell's results: up to 1,000 rows per result and 1 MB per cell. A result cut short says how many rows the file keeps, and a size limit can keep fewer than 1,000 rows of wide text. Clear results removes them. Turn saving off, or clear, before sharing a notebook whose results hold data others should not see.
  • The file names the connection (its name, engine and database), never a host, a login or a password.
  • Open notebooks come back after a restart when Auto-save open tabs is on, from their file with their results. They do not connect until you ask. A notebook with unsaved changes comes back from its cells: each cell still as it was saved shows its results from the file again, and the next Save keeps them; results run after the last Save are not kept. This works for older Jupyter notebooks too, whose cells carry no id: a cell finds its results by its SQL, in order, so a cell you edited, moved or added since the Save shows none. The selected tab is not restored.

Good to know

  • Pooled sessions. Sessions are pooled, so outside a transaction a temporary table (PostgreSQL, MySQL) or a SET or @variable (MySQL, MariaDB) made in one cell may be missing in the next. A PostgreSQL SET holds for the whole session. Put the cells that depend on each other in a transaction (manual commit), or in one cell.
  • Variables are per batch. In T-SQL a variable lives for one batch, and each statement of a cell is its own batch, so DECLARE @n INT = 1; SELECT @n fails in a cell as it does in the editor's Run All. Keep the DECLARE and its use in one statement.
  • Messages. SQL Server PRINT text, and RAISERROR of severity 10 or less, shows under the cell's result, also from a procedure that prints and returns rows (EXEC), and the notebook file keeps it as the cell's stdout output, after the rows.
  • Anonymous blocks and compound statements. An Oracle anonymous block or a MySQL compound statement (BEGIN ... END) in a cell runs as one statement, as in the editor's Run All.
  • Wide results. The 1 MB limit per cell can keep fewer than 1,000 rows of a wide text result. A wide result you scrolled sideways exports as what is visible.

Charts and export

  • Switch a result to a chart with the chart button of its results; the cell keeps the chart, its type and its axes in the file, and reopens on it.
  • Export to HTML (More actions menu) writes the text, the SQL, the result tables and the charts as images in one page, with the errors and statement messages. Links keep only http, https, mailto and in-page anchors. The page follows the reader's light or dark colour scheme; the chart images stay light. The menu entry is greyed out for an empty notebook.
  • Export to PDF draws the cells in the light theme on A4 pages. A cell that fits on the next page is not cut across two; a cell taller than a page continues on the next, between two lines.
  • Limits: the PDF prints a folded block of SQL folded (unfold it first to print it; the HTML always has the whole SQL). A result you scrolled sideways exports as what is visible. The "rows affected" text stored in a saved notebook is in English whatever the app language. The 1 MB limit per cell can keep fewer than 1,000 rows of a wide text result.

Something missing or wrong?

Documentation gaps are bugs. Tell us which page you were reading and what you expected to find.

Send feedback →

Product names, logos and brands mentioned on this page are the property of their respective owners. They are used for identification and comparison only, and their use does not imply any affiliation with or endorsement by them.