29. Other SQL Workbench/J specific commands
Prev |  | Next

## 29. Other SQL Workbench/J specific commands

All SQL Workbench/J specific command can only be used from within SQL Workbench/J

### 29.1. Confirm script execution - WbConfirm

The `WbConfirm` command pauses the execution of the current script and displays a message. You can then choose to stop the script or continue.

`WbConfirm` can be called in three different ways:

- Without any parameter, then a default message will be displayed

- With just a message text, e.g. `WbConfirm Do you really want to drop everything?`

- Supplying parameters for the message, the text for the "Yes" choice and the text for the "No" choice using standard SQL Workbench/J parameters:

  `WbConfirm -message="Do you really want to drop everything?" -yesText="OK, go ahead" -noText="No, please stop"`

When using `WbConfirm` in console (or interactive batch) mode, the check if the "Yes" choice was typed by the user is done by testing if the "Yes" value starts with the text the user enters (ignoring upper/lowercase differences). So if the "Yes text" is set to `"Continue"`, the user can enter `c`, `co`, `cont` and so on. Because of that, the "No" text should not start with the same letters as the "Yes" text. When using `-yesText=Continue and -noText=Cancel` and the user enters `C`, this would be regarded as a "Yes".

This command can be used to prevent accidental execution of a script even if confirm updates is not enabled.

This command has no effect in batch mode unless the `-interactive` parameter was specified.

### 29.2. Display a message box - WbMessage

The `WbMessages` command pauses the execution of the current script and displays a message and waits until the dialog is closed. Unlike `WbConfirm` the script will always continue once the message dialog is closed.

`WbMessage` can be called in two different ways:

- With just a message text, e.g. `WbMessage Done!`

- Supplying parameters for the message and the dialog title:

  `WbMessage -message="Script finished" -title="SQL Script"`

This command has no effect in batch or console mode.

### 29.3. Print a text - WbEcho

The command `WbEcho` can be used to print messages. The following statement:

    WbEcho The answer is: 42

will print the text "The answer is: 42" to the message pane in GUI mode, or to the console in batch or console mode.

If `WbEcho` is used in a script that is executed with `WbInclude` and the `-verbose=false` option, the message will not be displayed. To display a message even if verbose mode is disabled, prefix the text with two exclamation marks: `!!`, e.g.:

    WbEcho !! Dropping all tables!

### 29.4. Run a stored procedure with OUT parameters - WbCall

If you want to run a stored procedure that has `OUT` parameters, you have to use the `WbCall` command to correctly see the returned value of the parameters.

Consider the following (Oracle) procedure:

    CREATE OR REPLACE procedure return_answer(answer OUT integer)
    IS
    BEGIN
      answer := 42;
    END;
    /

To call this procedure you need to supply a placeholder indicating that a parameter is needed.

    SQL> WbCall return_answer(?);
    PARAMETER | VALUE
    ----------+------
    ANSWER    | 42

    (1 Row)
    Converted procedure call to JDBC syntax: {call return_answer(?)}
    Execution time: 0.453s
    SQL>

#### Stored procedures with REF CURSORS

If the stored procedure has a REF CURSOR (as an output parameter), `WbCall` will detect this, and retrieve the result of the ref cursors.

Consider the following (Oracle) stored procedure:

    CREATE PROCEDURE ref_cursor_example(pid number, person_result out sys_refcursor, addr_result out sys_refcursor) is
    BEGIN
        OPEN person_result FOR
          SELECT *
          FROM person
          WHERE person_id = pid;

        OPEN addr_result FOR
          SELECT a.*
          FROM address a JOIN person p ON a.address_id = p.address_id
          WHERE p.person_id = pid;
    END;
    /

To call this procedure you use the same syntax as with a regular OUT parameter:

    WbCall ref_cursor_example(42, ?, ?);

SQL Workbench/J will display two result tabs, one for each cursor returned by the procedure. If you use `WbCall ref_cursor_example(?, ?, ?)` you will be prompted to enter a value for the first parameter (because that is an IN parameter).

#### PostgreSQL functions that return a refcursor

When using ref cursors in PostgreSQL, normally such a function can simply be used inside a SELECT statement, e.g. `SELECT * FROM refcursorfunc();`. Unfortunately the PostgreSQL JDBC driver does not handle this correctly and you will not see the result set returned by the function.

