init project

As a new user, run the init project subcommand to get started with Liquibase. If you already use Liquibase, run init project to immediately create a new project with minimal input. It is available in Liquibase 4.7.0 and later.

The subcommand finds or creates your project folder containing a changelog and "defaults file"—liquibase.properties—and delivers an example H2 database to help you get started. The defaults file lets you specify properties without typing them into the CLI every time you run a command. For more information, see Create and Configure a liquibase.properties File. You can alternatively specify these properties as environment variables or using the JAVA_OPTS Environment Variable.

For guidance on structuring your changelogs after running init project, see Design Your Liquibase Project.

Note: The init project command does not require a Liquibase Pro license key, but the liquibase-commercial.jar file must be in your /liquibase/internal/lib folder for the command to work.

Syntax

To run the init project subcommand in the interactive mode, enter liquibase init project in your command line and follow the instructions: choose [y] to accept all the default values, [c] to customize the values, or [n] to not set up the project files.

Liquibase provides the following options:

  • Keep the default settings (y):
  • --project-dir=./
    --changelog-file=example-changelog.sql
    --format=sql
    --project-defaults-file=liquibase.properties
    --url=jdbc:h2:tcp://localhost:9090/mem:dev
    --username=dbuser
    --password=letmein

    The default values work with the example H2 database, which is also delivered when running liquibase init project.

  • Customize all parameters (c):
  • --project-dir=[path/to/some/directory]
    --changelog-file=[file.ext]
    --format=[sql|xml|json|yaml|yml]
    --project-defaults-file=[liquibase.properties]
    --url=[some/JDBC/URL]
    --username=[string]
    --password=[string]
  • Customize a few parameters and stop the process. The default settings will be used.

Example: If you run liquibase init project --changelog-file=mychangelog.sql --username=myusername, the interactive mode will ask if you want to accept the rest of the default parameters or customize all flags that are not set. In this case, they are project dir, project defaults file, url, and password.

To use the non-interactive mode, run liquibase init project and specify all the parameters you need:

liquibase init project
--project-dir=[path/to/some/directory]
--changelog-file=[file.ext]
--format=[sql|xml|json|yaml|yml]
--project-defaults-file=[liquibase.properties]
--url=[some/JDBC/URL]
--username=[string]
--password=[string]

Note: If Liquibase cannot find the directory, it will create the directory using the path you have specified.

init project does not overwrite your existing changelog file but updates an existing project-defaults-file with the same name. For example, this functionality might help you update the Liquibase properties file from the CLI with a different changelog or URL but keep other values and files the same.

Command arguments

Note: Syntax for each parameter is specified in kebab-case (CLI and flow file), camelCase (properties file and JAVA_OPTS), and ENVAR_CASE (environment variable).

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.

Note: The init project subcommand skips the CLI interactive mode when you provide values by other mechanisms than CLI.

Attribute Description Requirements
--changelog-file
liquibase.command.init.project.changelog-file
LIQUIBASE_COMMAND_INIT_PROJECT_CHANGELOG_FILE

Relative or fully qualified path to the changelog file. Default: example-changelog

Optional
--format
liquibase.command.init.project.format
LIQUIBASE_COMMAND_INIT_PROJECT_FORMAT

Format of the project changelog file: sql|xml|json|yaml|yml. Default: sql

Optional
--keep-temp-files
liquibase.command.init.project.keepTempFiles
LIQUIBASE_COMMAND_INIT_PROJECT_KEEP_TEMP_FILES

For remote project locations, do not delete temporary project files. Default: false

Optional
--password
liquibase.command.init.project.password
LIQUIBASE_COMMAND_INIT_PROJECT_PASSWORD

Password to use to connect to the database. Default: letmein

Optional
--project-defaults-file
liquibase.command.init.project.projectDefaultsFile
LIQUIBASE_COMMAND_INIT_PROJECT_PROJECT_DEFAULTS_FILE

File with default Liquibase properties. Default: liquibase.properties

Optional
--project-dir
liquibase.command.init.project.projectDir
LIQUIBASE_COMMAND_INIT_PROJECT_PROJECT_DIR

An optional parameter used to specify the directory containing files (existing or to be auto-created) to be used with Liquibase. Default: ./

Optional
--project-guide
liquibase.command.init.project.projectGuide
LIQUIBASE_COMMAND_INIT_PROJECT_PROJECT_GUIDE

Parameter that turns on or turns off the CLI interactive mode. For example, if you want to set one parameter and have the rest as default ones, run the parameter and set --project-guide=off to not be asked about the rest of the settings: liquibase init project --changelog=mychangelog.sql --project-guide=off. Default: on

Optional
--url
liquibase.command.init.project.url
LIQUIBASE_COMMAND_INIT_PROJECT_URL

The JDBC database connection URL. See Using JDBC URL in Liquibase. Default: jdbc:h2:tcp://localhost:9090/mem:dev

Optional
--username
liquibase.command.init.project.username
LIQUIBASE_COMMAND_INIT_PROJECT_USERNAME

Username to connect to the database. Default: dbuser

Optional

Note: An example of a Java system property:
For Windows, configure SET JAVA_OPTS="liquibase.command.init.project.projectDir=java_lbproj"
For Linux, run the value on the command line -Dliquibase.command.init.project.projectDir=java_lbproj