MySQL Workbench Manual  /  Configuration  /  Tutorial: Add a Custom Link to the Home Screen

3.4 Tutorial: Add a Custom Link to the Home Screen

This tutorial introduces the concept of altering the MySQL Workbench home screen by adding your own shortcut link. Specifically, the tutorial adds a shortcut titled "Example" that opens "" as a browser tab inside MySQL Workbench.


Although adding a link to the home screen is not a common need, this tutorial is an example that demonstrates the idea of customizing MySQL Workbench.

First, create an icon for your shortcut. This step is optional, and the following table compares the icon used in this tutorial and the default icon if a custom icon is not defined.

Table 3.3 MySQL Workbench Home Screen Icons

Default Icon Our Example Icon

Save your new 52x52 pixel image to a location accessible by MySQL Workbench. The following table indicates the default path by operating system where the source icons are stored.

Table 3.4 Default Path for Home Screen Icons

Operating System File Path
Windows "C:\Program Files (x86)\MySQL\MySQL Workbench CE 8.0.15\images\home\
macOS /Applications/
Linux /usr/share/mysql-workbench/images/

Next, open starters_settings.xml (this file is located under your user's MySQL Workbench directory) and add an entry for your new shortcut ID where the order determines the location on the home screen. Follow the standard convention by appending your value to "com.mysql.wb.starter.", this tutorial uses "example":

<link type="object">com.mysql.wb.starter.example</link>

Lastly, open predefined_starters.xml and add a new "app.Starter" entry.

Table 3.5 Default Path to predefined_starters.xml

Operating System File Path
Windows "C:\Program Files (x86)\MySQL\MySQL Workbench CE 8.0.15\data\
macOS /Applications/
Linux /usr/share/mysql-workbench/data/

This tutorial does not describe this entry in detail, so consider it as a self-explanatory template for now. The important concepts include using the ID you defined in the previous step, your own URL for the "command", and "smallIcon" as a 52x52 pixel image that is displayed on the MySQL Workbench home screen. Adjust these entries according to your needs, including the path to your icon.

<value type="object" struct-name="app.Starter" id="com.mysql.wb.starter.example">
 <value type="string" key="type">Website</value>
 <value type="string" key="title">Example</value>
 <value type="string" key="description">My wonderful</value>
 <value type="string" key="publisher">Example Inc.</value>
 <value type="string" key="authorHome"></value>
 <value type="string" key="smallIcon">/usr/local/share/wb-home-screen-example-icon.png</value>
 <value type="string" key="command">browse:</value>

Upgrading MySQL Workbench will overwrite these changes, because predefined_starters.xml is stored inside the MySQL Workbench installation directory, and starters_settings.xml is reset during installation. Consider saving copies of these changes for future reference.

Restart MySQL Workbench to see the new link on your MySQL Workbench home screen.

Additional "app.Starter" options include:

Require a specific edition of Workbench:
    <value type="string" key="edition">ce</value>
    <value type="string" key="edition">se</value>

Require a specific version (or higher) of Workbench:
  <value type="string" key="introduction">6.1.0</value>

User Comments
User comments in this section are, as the name implies, provided by MySQL users. The MySQL documentation team is not responsible for, nor do they endorse, any of the information provided here.
Sign Up Login You must be logged in to post a comment.