Tomcat Parallel Deployment: Deciding the Old Version's Role During a Schema Migration

Direct answer

Stop the prior version before applying a destructive schema change. Keep it active only during an additive, expand-phase migration where the old code tolerates new nullable columns or tables. If the migration drops columns, renames tables, or tightens constraints, the old version must not run against the new schema.

What Tomcat actually does

Parallel deployment keeps the older versioned WAR deployed so existing sessions continue to be served. New requests are routed only to the highest version number. This is confirmed behavior. The old context is not drained or stopped automatically; it remains a live application that can continue issuing database writes.

The compatibility boundary

The container does not manage database schemas. If the migration is non-backward-compatible, the old version will keep executing SQL shaped for the old schema. That leads to failed statements, silent data corruption, or session deserialization errors. If the migration is purely additive and the old code does not rely on SELECT * or strict schema validation, the old version can remain active through the expand phase.

Session attribute rules

Shared session attributes must be forward-compatible. New fields should be nullable or ignored by the old version. If object shapes change incompatibly, invalidate sessions or isolate session storage per version. Otherwise, expect ClassCastException or stale reads when the old version deserializes attributes written by the new version.

Safe deployment order

1. Deploy the new versioned WAR alongside the old one, for example app##002.war, ensuring it can operate against the current schema during the expand phase. Tomcat routes new requests to it.
2. If the migration is destructive, stop the old context before applying the schema change. Retain the old WAR file as a rollback artifact, but do not let it run against the migrated schema.
3. Apply the schema migration.
4. Verify the new version. If rollback is required, restore the reverse schema migration, then redeploy the old WAR as the active version.

Verification and version assumptions

Parallel deployment naming and session stickiness vary by Tomcat major version. Confirm the exact rules for your target release before relying on automatic routing. In staging, deploy two versioned WARs and apply a destructive migration to check whether the old context logs SQL errors. Use the Tomcat Manager to stop the specific versioned context; confirm the exact parameter syntax for your release before scripting it. Inspect a persisted session after deploying the new version to verify that the old version can still deserialize shared attributes.

One missing detail

Is your schema migration additive (expand) or destructive (contract)? That single fact determines whether the old version can remain active or must be stopped first.