Including and Excluding Objects from a Database

Liquibase allows you to include and exclude objects from your database to a changelog file. You can specify the objects you want to include or exclude when running the diff and generateChangeLog commands in the CLI.

The excludeObjects and includeObjects attributes help you filter the data that is exported by specifying objects and object types:

  • The --excludeObjects attribute alters output to exclude the objects specified.
  • The --includeObjects attribute alters output to include only the objects specified.

Note: The attribute names for Maven are diffIncludeObjects and diffExcludeObjects. They have the same functionality as the attributes for the CLI.

Running the includeObjects attribute

To run the includeObjects attribute with the diff command or generateChangeLog command, ensure that you have configured the liquibase.properties file to include your driver, classpath, and URL for the database you want to capture. Another way is to pass all attributes on the command line.

The diff command example:

  1. Create a new table in your database or use the existing one.
  2. Run the following:
liquibase diff --includeObjects="my_table"

Note: Enter the name of your table in place of my_table. You can also run
liquibase diff --includeObjects="table:mytable".

The generateChangeLog command example:

  1. Create a new table in your database or use the existing one.
  2. Run the following:
liquibase --includeObjects="my_table" generateChangeLog

Note: Enter the name of your table in place of my_table. The includeObjects attribute must be passed before generateChangeLog.

You will see the mytable object printed to the console output.

Running the excludeObjects attribute

To run the excludeObjects attribute with the diff or generateChangeLog command, ensure that you have configured the liquibase.properties file to include your driver, classpath, and URL for the database you want to capture. Another way is to pass all attributes on the command line.

The diff command example:

  1. Create a new table in your database or use the existing one.
  2. Run the following:
liquibase diff --excludeObjects="my_table"

Note: Enter the name of your table in place of my_table. You can also run
liquibase diff --excludeObjects="table:mytable".

The generateChangeLog command example:

  1. Create a new table in your database or use the existing one.
  2. Run the following:
liquibase --excludeObjects="my_table" generateChangeLog

Note: Enter the name of your table in place of my_table. The excludeObjects attribute must be passed before generateChangeLog.

You will see a list of objects printed to the console output, excluding the object mytable.

The format for the excludeObjects and includeObjects attributes

  • An object name, which is the regexp (regular expression) you specify, will include or exclude any object from the database which name matches the regexp.
  • Multiple expressions must be separated by a comma.
  • The type:name logic will be applied to the tables containing columns, indexes, foreign keys, primary keys, unique constraints, and others.

When running the excludeObjects or includeObjects attribute with the diff command, the objects you want to filter are not only the objects specified. They are also dependent objects. For example, if you run includeObjects=new_table, you will see new_table in the output as well as the columns associated with it. If you run excludeObjects=new_table, the output will not include the table or the columns. This dependency logic works for columns, indexes, foreign keys, primary keys, unique constraints, and data.

Note: The name comparison is case-sensitive. If you want to change the current logic, use the (?i) regexp flag.

Examples of the format for excludeObjects and includeObjects attributes

  • "table_name" will match a table called "table_name". It will not match "other_table" or "TABLE_NAME".
  • "(i?)table_name" will match a table called "table_name" or "TABLE_NAME".
  • "table_name" will match all columns in the table called "table_name".
  • "table:table_name" will match a table called "table_name". It will not match a column called "table_name".
  • "table:table_name, column:.*_lock" will match a table called "table_name" and all columns that end with _lock".

Related Links