Configuring External Tools in SQLDeveloper

In order to distract myself from the lunacy that is the ongoing UK General Election campaign, I’ve been continuing to spend some quality time with the Swiss Army Knife of the Oracle world, SQLDeveloper.
I know, conventional wisdom says that when you have a hammer, everything is a nail.
On the other hand, conventional wisdom is rather less forthcoming if instead you have a multi-tool of Central European origin.
Fortunately, SQLDeveloper pays no heed to conventional wisdom but allows you to configure callouts to other useful software utilities by means of it’s External Tools functionality.
What we’re going to look at here is :

  • Adding a call to an external tool in SQLDeveloper
  • Using macros to control the behaviour of an External Tool
  • Configuration settings for common tools in Windows
  • Configuration settings for common tools in Ubuntu

Setup External Tools

In the Tools menu, select External Tools.
If you’re on Windows, you can kick-start matters by clicking the Find Tools button.
This will configure :

  • Notepad
  • Internet Explorer
  • Word (if available)

This option is not available on Ubuntu, which is where I am at the moment so…

Adding a new tool

I’m going to start with the equivalent to Notepad on Ubuntu.
I feel I should apologise to the noble Gedit for that last sentence.
From the Tools menu select External Tools :

Click New.

Now we need to enter the location of the program we want to run. As we’re on Linux, we can find this out easily enough :

which gedit

If we have a file in focus when we call this editor we’d like Gedit to open it. We’d also like it to use the directory in which that file is located.
We can achieve this using some of the macros available to us. In the Argument field, click Insert. Now click on File Name :

Click OK and we can see that the field now has a value of :


We’re going to use a macro for the Run Directory as well. In this case we’ll select the File Directory macro which gives us a Run Directory value of


After all that the dialog looks like this :

Click Next

Next we can configure how the tool is displayed in SQLDeveloper. We’ll leave the caption as is. We’ll add a tooltip though.
Oh, and the icon is currently set to the SQLDeveloper default for External Tools.
On Windows, SQLDeveloper is usually smart enough to derive the appropriate icon from a fully qualified path to the executable. On Ubuntu, we need to point it in the right direction.
We also need to be a bit careful about the size of the icon file we choose otherwise SQLDeveloper will complain with something like :

Fortunately, Ubuntu tends to put suitably sized icons for it’s applications in :


…less fortunately, the one for Gedit isn’t called gedit.png. Anyhow, what we end up with is :

Next, we want to determine where Gedit will be available.
As well as the main Tools menu, we’d like it to be on the context menus and the main toolbar.
We don’t want to log output messages :

I’m going to leave the Availability settings at the default :

Finally click Finish, then close the External Tools window.

Now, if I have a file in focus, I can open it in Gedit :

Macro Definitions

In addition to External Tool configuration, these macros can be used elsewhere in SQLDeveloper to configure various preferences. For example, to set your Worksheet default path to be the same directory as the file that you have open at any point in time, you’d use


You can get an idea of the value of certain macros when you select them in the External Tool setup dialog:

The complete list of macros – at least – all of those available in the External Tool config dialog- is :

Macro Description syntax
DB Connection String Database Connection String ${sqldev.conn}
DB UserName Database username ${sqldev.dbuser}
Environment Variable The value of an environment variable The var attribute specifies the name of the environment variable ${env:var=PATH}
File Directory The directory containing the currently selected file ${file.dir}
File Extension The extension of the currently selected file ${file.ext}
File Name The name of the currently selected file ${}
File Name Without Extension The basename of the currently selected file ${}
File Path Full path of the currently selected file ${file.path}
File URL The URL of the currently selected file ${file.url}
IDE Application Name The name of this application ${}
IDE Classpath The full classpath of this application ${ide.classpath}
IDE Install Directory The directory in which this application is installed ${ide.dir}
IDE Oracle Home Directory The oracle home directory in which this application is installed. ${}
IDE User directory The user directory ${ide.user.dir}
Prompt Displays a prompt at runtime to allow user to specify an argument value ${prompt}
Prompt with Label Prompt user for a value. The label attribute specifies a label to display in the prompt dialog ${promptl:=prompt text}
System Property The value of a system property. The name attribute specifies the name of the system property ${prop:name=property}

Configuration details for common Windows tools

Here’s a list of configurations that work for me on Windows 10.
There are a couple of things that may help on Windows when looking for the information required to configure an external tool.
First, if you’re unsure as to the location fo the executable of the program you need to run, you can simply run it and then open Task Manager and right-click it. This will give you the exe name and path.
Second, whilst executables that are in your path do not require a fully qualified path name for SQLD to find them, it will usually need the full path to use the normal icon for that program.

Tool Executable Arguments Run Directory Icon Location
Windows Explorer C:\Windows\explorer.exe /select,${file.path}
Notepad++ C:\Program Files(x86)\Notepad++\notepad++.exe ${file.path} ${file.dir}
Git Bash C:\Program Files\Git\git-bash.exe ${file.dir}
Putty C:\Program Files(x86)\PUTTY\putty.exe
Excel C:\PROGRA~1\MICROS~1\Office16\EXCEL.EXE ${file.path} ${file.dir}
FileZilla C:\Program Files\FileZilla FTP Client\filezilla.exe “-a ${file.path}”
Snipping tool C:\Windows\system32\SnippingTool.exe ide.fileicon.file:/C:/Windows/system32/SnippingTool.exe
Notepad notepad.exe ${file.path} ${file.dir} ide.fileicon.file:/C:/Windows/system32/notepad.exe

Configuration details for common Ubuntu tools

Things are slightly different on Ubuntu, No, I’m not about to go into a chauvanistic rant about the innate superiority of life with the Penguins – although I’ve not included Git Bash in this list because Ubuntu has proper Bash…

Tool Executable Arguments Run Directory Icon Location
Nautilus /usr/bin/nautilus ${file.dir} /usr/share/icons/gnome/16×16/apps/file-manager.png
Gedit /usr/bin/gedit ${} ${file.dir} /usr/share/icons/gnome/16×16/apps/accessories-text-editor.png
Terminal /usr/bin/gnome-terminal ${file.dir} /usr/share/icons/gnome/16×16/apps/gnome-terminal.png
LibreOffice Calc /usr/bin/libreoffice –calc ${} ${file.dir} /usr/share/icons/gnome/16×16/apps/calc.png
FileZilla /usr/bin/filezilla “-a ${file.path}” /usr/share/filezilla/resources/16×16/filezilla.png
VS Code /usr/bin/code ${} ${file.dir}
Screenshot /usr/bin/gnome-screenshot /usr/share/icons/gnome/16×16/apps/applets-screenshooter.png

Note that I couldn’t fine an appropriately sized icon for VS Code.

Well that’s used up some time, but there’s still a month to go until the election. I’ll have to find something else to distract myself with.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.