By default SQL Workbench/J will use a file with the name WbMacros.xml stored in the configuration directory to save and load the macros.

To create a copy of the currently loaded macros, use Macros → Save Macros as.... To load previously saved macros, use Macros → Load Macros....

The currently loaded file is displayed as a tool tip of the Save Macros as... menu item and and the bottom of the Manage Macros dialog.

	A set of macros is always loaded globally, not just for the current window. If you have more than one window open, the newly loaded macros will also be active in all the other windows.

There are three ways to define a SQL macro.

If the current statement in the editor should be defined as a macro, select (highlight) the statement's text and select Macros → Add SQL macro from the main menu. You will be prompted to supply a name for the new macro. If you supply the name of an existing macro, the existing macro will be overwritten.

Alternatively you can add a new macro through Macros → Manage Macros.... This dialog can also be used to delete and and edit existing macros. You can put macros into separate groups (e.g. one for PostgreSQL macros, one for Oracle etc). If you have only one group defined (or only one visible group), all macros of that group will be listed in the menu directly. If you define more than one group, each group will appear as a separate sub-menu.

Macros can also be defined using the command WbDefineMacro.

When the dialog is closed using the OK button the macros are automatically saved to the current file.

The order in which the macros (or groups) appear in the menu can be changed by dragging them to the desired position in the manage macro dialog.

There are two ways to run an executable macro: use it's name as a SQL command by typing it into the editor and executing it like any other SQL statement. Or by selecting the corresponding menu entry from the Macros menu.

Note that the macro name needs to be unique to be used as a "SQL Statement". If you have two different macros in two different macro groups with the same name, it is undefined (i.e. "random") which of them will be executed.

To view the complete list of macros select Macros → Manage Macros... After selecting a macro, it can be executed by clicking on the Run Run button. If you check the option "Replace current SQL", then the text in the editor will be replaced with the text from the macro when you click on the run button.

In console mode you can use the command WbListMacros to show the complete list of macros (of course this can also be used in GUI mode as well.

	Macros will not be evaluated when running in batch mode.

Apart from the SQL Workbench/J script variables for SQL Statements, additional "parameters" can be used inside a macro definition. These parameters will be replaced before replacing the script variables.

The SQL statement that is eventually executed will be logged into the message panel when invoking the macro from the menu. Macros that use the above parameters cannot correctly be executed by entering the macro alias in the SQL editor (and then executing the "statement").

	The parameter keywords are case sensitive, i.e. the text ${SELECTION}$ will not be replaced!

This feature can be used to create SQL scripts that work only with with an additional statement. e.g. for Oracle you could define a macro to run an explain plan for the current statement:

explain plan
for
${current_statement}$
;

-- @wbResult Execution plan
select plan_table_output
from table(dbms_xplan.display(format => 'ALL'));

When you run this macro, it will run an EXPLAIN PLAN for the statement in which the cursor is currently located, and will immediately display the results for the explain. Note that the ${current_statement}$ keyword is terminated with a semicolon, as the replacement for ${current_statement}$ will never add the semicolon. If you use ${selection}$ instead, you have to pay attention to not select the semicolon in the editor before running this macro.

For PostgreSQL you can define a similar macro that will automatically run the EXPLAIN command for a statemet:

explain (analyze true, verbose true, buffers true) ${current_statement}$;

Another usage of the parameter replacement could be a SQL Statement that retrieves the rowcount that would be returned by the current statement:

SELECT count(*) FROM
(
${current_statement}$
)

Expandable macros are not intended to be run directly. They serve as code templates for writing statements.

When typing the name of the macro in the editor and completing this name with the "Macro expansion key", the typed word will be replaced with the macro's text. The name of a such a macro is not case sensitive. So slt and SLT are detected as the same macro name.

The macro expansion is only triggered if the macro expansion key is typed quickly after the word. If there is a longer pause between typing the last character of the macro's name and typing the expansion key, the macro will not be expanded.

For expandable macros, two special place holders in the macro text are supported. Both place holders are deleting when the macro text is inserted.