generate-changelog


The generate-changelog command creates a changelog file that has a sequence of changesets which describe how to re-create the current state of the database.

Uses

The generate-changelog command is typically used when you want to capture the current state of a database, then apply those changes to any number of databases. This is typically only done when a project has an existing database, but hasn't used Liquibase before. See How to set up Liquibase with an Existing Project and Multiple Environments for more details.

Note: When using the update command to apply the changes in the changelog, Liquibase will not create a new database or schema. You must create them before applying the changelog to it.

Syntax

To generate a changelog:

  1. Configure the Liquibase properties file to include your driver, classpath, and URL for the database you want to capture.
  2. Note: For more information on how to configure the Liquibase properties file, see the Create and Configure a liquibase.properties File topic. Instead of using a properties file, you can pass the necessary information from the command line.

  3. Open your CLI and run the following command:
  4. liquibase generate-changelog --changelog-file=example-changelog.xml 

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
--license-key

Your Liquibase Pro license key

Optional

Command arguments

Attribute Definition Requirement
--url

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

Required
--author

Specifies the author for changesets in the generated changelog.

Optional
--changelog-file

Changelog file to write results

Optional
--contextFilter

Specifies the changeset contexts to match. Contexts are expressions you can add to changesets to control which changesets are executed in any particular migration run.

Optional
--data-output-directory=DIR

Specifies a directory to send the data output of the command as a CSV file.

Optional
--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
--diff-types

Specifies the types of objects to compare. Includes a list of diff types in a changelog file expressed as a comma-separated list (without spaces): catalogs, tables, functions, views, columns, indexes, foreignkeys, primarykeys, uniqueconstraints, data, storedprocedures, triggers, sequences, databasepackage, databasepackagebody.

If null, default types are tables, views, columns, indexes, foreignkeys, primarykeys, uniqueconstraints.

Optional
--driver

The JDBC driver class

Optional
--driver-properties-file

The JDBC driver properties file

Optional
--exclude-objects

Objects to exclude from diff

Optional
--include-catalog=<true|false>

If true, the catalog will be included in generated changesets. Default: false

Optional
--include-objects

Objects to include in diff

Optional
--include-schema=<true|false>

If true, the schema will be included in generated changesets. Default: false

Optional
--include-tablespace=<true|false>

Includes the tablespace of tables and indexes in a generated changesets if the value is true. The default value is false.

Optional *
--label-filter

Specifies the changeset labels to match. Labels are tags you can add to changesets to control which changeset will be executed in any migration run.

Optional
--output-schemas

Output schemas allows you to replace the schemas in the output changelog. This is a CSV list. It is essential that the parameter size matches schemas. If you have three items names in schemas, you must also have three items in output schemas.

Example: liquibase generateChangelog --schemas a,b,c --outputSchemas d,e,f

Optional
--overwrite-output-file=<true|false>

Determines whether generate-changelog can overwrite an existing changelog, including one specified in --changelog-file. Default: false.

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
--schemas=<name1, name2>

Specifies database schemas you want to include

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.

* --include-tablespace only captures the tablespace if it was specified in the create table statement.

Output

The generate-changelog command generates a changelog that contains all your objects (represented as changesets) and places the file in the same directory where the command was ran.

The extension you provide determines the format of the changelog, so if you specify the filename as changelog.xml, you will get an XML formatted changelog. However, if you specify the filename as changelog.yaml, changelog.json, or changelog.sql, you will get changelogs formatted in YAML, JSON, or SQL, respectively.

Additional functionality with Liquibase Pro

While Liquibase Open Source stores all changesets in a changelog, Liquibase Pro creates a directory called Objects and places the directory at the same level as your changelog. The Objects directory contains a subdirectory for each of the following stored logic types:

  • package
  • packagebody
  • function
  • stored procedure
  • trigger
  • view

Note: Some database platforms may not support all of these stored logic types.

The generate-changelog command will not create the Objects directory if:

  • You don't have a valid ProKey
  • There are no stored logic objects in the database
  • The changelog file is written in formatted SQL (the Objects folder can only be created when generating XML, JSON or YAML changelogs)
  • The target database is not supported with the generate-changelog command and stored logic objects

If your database contains stored logic objects, you may have issues attempting to run the generate-changelog command more than once, even with a new changelog name, because the stored logic files already exist in the Objects directory.

To generate a newer version of the changelog file with stored logic objects based on the current database state, you need to delete, rename, or move the Objects directory that was created by running the generate-changelog command previously. Then, you can run the generate-changelog command again.

Note: If there is a pre-existing Objects directory that is not related to Liquibase, you need to delete, rename, or move it to run the generate-changelog command.

If you want to track the history of stored logic objects, use the diff-changelog command. The diff-changelog command structures stored logic files into timestamped directories every time you run the command.

Related links