runWithSpoolFile

Last published July 28, 2025

runWithSpoolFile is a changeset attribute that specifies a spool file to send output to when you deploy a particular changeset. This is useful if you want a changeset to have its own spool file.

Uses

By default, Liquibase automatically stores your command SQL in a .spool file for temporary processing before sending it to your database. This improves query efficiency. When you use runWith for a native executor like PSQL, SQL Plus, or SQLCMD, you can specify global arguments at runtime that configure spool files. For example, in SQL Plus:

  • --sqlplus-create-spool

    : If

    true

    , create an Oracle spool file which captures the SQLPlus output.

    Default:

    true

    . When

    create spool = false

    , the spool file does not generate.

  • --sqlplus-keep-temp

    : Indicates whether or not to keep a temporary SQL file after the execution of

    SQL Plus

    . If

    true

    , the file is not deleted. This setting is not required to keep the temporary file, only

    create-spool

    is.

    Default:

    false

    .

  • --sqlplus-keep-temp-name

    : Indicates the name of a temporary SQL file after the execution of

    SQL Plus

    . If no file name is specified, a name is automatically generated.

    In Oracle, if no file extension is specified, the file is saved as

    .lst

    .

  • --sqlplus-keep-temp-overwrite

    : Overwrites any files in the specified directory with the same name.

    Default:

    true

    .

  • --sqlplus-keep-temp-path

    : Specify the path in which to store the temporary files after the execution of

    SQL Plus

    . If not specified, the files will be stored in the system's

    temp

    directory.

Note: Each native executor has global arguments with different names. See the native executor pages for PSQL, SQL Plus, and SQLCMD for more information.

For example, you can specify *-keep-temp-name as the spool file to use for all changesets. If you don't specify *-keep-temp-name, Liquibase generates one spool file with an arbitrary name per changeset.

However, you may want to specify the name of a particular spool file for a particular changeset. This may help you enforce a file naming convention and keep track of your deployment SQL more easily. To do this, set runWithSpoolFile on each desired changeset. If you specify different names for *-keep-temp-name and runWithSpoolFile, the value you specify for runWithSpoolFile takes precedence on any affected changesets.

Syntax

All changelog attributes use the camelCase format.

Examples

--liquibase formatted sql --changeset adrian:1 runWith:sqlplus runWithSpoolFile:my_spool_file.spool create table company ( id int primary key, address varchar(255) );