14. Using macros and text clips
Prev |  | Next

## 14. Using macros and text clips

SQL macros and text clips can help writing and executing SQL statements that you use frequently.

There are two types of macros:

- executable macros
- expandable macros

Executable macros are intended for complete SQL statements that are executed once you select/run the macro. They can also be used as an abbreviated SQL statement, by typing the macro's name and executing this as a SQL statement.

Expandable macros are intended for SQL fragments (or "clips"). The text of the macro is inserted into the editor if the name is typed or the macro is selected from the menu.

### 14.1. Loading and saving macro sets

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.

It is possible to use a different set of macros for each connection profile. In that case the global/default macros are not loaded, only those specified in the connection profile.

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.

Starting with build 129 macros can optionally be stored as SQL scripts in a directory, to make sharing of the SQL statements in the macros easier. Each sub-directory in the selected directory represents one macro group.

When using the directory based storage, it's possible to use symbolic links in the filesystem to make a macro group available for multiple sets of macros. This can be used to e.g. include multi-purpose scripts in a set of macros specific to one DBMS.

### 14.2. Defining Macros

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.

### 14.3. Executable macros

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.

Parameter | Description
--- | ---
${selection}$ | This parameter will be replaced with the currently selected text. The selected text will not be altered in any way.
${selected_statement}$ | This behaves similar to `${selection}$` except that any trailing semicolon will be removed from the selection. Thus the macro definition can always contain the semicolon (e.g. when the macro actually defines a script with multiple statements) but when selecting the text, you do not need to worry whether a semicolon is selected or not (and would potentially break the script).
${current_statement}$ | This key will be replaced with the current statement (without the trailing delimiter). The current statement is defined by the cursor location and is the statement that would be executed when using SQL → Execute current
${text}$ | This key will be replaced with the complete text from the editor (regardless of any selection).

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}$
    )

### 14.4. Expandable macros

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.

Parameter | Description
--- | ---
${c} | This parameter marks the location of the cursor after the macro is expanded.
${s} | This parameter also marks the position of the cursor after expansion. Additionally the word on the right hand side of the parameter will automatically be selected.

### 14.5. DbTree macros

The third type of macros is intended to be used in the DbTree. The macros will be available from the context menu for tables and columns in the DbTree.

Inside the macro definition the following parameters will be replaced:

Parameter | Description
--- | ---
${table}$ | This will be replaced with the qualified name of the selected table. Depending on the context, this might be replaced with a fully qualified name (including schema or database).
${table_name}$ | This will be replaced with the name of the table. No qualifying prefix (schema, database) will be used.
${schema_name}$ | This will be replaced with the name of the schema in which the table is defined.
${catalog_name}$ | This will be replaced with the name of the catalog in which the table is defined. `${db_name}` is an alternative writing for this placeholder.
${column_list}$ | This will be replaced with a comma separated list of the names of all selected columns. The order in which the columns are listed might depend on the used Java version and operating system.
${column}$ | This will be replaced with the name of selected column if exactly one column is selected.
${column_N}$ | This will be replaced with the name of n-th select column if more than one column is selected. So `${column_1}$` will be replaced with the first column, `${column_2}$` with the second column and so on. The order in which the columns are listed might depend on the used Java version and operating system.

Prev |  | Next
13. Using SQL Workbench/J specific annotations in SQL comments | Home | 15. Working with foreign keys