To display the result set returned by such a function, you have to use `WbCall` as well

    CREATE OR REPLACE FUNCTION refcursorfunc()
      RETURNS refcursor
    AS
    $$
    DECLARE
        mycurs refcursor;
     BEGIN
        OPEN mycurs FOR SELECT * FROM PERSON;
        RETURN mycurs;
     END;
    $$ LANGUAGE plpgsql;
    /

You can call this function using

    WbCall refcursorfunc();

This will then display the result from the SELECT inside the function.

### 29.5. Execute a SQL script - WbInclude (@)

With the `WbInclude` command you run SQL scripts without actually loading them into the editor, or call other scripts from within a script. The format of the command is `WbInclude -file=filename;`. For DBMS other then MS SQL, the command can be abbreviated using the @ sign: `@filename;` is equivalent to `WbInclude -file=filename;`. The called script way may also include other scripts. Relative filenames (e.g. as parameters for SQL Workbench/J commands) in the script are always resolved to the directory where the script is located, not the current directory of the application.

The reason for excluding MS SQL is, that when creating stored procedures in MS SQL, the procedure parameters are identified using the @ sign, thus SQL Workbench/J would interpret the lines with the variable definition as the WbInclude command. If you want to use the @ command with MS SQL, you can configure this in your `workbench.settings` configuration file.

If the included SQL script contains `SELECT` queries, the result of those queries will not be displayed in the GUI unless `-displayResult=true` is used.

The long version of the command accepts additional parameters. When using the long version, the filename needs to be passed as a parameter as well.

Only files up to a certain size will be read into memory. Files exceeding that size will be processed statement by statement. In this case the automatic detection of the alternate delimiter will not work. If your scripts exceed the maximum size and you do use the alternate delimiter you will have to use the long version of the command using the `-file` and `-delimiter` parameters.

`WbInclude` supports conditional execution

The command supports the following parameters:

Parameter | Description
--- | ---
-file | The filename of the file to be included.
-continueOnError | Defines the behavior if an error occurs in one of the statements. If this is set to `true` then script execution will continue even if one statement fails. If set to `false` script execution will be halted on the first error. The default value is `false`
-delimiter | Specify a delimiter to be used that is different from the standard `;` delimiter. A non-standard delimiter will be required to be on a line of its own. If you specify `-delimiter=/` the following will work:
    select *
    from person
    /
but putting the delimiter at the end of a line will not work:
    select *
    from person/
If this parameter is not specified, the SQL standard `;` delimiter will be used.
-encoding | Specify the encoding of the input file. If no encoding is specified, the default encoding for the current platform (operating system) is used.
-verbose | Controls the logging level of the executed commands. `-verbose=true` has the same effect as adding a `WbFeedback on` inside the called script. `-verbose=false` has the same effect as adding the statement `WbFeedback off` to the called script.
-displayResult | By default any result set that is returned e.g. by a `SELECT` statement in the script will not be displayed. By specfying `-displayResult=true` those results will be displayed.
-printStatements | If true, every SQL statement will be printed before execution. This is mainly intended for console usage, but works in the GUI as well.
-showTiming | If true, display the execution time of every SQL statement and the overall execution time of the script.
-useSavepoint | Control if each statement from the file should be guarded with a savepoint when executing the script. Setting this to `true` will make execution of the script more robust, but also slows down the processing of the SQL statements.
-ignoreDropErrors | Controls if errors resulting from DROP statements should be treated as an error or as a warning.
-searchFor -replaceWith -ignoreCase -useRegex | Defines search and replace parameters to change the SQL statements before they are sent to the database. This can e.g. be used to replace the schema name in DDL script that uses fully qualified table names. The replacement is done without checking the syntax of the statements. If the search value is contained in a string literal or a SQL comment, it is also replaced.

#### 29.5.1. Examples

Execute `my_script.sql`

    @my_script.sql;

Execute `my_script.sql` but abort on the first error

    WbInclude -file="my_script.sql" -continueOnError=false;

Execute the script `create_tables.sql` and change all occurances of `oldschema` to `new_schema`

    WbInclude -file=create_tables.sql -searchFor="oldschema." -replaceWith="new_schema."

Execute a large script that uses a non-standard statement delimiter:

    WbInclude -file=insert_10million_rows.sql -delimiter='/';

### 29.6. Conditional execution

The following SQL Workbench/J commands support conditional execution based on variables:

- WbInclude
- WbCopy
- WbImport
- WbExport
- WbSysExec
- WbRunResult
- WbVarDef
- WbConfirm

Conditional execution is controlled using the following parameters:

