Introducing Agent Safe Governance for the AI Era

Read the Blog

Size JVM heap and RAM for diff-class commands

Last updated: July 8, 2026

Diff-class commands — snapshot, snapshot-reference, diff, diff-changelog, and generate-changelog — can exhaust JVM memory on large schemas, causing OutOfMemoryError failures or long pauses from garbage collection. This happens because each command loads a model of your database objects into memory; diff and diff-changelog load two models at once, one for each side of the comparison. This guidance is based on measurements against Oracle and SQL Server schemas of different sizes, using the default G1GC garbage collector.

Before you begin

Budget your JVM heap using the following rules of thumb:

  • snapshot and generate-changelog: approximately 3 GB of heap per million objects (one schema resident, column-heavy worst case, scales linearly)

  • diff and diff-changelog: roughly double the per-schema amount (both target and reference schema resident at once)

  • Recommended -Xmx values in the tables below are roughly 1.5× the observed peak heap

Procedure

1

Count the objects in your schema

Count the total number of objects in your schema: tables, views, indexes, sequences, procedures, and so on. You'll use this count to find the matching row in the sizing table in the next step.

2

Find your sizing table

snapshot and generate-changelog sizing (one schema resident)

Objects per schema

Up to 100k

Peak heap

~0.4 GB

Min -Xmx

512m-1g

Recommended -Xmx

2g

Objects per schema

~1m

Peak heap

~3.6 GB

Min -Xmx

4g

Recommended -Xmx

6g

Objects per schema

~2m

Peak heap

~4.4-5.8 GB

Min -Xmx

4g (SQL Server) / 6g (Oracle)

Recommended -Xmx

8g

diff and diff-changelog sizing (target + reference resident)

Objects per schema

Up to 100k

Peak heap

~1-2 GB

Min -Xmx

2g

Recommended -Xmx

4g

Objects per schema

~1m

Peak heap

~4 GB

Min -Xmx

4g

Recommended -Xmx

6g

Objects per schema

~2m

Peak heap

~6.5-8.6 GB

Min -Xmx

6g (Oracle) / 8g (SQL Server)

Recommended -Xmx

12g

3

Convert heap to RAM

Don’t provision machine RAM equal to your -Xmx value. That’s JVM heap only. Size RAM above it: RAM ≈ -Xmx + ~1 GB for metaspace, thread stacks, code cache, and buffers. Add further headroom if your database is co-located on the same machine.

Recommended -Xmx (heap)

2g

Plan RAM for JVM

~3 GB

Recommended -Xmx (heap)

6g

Plan RAM for JVM

~7 GB

Recommended -Xmx (heap)

8g

Plan RAM for JVM

~9-10 GB

Recommended -Xmx (heap)

12g

Plan RAM for JVM

~13-14 GB

4

Understand what affects run time

SQL Server diff runs heavier than Oracle at the same object count, because diff-class commands on SQL Server are metadata-latency-bound rather than heap-bound. Actual run time also depends heavily on network latency between Liquibase and the database, storage performance, and current database load.

Because these factors vary by environment, this guidance doesn't publish expected run times. Run a test invocation against a non-production copy of your schema to establish a baseline before scheduling production runs.

Heap usage is driven primarily by object count, dominated by columns. Stored procedures, packages, and package bodies add comparatively little heap (their bodies are streamed to files) but they do add proportionally more processing overhead.

Note: If any object type in your schema exceeds 100k rows, set -Dliquibase.sql.maxResultSetSize=5000000. Without it, snapshot and diff abort quickly instead of streaming through the large result set.

5

Run the command

Set -Xmx to the Recommended value from step 2:

Bash
JAVA_OPTS="-Xms512m -Xmxyour_xmx_value" liquibase your_command

Be sure to:

  • Replace your_xmx_value with the Recommended -Xmx value from step 2, including the unit. For example, 6g, 12g

  • Replace your_command with the command you're running. For example, generate-changelog, diff

For example
loading

Troubleshooting heap errors

A genuine heap exhaustion throws OutOfMemoryError: Java heap space (or GC overhead limit exceeded). Liquibase writes this to the console and to --log-file, and the command exits non-zero, but the output is a raw JVM stack trace rather than a suggestion to raise -Xmx. Use the sizing guidance above to choose the right value up front rather than discovering it after a failure. On large-object schemas, the maxResultSetSize guard described in step 4 usually fails first, with an explicit, actionable message rather than a JVM crash. For example:

Query exceeded maximum result set size of 100000 rows… increase liquibase.sql.maxResultSetSize

Note: Liquibase does not print peak heap usage by default. The peak-heap figures in this guidance came from GC logs and process RSS. To observe peak heap live, add -Xlog:gc*:file=gc.log to JAVA_OPTS.

What to do next