DB Notebooks are individual, complex documents that when combined with a connection to MySQL and a special-purpose editor provide you with a tool for producing graphical result views and charts. Each DB Notebook's queries, code, and output are stored only for the current session. If you close a notebook editor or a connection tab that has multiple notebook editors, your work is lost.
Optionally, you can save and reload a DB Notebook in a way that persists the queries or code, result sets, the last editor state (the last caret position, scroll position and selection of the code editor, and so on). Effectively, you can save a notebook session as a notebook file. When you load the file, all execution blocks are restored in the exact same order with the exact same size as they were when the notebook was last saved.
Saved notebook files enable you to:
Suspend and resume ongoing work in complex scenarios.
Keep important sets for reuse later in demonstrations or classroom instruction.
Share sets with team members for review and discussion.
Organize notebooks within a larger project.
Restore or repurpose a session created by another user.
Notebook files have a new file type
(mysql-notebook), which represents a special
JSON document with just enough data to restore the notebook.
MySQL Shell for VS Code implements a custom editor for these files
that permits synchronization between a notebook file and a
notebook editor. With this level of synchronization, you can
persist and reactivate a notebook file from within an active
connection tab, a standalone notebook file tab, or both. The
specific structure of the JSON file provides a type field to
identify it and a version field to permit updates to it
seamlessly, if required. These fields make notebook files
source-code management friendly and easy to compare.
Notebook files require a connection. It can be the connection configured in the extension settings (default connection) or, if none is set, you are prompted to select one. If the connection being used by a notebook tab becomes unavailable, the notebook file closes after saving the document automatically, if necessary. This type of interruption can occur if you:
Remove the connection.
Select a different profile.
Connect to a different MySQL Shell process (or the process stops).
The connection you select is stored in the extension state, based on the URL of the notebook file and it is used the next time you open the notebook file. If the connection no longer exists, MySQL Shell for VS Code removes it from the extension state and prompts you to select a new one.
A notebook file tab is similar to a connection tab, except that
the a notebook file tab permits only one active editor. In
contrast, a connection tab can include multiple notebook and
single-language script editors. Because it has just one file
editor, the notebook file tab omits the
Editor drop-down list from the toolbar and
adds an active breadcrumb list showing the path of the open file.
The figure that follows shows an open notebook file tab (and
toolbar) for a file named
sakila-actor.mysql-notebook in a folder named
Samples.
File-tab toolbar operations are identical to those of the connection-tab toolbar (see Section 4.4, “DB Notebook Toolbar”).
To save an original DB Notebook session:
In a connection tab, create a DB Notebook session with the original queries and result sets to be saved.
-
Click the Save this Notebook icon to open a file-selector dialog.
In the dialog, specify a file name and, optionally, a different workspace or folder. The file type defaults to
.mysql-notebookautomatically.Click to persist the active DB Notebook session as a file.
To save an existing notebook file:
-
Load the notebook file to be modified and saved using one of the following options (see Load a notebook from a file for instructions):
In a connection tab
In a notebook file tab
-
Modify the notebook content in the editor as needed and then click the Save this Notebook icon. In most cases, a file-selector dialog opens.
(If the file is newer than the active notebook session, you might be prompted to compare or overwrite the file.)
In the dialog, select a notebook file (
filename.mysql-notebookIf prompted, confirm that you want to replace the existing file.
The notebook file tab supports using the standard Ctrl+S (or Command+S) keyboard shortcut to save the file.
To load a notebook file into a connection tab:
-
From the MySQL Shell for VS Code container view, open a DB connection.
-
From the connection tab's toolbar, click the Load a new Notebook from a file icon to open a file-selector dialog.
In the dialog, navigate to the location of your file. Valid notebook files have a
.mysql-notebookfile extension.-
Select the file and click .
The selected notebook file replaces the previous DB Notebook in the editor. In addition, the OPEN EDITORS view adds a new DB Notebook (
n) entry to the listing for the connection.
To load a notebook file into a standalone file tab:
-
Locate the notebook file (
filename.mysql-notebook-
In Visual Studio Code, navigate to the notebook file by selecting the Explorer icon from the activity bar (Ctrl+Shift+E).
NoteVisual Studio Code might prompt you to set up a folder first.
Open the file selector provided by your computer's operating system and navigate to the notebook file.
-
-
Depending on the context, click or double-click the file. From Explorer in the activity bar, right-click the file and select under .
This action loads the persisted session (and all data) into a standalone file tab. It is possible to modify and save the session again, or to load a different saved notebook file into the tab.
To load a notebook file as a text file:
-
In Visual Studio Code, navigate to the notebook file by selecting the Explorer icon from the activity bar (Ctrl+Shift+E).
-
Right-click the file and select under .
Changes made in the plain text editor are not saved to the file.