Parameter | Description
--- | ---
-ifDefined | The command is only executed if the variable with the specified name is defined. `-ifDefined=some_var`
-ifNotDefined | The command is only executed if the variable with the specified name is not defined. `-ifNotDefined=some_var`
-ifEquals | The command is only executed if the specified variable has the specified value `-ifEquals='some_var=42'`
-ifNotEquals | The command is only executed if the specified variable does not have the specify value `-ifNotEquals='some_var=42'`
-ifEmpty | The command is only executed if the specified variable is defined but has an empty value `-ifEmpty=some_var`. This is essentially a shorthand for `-ifEquals="some_var=''"`
-ifNotEmpty | The command is only executed if the specified variable is defined and has a non empty value `-ifNotEmpty=some_var`. This is essentially a shorthand for `-ifNotEquals="some_var=''"`
-ifFileExists | The command is only executed if the specified file exists (on the computer running ) `-ifFileExists=/data/export/text`.
-ifNotFileExists | The command is only executed if the specified file does not exist (on the computer running ) `-ifFileExists=/data/export/text`.
-ifTableExists | The command is only executed if the specified table exists `-ifTableExists=person`.
-ifNotTableExists | The command is only executed if the specified table does not exist. `-ifNotTableExists=person`.
-isDBMS | The command is only executed if the current connection is against the specified DBMS. The value supplied is the DBID that is used internally by SQL Workbench/J, e.g. `-isDBMS=postgresql` This parameter supports auto-completion.
-isNotDBMS | The command is only executed if the current connection is not against the specified DBMS. The value supplied is the DBID that is used internally by SQL Workbench/J e.g. `-isNotDBMS=postgresql` This parameter supports auto-completion.

### 29.7. Run a result set as a SQL script - WbRunResult

`WbRunResult` can be used to execute the result of a query as a SQL script. Each row in the result is assumed to be a single statement. This is e.g. useful to generate scripts dynamically without having to use dynamic SQL in a procedural language like PL/pgSQL or PL/SQL.

From the result of the generating script, only the first column will be used. If the statement generated more columns, the additional columns are ignored. Each generated statement should end with a `;` character.

`WbRunResult` supports conditional execution

The command supports the following parameters:

Parameter | Description
--- | ---
-query | The query that generates the script. If this parameter is not provided, the SQL query following `WbRunResult` will be used as the input. This is similar to the way as WbExport works.
-dryRun | If true, the generated script won't be executed, only the result will be displayed. This can be used to inspect the generated statements for actually running them. This is useful when providing the query through the `-query` parameter, not as a separate statement that could be run on its own.
-continueOnError | If true, the script execution does not stop on the first error. This is the same as the `-continueOnError` parameter for WbInclude.
-verbose | Controls the feedback during script execution. This is the same as the `-verbose` parameter for WbInclude.
-ignoreDropErrors | Don't stop executing the script if a `DROP` statement results in an error. This is the same as the `-ignoreDropErrors` parameter for WbInclude.
-printStatements | Print each statement while the script is processed. This is the same as the `-printStatements` parameter for WbInclude.
-showTiming | Print execution statistics for each statement. This is the same as the `-showTiming` parameter for WbInclude.
-showProgress | Report the current statement nummer in the statusbar.

The following script will drop all tables that end with `_backup`:

    WbRunResult -showProgress -showTiming;
    SELECT concat('DROP TABLE ', table_schema, '.', table_name, ';') as ddl
    FROM information_schema.tables
    WHERE table_name LIKE '%\_backup' ESCAPE '\';

### 29.8. Extract and run SQL from a Liquibase ChangeLog - WbRunLB

If you manage your stored procedures in Liquibase ChangeLogs, you can use this command to run the necessary SQL directly from the XML file, without the need to copy and paste it into SQL Workbench/J. This is useful when testing and developing stored procedures that are managed by a Liquibase changeLog.

This is NOT a replacement for Liquibase. `WbRunLB` will only extract SQL statements stored in `<sql>` or `<createProcedure>` tags or scripts referenced through the `<sqlFile>` tag. It will not convert any of the Liquibase tags to "real" SQL. `WbRunLB` will NOT update the Liquibase log table (`DATABASECHANGELOG`) nor will it check if the specified changeSet(s) have already been applied to the database. It is merely a convenient way to extract and run SQL statements stored in a Liquibase XML file!

The attribute `splitStatements` for the `sql` tag is evaluated. The delimiter used to split the statements follows the usual SQL Workbench/J rules (including the use of the alternate delimiter).

`WbRunLB` supports the following parameters:

