Skip to main content

Database Modularization

Modularized ADITO modules may define their own database tables and changes using alias definitions and Liquibase files.

Alias Definitions and targetAliasName​

Each module that introduces its own tables must define a dedicated Alias Definition. This includes the structure of the tables (AOD files) and links to Liquibase changelogs.

  • The Alias Definition must set the targetAliasName property.
  • This defines the central alias into which it will be merged (usually Data_alias or _____SYSTEMALIAS).
  • Target aliases like Data_alias are located in a shared module (e.g., sharedalias).

Liquibase Structure Per Module​

Each module contains:

  • A local aliasDefinition/ folder
  • A changelog.xml file that acts as entry point for module-specific Liquibase files
  • changesets/ and optionally demo/ or keywords/ subfolders

These changesets define schema changes, demo data, or static configuration values.

postinstall Logic and Changelog Merging​

When running npm install on the project module:

  1. All dependencies are installed into node_modules/
  2. The postinstall script scans all changelog.xml files from dependent modules
  3. It generates a merged changelog.xml inside the shared alias (e.g., sharedalias/Data_alias/)
  4. This merged changelog is then used during Liquibase execution

Prerequisites for Inclusion​

To be included in the merged changelog:

  • The module must define a valid targetAliasName
  • A changelog.xml file must exist under the alias definition
  • All dependencies must be ordered and resolvable (no cyclic dependencies)

Designer and CLI Execution​

Designer Execution (2024.2.1+)​

The Designer supports Liquibase execution from the dist/ folder if the checkbox "Execute in transpiled directory (dist)" is enabled.

  • Ensures compatibility with modularized changelog structure
  • Performs partial transpile before execution

CLI Execution​

For versions prior to 2024.2.1, use the Liquibase CLI or ADITO's VSCode extension:

  • Execute against the dist folder
  • The merged changelog.xml is required
  • VSCode extension offers update, drop-all, clear checksum etc.
warning

Liquibase checksums may differ between tools (CLI vs. Designer plugin). Use "Clear Checksums" if needed after switching environments.

Avoiding Changes to Existing Tables​

To ensure maintainability and future upgrade compatibility, existing database structures in shared or core modules should be left unchanged whenever possible.

  • Avoid altering shared database tables or columns defined in other modules.
  • Prefer creating new module-specific tables with their own aliases and structures.
  • If necessary, you may technically add columns to existing tables using Liquibase changesets, but this should be evaluated carefully.
  • In some cases, adding a new table with foreign key references is a better modular alternative.

ADITO developers should assess each case individually. As the modularization of ADITO projects advances, clear best practices will be established.