Skip to main content

Liquibase 4 Integration for Visual Studio Code

The Liquibase 4 Integration extension allows you to run official Liquibase CLI commands from Visual Studio Code. You can select a database configuration, choose a changelog, provide command options, and execute the command without opening a separate command-line window.

The extension is developed by ADITO and is included in the ADITO Extension Pack. It is not limited to ADITO projects and can be used with any project that uses Liquibase.

note

Liquibase is a registered trademark of Liquibase, Inc. This extension is not affiliated with or endorsed by Liquibase, Inc. Liquibase is licensed separately under the Functional Source License (FSL-1.1).

Install the extension​

Install the extension from the Visual Studio Code Marketplace, or install the ADITO Extension Pack, which includes it together with other development tools.

After installation, open the extension walkthrough for a short introduction to its main features.

Create a Liquibase configuration​

Every command that connects to a database requires a liquibase.properties file. The file contains the connection details that Liquibase uses to access the database.

For ADITO projects, you do not usually need to create these configuration files manually. Use the JS DevTools scripts to generate them from the existing ADITO server configuration:

After generation, the files are available in the project's data/liquibase folder and can be added to the Liquibase extension.

For other Liquibase projects, or when a generated configuration needs to be adjusted, you can create or add a configuration directly in Visual Studio Code.

To create a configuration in Visual Studio Code:

  1. Open the Command Palette with Ctrl+Shift+P (Cmd+Shift+P on macOS).
  2. Run Liquibase: Create Liquibase Configuration.
  3. Enter the required database connection details.

To use an existing configuration, run Liquibase: Add existing liquibase.properties to the configuration... instead.

By default, the extension stores created and added configurations in data/liquibase. You can change this location with the liquibase.configurationPath setting. Existing configurations can be edited with Liquibase: Edit existing Liquibase Configuration.

warning

Liquibase configuration files can contain database credentials and other sensitive information. Do not commit these files or the configuration folder to version control. Add them to .gitignore instead.

Execute Liquibase commands​

Liquibase commands are available from the Liquibase item in the Visual Studio Code status bar and from the Command Palette.

Most commands follow the same sequence:

  1. Select the database configuration.
  2. Select the changelog, if the command requires one.
  3. Select the Liquibase contexts, if the command supports contexts.
  4. Provide any additional command options.

The extension passes the selected options to the Liquibase CLI and executes the corresponding command.

You can also run changelog-related commands from the context menu. The Liquibase submenu is available for XML, JSON, YAML, YML, and SQL files because these formats can contain Liquibase changelogs. When you start a command from a context menu, the selected file is used as the changelog.

The extension supports the following commands. The names below are the commands shown by the extension:

  • Compare two databases (diff) compares two database schemas.
  • Clear the checksums of all changelogs in the database clears stored changelog checksums.
  • Create Tag creates a tag in the database.
  • Drop-all drops all database objects.
  • Generate Changelog generates a changelog from a database.
  • Generate database documentation (db-doc) generates HTML documentation for a database.
  • Generate SQL File for incoming changes generates SQL for pending changes.
  • List all deployed changesets (history) lists changesets that have already been deployed.
  • List the not deployed changesets (status) lists pending changesets.
  • Mark not deployed changelogs as executed (changelog-sync) marks pending changelogs as executed without running them.
  • Rollback to Tag rolls the database back to a selected tag.
  • Tag Exists checks whether a tag exists in the database.
  • Update applies pending changesets to the database.
  • Unexpected Changesets checks for changesets that are not expected in the current database state.
  • Validate validates the changelog and its configuration.

The extension does not support every command provided by the Liquibase CLI. For command-specific details, see the Liquibase command documentation.

Differences from the ADITO Designer​

The existing ADITO Designer provided Liquibase update and Liquibase drop. It also provided the combined drop-all and update command, which executed both commands in sequence.

The combined drop-all and update command is not available in the Visual Studio Code extension because it is not a standard Liquibase command. To perform the same workflow, execute Drop-all first and Update afterwards. Review the selected database and changelog carefully before executing either command.

Review your database with an overview​

The Overview action in the status bar generates an HTML report for the selected database and its changelogs.

liquibase-overview.png Figure: Overview action in the status bar

The report can include:

  • the current table structure, including columns and indexes;
  • the authors of the changesets referenced by the root changelog; and
  • pending changes.

The extension writes the generated files to a temporary directory and opens the index.html file when the report is ready. To choose an output location explicitly, use Liquibase: Generate database documentation (db-doc).

Work with Liquibase contexts​

Commands that support contexts prompt you to select how the contexts should be loaded:

  • You can use recently loaded contexts for the selected database connection.
  • You can load all contexts from the root changelog and its included files.
  • You can execute the command without contexts.

Recently loaded contexts are cached separately for each database connection.

Convert changelog formats​

Use the following commands to convert changelogs between supported Liquibase formats:

  • Liquibase: Converts a file from one Liquibase format to another;
  • Liquibase: Converts a folder from one Liquibase format to another.

Review the generated files carefully. The extension cannot guarantee complete or correct conversion results. In particular, include and includeAll elements are subject to Liquibase conversion limitations, and converting files with preConditions to YAML or JSON can produce invalid results.

Manage cached values​

During command execution, the extension caches the recently loaded contexts and the five most recently selected changelogs for each liquibase.properties file. Use the following commands to inspect or clear these values:

  • Liquibase: Cache: Open the file with the recently loaded elements;
  • Liquibase: Cache: Remove any values from the recently loaded elements.

Manual editing of the cache file is not recommended.

View logs​

The extension writes command output to the Liquibase output channel. Open the output panel, run Output: Focus on Output View, and select Liquibase from the channel list.

Extension logs are also stored in the operating system's extension log folder. To open the folder, run Developer: Open Extension Logs Folder and locate the Liquibase log files.