Parameter | Description
--- | ---
-file | The filename of the Liquibase changeLog (XML) file. The `<include>` tag is NOT supported! SQL statements stored in files that are referenced using Liquibase's `include` tag will not be processed.
-changeSet | A list of changeSet ids to be run. If this is omitted, then the SQL from all changesets (containing supported tags) are executed. The value specified can include the value for the author and the id, `-changeSet="Arthur::42"` selects the changeSet where `author="Arthur"` and `id="42"`. This parameter can be repeated in order to select multiple changesets: `-changeSet="Arthur::42" -changeSet="Arthur::43"`. You can specify wildcards before or after the double colon: `-changeSet="*::42"` will select all changesets with the id=42. `-changeSet="Author::*"` will select all changesets from "Arthur" If the parameter value does not contain the double colon it is assumed to be an ID only: `-changeSet="42"` is the same as `-changeSet="*::42"` If this parameter is omitted, all changesets are executed. This parameter supports auto-completion if the `-file` argument is specified.
-continueOnError | Defines the behaviour if an error occurs in one of the statements. If this is set to `true` then script execution will continue even if one statement fails. If set to `false` script execution will be halted on the first error. The default value is `false`
-encoding | Specify the encoding of the input file. If no encoding is specified, UTF-8 is used.

### 29.9. Handling tables or updateable views without primary keys

#### 29.9.1. Define primary key columns - WbDefinePK

To be able to directly edit data in the result set (grid) SQL Workbench/J needs a primary key on the underlying table. In some cases these primary keys are not present or cannot be retrieved from the database (e.g. when using updateable views). To still be able to automatically update a result based on those tables (without always manually defining the primary key) you can manually define a primary key using the `WbDefinePk` command.

Assuming you have an updateable view called `v_person` where the primary key is the column `person_id`. When you simply do a `SELECT * FROM v_person`, SQL Workbench/J will prompt you for the primary key when you try to save changes to the data. If you run

    WbDefinePk v_person=person_id

before retrieving the result, SQL Workbench/J will automatically use the `person_id` as the primary key (just as if this information had been retrieved from the database).

To delete a definition simply call the command with an empty column list:

    WbDefinePk v_person=

