Pre-General Availability: 2024-05-02

4.7 Persist and Load Notebook Files

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.

Figure 4.8 MySQL Shell for VS Code - Notebook File Tab and Toolbar

File-tab toolbar operations are identical to those of the connection-tab toolbar (see Section 4.4, “DB Notebook Toolbar”).

Save an active notebook to a file

To save an original DB Notebook session:

1. In a connection tab, create a DB Notebook session with the original queries and result sets to be saved.

2. Click the Save this Notebook icon to open a file-selector dialog.

   

3. In the dialog, specify a file name and, optionally, a different workspace or folder. The file type defaults to .mysql-notebook automatically.

4. Click Save Notebook to persist the active DB Notebook session as a file.

To save an existing notebook file:

1. 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

2. 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.)

3. In the dialog, select a notebook file (filename.mysql-notebook) and then click Save Notebook.

4. If prompted, confirm that you want to replace the existing file.

Tip

The notebook file tab supports using the standard Ctrl+S (or Command+S) keyboard shortcut to save the file.

Load a notebook from a file

To load a notebook file into a connection tab:

1. From the MySQL Shell for VS Code container view, open a DB connection.

   

2. From the connection tab's toolbar, click the Load a new Notebook from a file icon to open a file-selector dialog.

   

3. In the dialog, navigate to the location of your file. Valid notebook files have a .mysql-notebook file extension.

4. Select the file and click Open Notebook.

   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:

1. Locate the notebook file (filename.mysql-notebook) to load in one of the following ways:

   • In Visual Studio Code, navigate to the notebook file by selecting the Explorer icon from the activity bar (Ctrl+Shift+E).

     

     Note

     Visual 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.

2. Depending on the context, click or double-click the file. From Explorer in the activity bar, right-click the file and select MySQL Notebook Editor under Open With.

   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:

1. In Visual Studio Code, navigate to the notebook file by selecting the Explorer icon from the activity bar (Ctrl+Shift+E).

   

2. Right-click the file and select Text Editor under Open With.

   Changes made in the plain text editor are not saved to the file.