execute-sql

The execute-sql command executes a SQL string or file.

Uses

Use the execute-sql command to directly run SQL queries without changing and applying changelog files with changesets. An example of using the execute-sql command is to check the database data or make unplanned changes when you run Liquibase in automation.

Compared with other database query tools, the execute-sql command runs with the credentials and configuration you already have in Liquibase without any need to set up another tool. If statements run correctly in your database CLI but fail in Liquibase, running exploratory statements through execute-sql might help you find differences in permission configurations, connection setup, and SQL run in the database CLI or database-native SQL.

Note: The command does not affect the DATABASECHANGELOG table because the table is associated with changesets and tracks which changesets have been run. Liquibase recommends handling your changes with execute-sql only on rare occasions to not lose their traceability.

Syntax

To run the execute-sql command, specify the following parameters in the Liquibase properties file, environment variables, or the command prompt while running the command:

  • URL, driver [optional], and user authentication information such as username and password.
  • sql or sql-file parameter.

Tip: For more information about the options to store parameters, see Create and Configure a liquibase.properties File, Liquibase Environment Variables, and JAVA_OPTS Environment Variable. To find the format of the parameter, see Liquibase Parameters.

Run the execute-sql command with the SQL string:

liquibase execute-sql --sql="SELECT * FROM databasechangelog"

Run the execute-sql command with the SQL file:

liquibase execute-sql --sql-file=path/to/file.sql

Note: You can also specify --delimiter=/. The default value for delimiter is ;, which will work as long as you do not have stored logic.

Global arguments

Tip: For best results, specify all commands and parameters in the --kebab-case format in the CLI. If your preference is camelCase, it also works in the CLI.

Attribute Definition Requirement
--output-file

File path to where the command output will be written. If not specified, output goes to STDOUT. See --output-file.

Optional

Command arguments

Tip: For best results, specify all commands and parameters in the --kebab-case format in the CLI. If your preference is camelCase, it also works in the CLI.

Attribute Definition Requirement
--sql

The SQL string to execute

Note: Columns display in the same order they are specified in the argument. If no columns are specified (For example select * <table_name>), then the output will display columns in the same order they are in the database.

Required
--sql-file

Specifies the file where SQL statements are stored

Required
--url

The JDBC database connection URL. See Using JDBC URL in Liquibase.

Required
--default-catalog-name

Name of the default catalog to use for the database connection

Optional
--default-schema-name

Name of the default schema to use for the database connection. If defaultSchemaName is set, then objects do not have to be fully qualified. This means you can refer to just mytable instead of myschema.mytable.

Tip: In Liquibase v4.23.0+, camelCase for defaultSchemaName works successfully. If you are on an earlier version, camelCase may not work as expected.

Note: The syntax liquibase.command.defaultSchemaName is valid for v4.19.0+. For prior versions, use defaultSchemaName.

Optional
--delimiter

The delimiter to use when executing SQL scripts

Optional
--driver

The JDBC driver class

Optional
--driver-properties-file

The JDBC driver properties file

Optional
--output-file The CSV file that is the result of running a select query. Optional
--password

Password to connect to the target database.

Tip: It is a best practice to store sensitive data in a Secrets Management tool with Liquibase Pro.

Optional
--username

Username to connect to the target database.

Tip: It is a best practice to store sensitive data in a Secrets Management tool with Liquibase Pro.

Optional

Note: The username and password attributes are not required for connections and systems which use alternate means of authentication. Also, you can specify database credentials as part of the url attribute.

Related links