Liquibase changelog size limits for checks command

Applies to

• Liquibase Secure (Pro)

Conditions

• Running Liquibase checks command
• Large changelog scripts (~20-30MB, ~150k lines)
• Deploying multiple scripts (e.g., three at a time)
• Default Java heap space settings may not be sufficient

Question

Is there a size limit for changelog scripts (file size or number of lines) that would allow us to objectively determine whether a script is considered "large" for Liquibase checks?

Answer

Liquibase does not have a strict documented limit for changelog size. However, our engineering team tested various changelog sizes to estimate Java heap space usage and found the following:

Heap space usage vs. file size (observed):

• 3.9 MB file → 1.9 GB heap space
• 7.7 MB file → 2.5 GB heap space
• 15.5 MB file → 3.0 GB heap space
• 30.9 MB file → 4.5 GB heap space

General rule for heap space usage:

Required Heap (GB) = 1.2 + (0.1 * File Size in MB)

For example, a 10MB changelog roughly requires 2.2GB of heap space. However, this is a rough estimate and should not be used as a hard limit.

Key considerations

• Always add extra buffer memory. Running Liquibase at just the calculated minimum may lead to out-of-memory errors.
• Memory usage can vary significantly based on:
  • Checks run inside a flow
  • Custom or poorly optimized regular expressions in checks
  • Python-based custom checks with suboptimal memory handling

Recommendation: If your changelog size suggests 2.2GB of heap space, configure additional headroom (e.g., 3GB or more) to avoid memory issues.

Related Article(s)

• Liquibase Checks Command Documentation
• Configuring Java Memory for Liquibase