If you want to define certain mappings permanently, this can be done using a mapping file that is specified in the configuration file. The file specified has to be a text file with each line containing one primary key definition in the same format as passed to this command. The global mapping will automatically be saved when you exit the application if a filename has been defined. If no file is defined, then all PK mappings that you define are lost when exiting the application (unless you explicitely save them using WbSavePkMap

    v_person=person_id
    v_data=id1,id2

will define a primary key for the view `v_person` and one for the view `v_data`. The definitions stored in that file can be overwritten using the `WbDefinePk` command, but those changes won't be saved to the file. This file will be read for all database connections and is not profile specific. If you have conflicting primary key definitions for different databases, you'll need to execute the `WbDefinePk` command each time, rather then specifying the keys in the mapping file.

When you define the key columns for a table through the GUI, you have the option to remember the defined mapping. If this option is checked, then that mapping will be added to the global map (just as if you had executed `WbDefinePk` manually.

The mappings will be stored with lowercase table names internally, regardless how you specify them.

#### 29.9.2. List defined primary key columns - WbListPKDef

To view the currently defined primary keys, execute the command `WbListPkDef`.

#### 29.9.3. Load primary key mappings - WbLoadPKMap

To load the additional primary key definitions from a file, you can use the the `WbLoadPKMap` command. If a filename is defined in the configuration file then that file is loaded. Alternatively if no file is configured, or if you want to load a different file, you can specify the filename using the `-file` parameter.

#### 29.9.4. Save primary key mappings - WbSavePKMap

To save the current primary key definitions to a file, you can use the the `WbSavePKMap` command. If a filename is defined in the configuration file then the definition is stored in that file. Alternatively if no file is configured, or if you want to store the current mapping into a different file, you can specify the filename using the `-file` parameter.

### 29.10. Change the default fetch size - WbFetchSize

The default fetch size for a connection can be defined in the connection profile. Using the command `WbFetchSize` you can change the fetch size without changing the connection profile.

The following script changes the default fetch size to 2500 rows and then runs a `WbExport` command.

    WbFetchSize 2500;
    WbExport -sourceTable=person -type=text -file=/temp/person.txt;

`WbFetchSize` will not change the current connection profile.

### 29.11. Run statements as a single batch - WbStartBatch, WbEndBatch

To send several SQL Statements as a single "batch" to the database server, the two commands WbStartBatch and WbEndBatch can be used. All statements between these two will be sent as a single statement (using `executeBatch()`) to the server.

Note that not all JDBC drivers support batched statements, and the flexibility what kind of statements can be batched varies between the drivers as well. Most drivers will not accept different types of statements e.g. mixing DELETE and INSERT in the same batch.

To send a group of statements as a single batch, simply use the command `WbStartBatch` to mark the beginning and `WbEndBatch` to mark the end. You have to run all statements together either by using "Execute all" or by selecting all statements (including WbStartBatch and WbEndBatch) and then using "Execute selected". The following example sends all INSERT statements as a single batch to the database server:

    WbStartBatch;
    INSERT INTO person (id, firstname, lastname) VALUES (1, 'Arthur', 'Dent');
    INSERT INTO person (id, firstname, lastname) VALUES (2, 'Ford', 'Prefect');
    INSERT INTO person (id, firstname, lastname) VALUES (3, 'Zaphod', 'Beeblebrox');
    INSERT INTO person (id, firstname, lastname) VALUES (4, 'Tricia', 'McMillian');
    WbEndBatch;
    COMMIT;

### 29.12. Extracting BLOB content - WbSelectBlob

To save the contents of a `BLOB` or `CLOB` column into an external file the `WbSelectBlob` command can be used. Most DBMS support reading of `CLOB` (character data) columns directly, so depending on your DBMS (and JDBC driver) this command might only be needed for binary data.

The syntax is very similar to the regular `SELECT` statement, an additional `INTO` keyword specifies the name of the external file into which the data should be written:

    WbSelectBlob blob_column
    INTO 'c:/temp/image.bmp'
    FROM theTable
    WHERE id=42;

Even if you specify more then one column in the column list, SQL Workbench/J will only use the first column. If the SELECT returns more then one row, then one output file will be created for each row. Additional files will be created with a counter indicating the row number from the result. In the above example, image.bmp, image_1.bmp, image_3.bmp and so on, would be created.

`WbSelectBlob` is intended for an ad-hoc retrieval of a single LOB column. If you need to extract the contents of several LOB rows and columns it is recommended to use the WbExport command.

You can also manipulate (save, view, upload) the contents of BLOB columns in a result set. Please refer to BLOB support for details.

### 29.13. Control feedback messages - WbFeedback

Normally SQL Workbench/J prints the results for each statement into the message panel. As this feedback can slow down the execution of large scripts, you can disable the feedback using the `WbFeedback` command. When `WbFeedback OFF` is executed, only a summary of the number of executed statements will be displayed, once the script execution has finished. This is the same behaviour as selecting "Consolidate script log" in the options window. The only difference is, that the setting through `WbFeedback` is temporary and does not affect the global setting.

`WbFeedback traceOn` can be used to enable printing of every executed statement to the screen. The SQL statement printed will be the one after variable substitution and macro expansion. `WbFeedback traceOff` will turn tracing of statements off.

### 29.14. Change the current schema - WbSetSchema

The `WbSetSchema` command will use the JDBC driver's API to change the current schema.

Whether this command works and actually changes the current schema depends on the JDBC driver and the underlying DBMS. The driver is free to ignore the call to `setSchema()` API call.

### 29.15. Change the current database/catalog - WbSwitchDB

The `WbSwitchDB` can be used to switch the current catalog (or database) if the DBMS supports this. The details on what is done in the background depend on the DBMS.

- For Postgres this is similar to the `psql`'s `\connect` command and will use the current username and password to create a new physical connection to the specified database.

- For Oracle this is used to switch to a different PDB (pluggable database). This will be done by running `ALTER SESSION SET CONTAINER = ...`.

- For SQL Server, MySQL and MariaDB this will run a `USE ...` command to switch the database.

### 29.16. Setting connection properties - SET

The `SET` command is passed on directly to the driver, except for the parameters described in this chapter because they have an equivalent JDBC call which will be executed instead.

Oracle does not have a SQL set command. The SET command that is available in SQL*Plus is a specific SQL*Plus command and will not work with other client software. Most of the SQL*Plus SET commands only make sense within SQL*Plus (e.g. formatting of the results). To be able to run SQL scripts that are intended for Oracle SQL*PLus, any error reported from the SET command when running against an Oracle database will silently be ignored and only logged as a warning.

#### 29.16.1. FEEDBACK

`SET feedback ON/OFF` is equivalent to the WbFeedback command, but mimics the syntax of Oracle's SQL*Plus utility.

#### 29.16.2. AUTOCOMMIT

With the command `SET autocommit ON/OFF` autocommit can be turned on or off for the current connection. This is equivalent to setting the autocommit property in the connection profile or toggling the state of the SQL → Autocommit menu item.

#### 29.16.3. MAXROWS

Limits the number of rows returned by the next statement. The behaviour of this command is a bit different between the console mode and the GUI mode. In console mode, the maxrows stay in effect until you explicitely change it back using `SET maxrows` again.

In GUI mode, the maxrows setting is only in effect for the script currently being executed and will only temporarily overwrite any value entered in the "Max. Rows" field.

### 29.17. Changing Oracle session behavior - SET

The following options for the SET command are only available when being connected to an Oracle database.

#### 29.17.1. SERVEROUTPUT

`SET serveroutput on` is equivalent to the ENABLEOUT command and `SET serveroutput off` is equivalent to DISABLEOUT command.

#### 29.17.2. AUTOTRACE

This enables or disables the "autotrace" feature similar to the one in SQL*Plus. The syntax is equivalent to the SQL*Plus command and supports the following options:

Option | Description
--- | ---
ON | Turns on autotrace mode. After running a statement, the statement result (if it is a query), the statistics and the execution plan for that statement are displayed as separate result tabs.
OFF | Turns off the autotrace mode.
TRACEONLY | Like `ON`, but does not display the result of a query.
REALPLAN | This is an extension to the SQL*Plus `EXPLAIN` mode. Using `EXPLAIN`, SQL Workbench/J will simply run an `EXPLAIN PLAN` for the statement (and the statement will not be executed) - this is the same behavior as SQL*Plus' `EXPLAIN` mode. Using `REALPLAN`, SQL Workbench/J will run the statement and then retrieve the execution plan that was generated while running the statement. This might yield a different result than regular `EXPLAIN` mode. The actual plan also contains more details about estimated and actual row counts. This plan is retrieved using `dbms_xplan.display_cursor()`. If `REALPLAN` is used, the actual SQL statement sent to the server will be changed to include the `GATHER_PLAN_STATISTICS` hint.

The information shown in autotrace mode can be controlled with two options after the `ON` or `TRACEONLY` parameter. `STATISTICS` will fetch the statistics about the execution and `EXPLAIN` which will display the execution plan for the statement. If not additional parameter is specified, `EXPLAIN STATISTICS` is used.

If statistics are requested, query results will be fetched from the database server but they will not be displayed.

Unlike SQL*Plus, the keywords (`AUTOTRACE, STATISTICS, EXPLAIN`) cannot be abbreviated!

For more information about the prerequisites for the autotrace mode, see the description of DBMS specific features.

### 29.18. Changing read only mode - WbMode

In the connection profile two options can be specified to define the behavior when running commands that might change or update the database: a "read only" mode that ignores such commands and a "confirm all" mode, where you need to confirm any statement that might change the database.

These states can temporarily be changed without changing the profile using the `WbMode` command.

This changes the mode for all editor tabs, not only for the one where you run the command.

Parameters for the `WbMode` command are:

Parameter | Description
--- | ---
reset | Resets the flags to the profile's definition
normal | Makes all changes possible (turns off read only and confirmations)
confirm | Enables confirmation for all updating commands
readonly | Turns on the read only mode

The following example will turn on read only mode for the current connection, so that any subsequent statement that updates the database will be ignored

    WbMode readonly;

To change the current connection back to the settings from the profile use:

    WbMode reset;

### 29.19. Count rows for all tables - WbRowCount

This command retrieves the row counts for several tables at once. If called without parameters the row counts for all tables accessible to the current user are counted.

The command supports the following parameters to specify the tables (or views) to be counted.

Parameter | Description
--- | ---
-objects | Show only the row counts for the tables (or views) specified by the parameter. The parameter value can contain wildcards, e.g. `-objects=PR%,ORD%` will count the rows for all tables with names that either start with `PR` or `ORD` To count all tables from a schema (or catalog), the schema can be part of the parameter, e.g. `-objects=some_schema.%` will include all tables from the schema `some_schema`. The parameter supports auto-completion and will show a list of available tables.
-types | Define the types of objects which should be selected. By default only tables are considered. If you also want to count the rows for views, use `-types=table,view` The parameter supports auto-completion and will show a list of available object types.
-orderBy | Defines how the resulting table should be sorted. By default it will be sorted alphabetically by table name. The `-orderBy` parameter specifies the columns to sort the result by. By default, sorting is done ascending, if you want a descending sort, append `:desc` to the column name, e.g.: `-orderBy="rowcount:desc"`. So sort by multiple columns separate the column names with a comma: `-orderBy="rowcount:desc,name:desc"` or `-orderBy="rowcount,name:desc"`
-excludeColumns | Possible values: `catalog`, `schema`, `type` By default `WbRowCount` will display the same columns as the table list in the DbExplorer. If not all columns are needed or wanted, this parameter can be used to exclude certain columns. You can specify a comma separated list of columns to be excluded, e.g. `-excludeColumns=type,catalog`. The columns `ROWCOUNT` and `NAME` can not be excluded. The name `database` can be used instead of `catalog`.

If none of the above parameters are used, `WbRowCount` assumes that a list ot table names was specified. `WbRowCount person,address,orders`is equivalent to `WbRowCount -objects=person,address,orders`. When called without any parameters the row counts for all tables accessible to the current user will be displayed.

Unlike the Count rows item in the DbExplorer, `WbRowCount` displays the result for all tables once it is finished. It does not incrementally update the output.

### 29.20. Change the connection for a script - WbConnect

With the `WbConnect` command, the connection for the currently running script can be changed.

When this command is run in GUI mode, the connection is only changed for the remainder of the script execution. Therefor at least one other statement should be executed together with the `WbConnect` command. Either by running the complete script of the editor or selecting the `WbConnect` command together with other statements. Once the script has finished, the connection is closed and the "global" connection (selected in the connect dialog) is active again. This also applies to scripts that are run in batch mode or scripts that are started from within the console using `WbInclude`.

When this command is entered directly in the command line of the console mode, the current connection is closed and the new connection is kept open until the application ends, or a new connection is established using `WbConnect` on the command line again.

There are three different ways to specify a connection:

#### 29.20.1. By specifying a profile

Parameter | Description
--- | ---
-profile | Specifies the profile name to connect to. This parameter is ignored if either `-connection` or the detailed connection informations are supplied individually.
-profileGroup | Specifies the group in which the profile is stored. This is only required if the profile name is not unique

#### 29.20.2. By specifying a simple connection string

Parameter | Description
--- | ---
-connection | Allows to specify a full connection definition as a single parameter (and thus does not require a pre-defined connection profile). The connection is specified with a comma separated list of key value pairs: `username` - the username for the connection `password` - the password for the connection `url` - the JDBC URL `driver` - the class name for the JDBC driver. If this is not specified, SQL Workbench/J will try to determine the driver from the JDBC URL `driverJar` - the full path to the JDBC driver. This not required if a driver for the specified class is already configured e.g.: `"username=foo,password=bar,url=jdbc:postgresql://localhost/mydb"` If an appropriate driver is already configured the driver's classname or the JAR file don't have to be specified. If an appropriate driver is not configured, the driver's jar file must be specified: `"username=foo,password=bar,url=jdbc:postgresql://localhost/mydb,driverjar=/etc/drivers/postgresql.jar"` SQL Workbench/J will try to detect the driver's classname automatically (based on the JDBC URL). If this parameter is specified, `-profile` is ignored. The individual parameters controlling the connection behavior can be used together with `-connection`, e.g. `-autocommit` or `-fetchSize`

#### 29.20.3. By specifying all connection attributes

Parameter | Description
--- | ---
-url | The JDBC connection URL
-username | Specify the username for the DBMS
-password | Specify the password for the user If this parameter is not specified (but `-url` and `-username`) then you will be prompted to enter the password. To supply an empty password use `-password=` in the command line when starting SQL Workbench/J
-driver | Specify the full class name of the JDBC driver
-driverJar | Specify the full pathname to the .jar file containing the JDBC driver
-autocommit | Set the autocommit property for this connection. You can also control the autocommit mode from within your script by using the `SET AUTOCOMMIT` command.
-rollbackOnDisconnect | If this parameter is set to true, a `ROLLBACK` will be sent to the DBMS before the connection is closed. This setting is also available in the connection profile.
-checkUncommitted | If this parameter is set to true, SQL Workbench/J will try to detect uncommitted changes in the current transaction when the main window (or an editor panel) is closed. If the DBMS does not support this, this argument is ignored. It also has no effect when running in batch or console mode.
-trimCharData | Turns on right-trimming of values retrieved from `CHAR` columns. See the description of the profile properties for details.
-removeComments | This parameter corresponds to the Remove comments setting of the connection profile.
-fetchSize | This parameter corresponds to the Fetch size setting of the connection profile.
-ignoreDropError | This parameter corresponds to the Ignore DROP errors setting of the connection profile.
-altDelimiter | This parameter corresponds to the Alternate delimiter setting of the connection profile.

If none of the parameters is supplied when running the command, it is assumed that any value after `WbConnect` is the name of a connection profile, e.g.:

    WbConnect production

will connect using the profile name `production`, and is equivalent to

    WbConnect -profile=production

### 29.21. Show the history of SQL statements - WbHistory

This command is primarily intended for console mode to show the statements that have been executed. In console mode the number of any of the listed statements can be entered to re-execute that statement from the history directly.

### 29.22. Run an XSLT transformation - WbXslt

Transforms an XML file via a XSLT stylesheet. This can be used to format XML input files into the correct format for SQL Workbench/J or to transform the output files that are generated by the various SQL Workbench/J commands.

Parameters for the XSLT command:

Parameter | Description
--- | ---
-inputfile | The name of the XML source file.
-xsltoutput | The name of the generated output file.
-stylesheet | The name of the XSLT stylesheet to be used.
-xsltParameter | A list of parameters (key/value pairs) that should be passed to the XSLT processor. When using e.g. the `wbreport2liquibase.xslt` stylesheet, the value of the `author` attribute can be set using `-xsltParameter="authorName=42"`. This parameter can be provided multiple times for multiple parameters, e.g. when using `wbreport2pg.xslt`: `-xsltParameter="makeLowerCase=42" -xsltParameter="useJdbcTypes=true"`

### 29.23. Running operating system commands - WbSysExec

To run an operating system command use `WbSysExec` followed by a valid command for your operating system.

To run the program `ls` the following call can be used:

    WbSysExec ls

To run Windows® commands that are internal to `cmd.exe` such as `DIR`, you must call `cmd.exe` with the `/c` switch to make sure cmd.exe is terminated:

    WbSysExec cmd /c dir /n

If you need to specify a working directory for the program, or want to specify the command line arguments individually, a second format is available using the standard SQL Workbench/J parameter handling:

`WbSysExec` supports conditional execution

Parameter | Description
--- | ---
-program | The name of the executable program
-argument | One command line argument for the program. This parameter can be repeated multiple times.
-dir | The working directory to be used when calling the external program
-env | A definition for an environment variable for the process running the program. This parameter can be repeated multiple times.

To run an internal Windows® command using the second format, use the following syntax:

    WbSysExec -program='cmd.exe' -argument='/c' -argument='dir /n' -dir='c:\temp\'

To define multiple environment variables for the process, repeat the `-env` parameter for each variable e.g. `-env="var_one=value_one" -env="var_two=value_two"`

### 29.24. Opening a file with the default application - WbSysOpen

`WbSyOpen` can be used to open a file with the default application of the operating system.

    WbExport -file=c:/temp/person.txt -sourceTable=person -type=text -header=true;
    WbSysOpen c:/temp/person.txt;

Due to limitations of the Java console mode, neither `WbSysExec` nor `WbSysOpen` can be used to run a text editor (vi, vim) in console mode (and putting SQL Workbench/J into the background).

### 29.25. Change an internal configuration parameter - WbSetConfig

Not all configuration parameters are available through the Options Dialog and have to be changed manually in the file workbench.settings. Editing the file requires to close the application.

When using `WbSetConfig`, configuration properties can be changed permanently without restarting SQL Workbench/J.

`WbSetProp` is an alias for `WbSetConfig` with the difference that the change will not be saved permanently. Any property set through `WbSetProp` is lost when the SQL Workbench/J is closed.

Any value that is changed through this command will be saved automatically in `workbench.settings` when the application is closed.

If you want to e.g. disable the use of Savepoints in the SQL statements entered interactively, the following command will turn this off for PostgreSQL:

    WbSetConfig workbench.db.postgresql.sql.usesavepoint=false

For a list of configuration properties that can be changed, please refer to Advanced configuration options

If you supply only the property key, the current value will be displayed. If no argument is supplied for `WbSetConfig` all properties are displayed. You can also supply a partial property key. `WbSetConfig workbench.db.postgresql` will list all PostgreSQL related properties. You can directly edit the properties in the result set.

The value `[dbid]` inside the property name will get replaced with the current DBID to change database specific settings.

The following command changes the property named `workbench.db.postgresql.ddlneedscommit` if the current connection is against a PostgreSQL database:

    WbSetConfig workbench.db.[dbid].ddlneedscommit=true

Prev |  | Next
28. Manage variables with SQL Workbench/J | Home | 30. DataPumper