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 generate-changelog commands in the CLI.

The --exclude-objects and --include-objects attributes help you filter the data that is exported by specifying objects and object types:

  • --exclude-objects alters output to exclude the objects specified.
  • --include-objects 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 --include-objects

To run the --include-objects attribute with the diff command or generate-changelog command, ensure that you have configured the Liquibase properties file to include the driver, classpath, and URL for the database that you want to capture. Another way is to pass all attributes on the command line.

diff command example:

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

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

generate-changelog command example:

  1. Create a new table in your database or use an existing one.
  2. Run the following:
    3. liquibase generate-changelog --include-objects="my_table"

    Note: Enter the name of your table in place of my_table. You must pass --include-objects to the right of generate-changelog.

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

Running --exclude-objects

To run the --exclude-objects attribute with the diff or generate-changelog command, ensure that you have configured the Liquibase properties file to include the driver, classpath, and URL for the database that you want to capture. Another way is to pass all attributes on the command line.

diff command example:

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

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

generate-changelog command example:

  1. Create a new table in your database or use an existing one.
  2. Run the following:
    3. liquibase generate-changelog --exclude-objects="my_table"

    Note: Enter the name of your table in place of my_table. You must pass --exclude-objects to the right of generate-changelog.

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

Syntax

Note: Liquibase uses the java.util.regex engine to match regular expressions.

  • An object name, which is a regular expression (regexp) 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 --exclude-objects or --include-objects 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 include-objects=new_table, you will see new_table in the output as well as the columns associated with it. If you run exclude-objects=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 run case-insensitive searches, use the (?i) regexp flag.

Examples

  • "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