Upgrading from Pega 8.7 to Pega 25 requires checking four compatibility layers before you touch the update tool: the Java runtime and application server, the database version and schema, the deprecated rules and APIs in your application, and the Pega Cloud versus on-premises deployment model. Pega 25 also adds Constellation-first UI, generative AI agents, and Pega GenAI Blueprint, which change design assumptions more than earlier releases did.
Prerequisites: What Pega 25 Actually Requires Under the Hood
Pega 25 is a major-version jump, not an incremental patch. The platform runs only on a supported Java long-term-support release and a supported application server, and Pega publishes a Platform Support Guide that lists exact combinations. Check that guide against your stack before scheduling anything, because an unsupported JVM or servlet container blocks the update outright.
The database is the second hard gate. Pega certifies specific versions of PostgreSQL, Oracle, Microsoft SQL Server, and other databases per release. A database that worked on 8.7 may fall outside the Pega 25 certification matrix. Schema changes also run during the update, so verify tablespace headroom and backup restore time before you start.
The deployment model is the third gate, and it is the one teams underestimate. Pega Cloud customers get the upgrade orchestrated by Pega on a scheduled window. On-premises and self-managed customers own every step, including the update tool, the temporary database, and rollback. The same version number means very different work depending on where you run it.
A fourth gate sits inside your application rather than the platform. Rules that use deprecated APIs, custom Java steps, or direct database calls can compile on 8.7 and fail on Pega 25. The Pega Upgrade Assistant and the pre-upgrade compliance scan surface most of these, but the scan reports only what it can parse. Plain-language version: the platform checks the platform, and you must check your code.
How the Upgrade Mechanism Works, Step by Step
The update runs in two phases, and conflating them is the most common planning error. Phase one is the platform update itself, which replaces binaries, migrates the system schema, and rebuilds the ruleset inventory. Phase two is application migration, where your rulesets, data transforms, and integrations are revalidated against the new engine.
During phase one, the update tool extracts your existing schema into a staging database, applies built-in schema changes, and then merges the result back. This is why disk space and database privileges matter more than raw CPU. The staging step roughly doubles the database footprint for the duration of the run, so provision for it explicitly.
Phase two exposes the real risk. Pega 25 resolves rules at runtime with stricter validation than 8.7 did for several rule types, particularly around data pages and declarative processing. A rule that silently tolerated a missing property in 8.7 can now raise a validation error. The upgrade compatibility scan is designed to catch this, but only if the scan runs against a representative copy of production, not a trimmed-down development instance.
One counterintuitive detail: a clean development upgrade proves less than teams expect. Development instances usually lack the volume, the custom authentication chain, and the integration endpoints that production has. The compatibility report from a small dev instance can look green while production fails on the first authenticated request.
Timeline: Realistic Phases for an 8.7 to Pega 25 Move
| Phase | Typical duration | What must be true to exit |
|---|---|---|
| Inventory and readiness assessment | 2 to 4 weeks | Stack matches the support matrix; deprecated-rule list drafted |
| Compatibility scan on production clone | 1 to 2 weeks | Scan findings triaged; blocking items have owners |
| Remediation of rules and integrations | 4 to 12 weeks | Deprecated APIs replaced; custom Java recompiled |
| Pre-production upgrade rehearsal | 1 to 2 weeks | Full update run completes; smoke tests pass |
| Production upgrade window | 1 to 3 days | Rollback verified; core case types functional |
| Post-upgrade stabilization | 2 to 6 weeks | Defects below the agreed threshold; AI features assessed |
These ranges assume a mid-size application with moderate customization. A heavily customized application with deep Java steps can double the remediation phase. Treat the table as a planning envelope, not a commitment, and re-baseline after the compatibility scan returns real findings.
New Features Added in Pega 25 and What They Change
Pega 25 leans hard into Constellation, Pega's React-based UI architecture, and into generative AI. Constellation-first design means sections, harnesses, and layouts are authored in the Constellation model rather than the legacy section-based model. Applications still on section-based UI in 8.7 continue to work, but new UI investment flows toward Constellation.
Pega GenAI Blueprint generates application scaffolding from a described business process. Pega GenAI agents and the assistant capabilities embed large-language-model interactions into case workflows. These features are governed by Pega's AI configuration and typically require explicit enablement plus a connected AI provider or Pega-hosted service.
The upgrade implication is architectural, not cosmetic. AI-driven features assume well-structured case data and clean data-page design. An application that carried legacy data transforms forward without cleanup will find GenAI features brittle. Plan a data-model review alongside the version move, not after it.
A professional caveat: do not enable new AI features during the upgrade window itself. Enable the platform first, stabilize it, then turn on GenAI capabilities in a controlled follow-up. Bundling both increases the failure surface and makes rollback decisions ambiguous.
Edge Cases and Red-Flag Warnings
The upgrade path is not uniform. Some 8.7 environments can move directly to Pega 25; others must stage through an intermediate release first. Pega documents supported upgrade paths per release, so confirm yours rather than assuming a single hop.
Custom Java steps that call internal Pega APIs can break without a compile error, failing only at runtime under load. Direct SQL or JDBC calls against Pega schema tables are vulnerable to schema changes introduced in the update. Custom authentication and SSO configurations often need revalidation because security defaults shift between major versions. Rule resolution changes can alter which rule version wins at runtime, silently changing behavior in production. Third-party integration libraries pinned to old versions may fail the compatibility scan and block the update. Skipping the production-clone scan and upgrading dev first is the single most common cause of late-stage failure.
Each of these is a red flag, not a certainty. Treat any one of them as a reason to extend the remediation phase rather than compress the schedule.
Misconceptions That Derail Upgrade Projects
The most persistent misconception is that a successful update-tool run equals a successful upgrade. The tool reports schema and platform migration status, not application behavior. A green tool result with an untested application is an unfinished upgrade.
A second misconception is that Pega Cloud and on-premises follow the same checklist. They share the compatibility scan and remediation work, but Cloud customers do not control the update window and cannot stage the database the same way. Assuming Cloud parity with on-premises leads to misallocated effort.
A third is that deprecated features stop working immediately. Most deprecated rules continue to function in Pega 25, which is precisely the danger: they work until a future release removes them. Deprecation is a warning with a shelf life, not a switch. Teams that defer remediation accumulate debt that surfaces at the next major upgrade.
Plain-language version: deprecated does not mean broken today, but it means broken eventually, and the eventually is closer than it looks after a major-version jump.
Comparative View: Upgrade Approach Options
| Approach | Control over timing | Risk profile | Best fit |
|---|---|---|---|
| Pega-orchestrated Cloud upgrade | Low | Lower operational risk, less rollback control | Standard Cloud applications |
| Self-managed on-premises upgrade | High | Higher operational risk, full rollback ownership | Regulated or heavily customized stacks |
| Single-hop direct upgrade | Medium | Depends on supported-path confirmation | Applications on a documented direct path |
| Staged upgrade via intermediate release | Medium | Lower per-step risk, longer total timeline | Applications on an unsupported direct path |
| Big-bang with extended freeze | Low | Highest blast radius | Rarely justified |
| Phased with parallel run | High | Lowest blast radius, highest cost | Mission-critical case workloads |
The comparison is not a ranking. A phased parallel run is the safest option and also the most expensive; a direct single-hop is fastest and depends entirely on path confirmation. Choose by risk tolerance and by what the support matrix allows, not by what the vendor demo emphasized.
Practical Actions and Thresholds Before You Commit
Start with evidence, not scheduling. Run the Pega Upgrade Assistant and the pre-upgrade compliance scan against a full production clone. Triage findings into blocking, high, and low categories, and refuse to set a production date until every blocking item has a named owner and a resolution.
Confirm the support matrix explicitly for your Java version, application server version, database version, and operating system. If any one of them is outside the matrix, upgrade that component first and re-run the scan. Do not attempt to upgrade the Pega platform and the surrounding stack in the same window.
Budget the staging database at roughly twice your current data footprint, and rehearse a restore of the pre-upgrade backup until it completes inside your rollback window. A rollback plan you have not timed is a plan you do not have.
Run a full pre-production rehearsal of the update, including authentication, at least one end-to-end case type, and one integration endpoint. Smoke tests that skip authentication miss the most common production failure. After production upgrade, hold new AI feature enablement for a separate, stabilized window.
Set explicit exit thresholds: zero blocking scan items, all core case types passing in rehearsal, and a measured, tested rollback time. If any threshold is unmet, move the date rather than lower the bar.
Limits of This Guidance and What to Verify Locally
This article describes stable mechanisms and the general shape of the 8.7 to Pega 25 move. Exact version numbers, supported-path details, and feature availability change with each Pega release and are documented in Pega's own support matrix and release notes, which you should read directly. Environment-specific factors such as customization depth, data volume, and deployment model determine your real timeline, and only a scan against your own production clone can quantify them. Treat every duration here as a planning envelope to be replaced by measured data. Verify current support status with Pega before committing to a date.
This article is general educational information about software upgrade planning, not a professional implementation, security, or compliance opinion. It does not promise upgrade outcomes or timelines. Consult a qualified Pega-certified architect or your Pega account team for decisions specific to your environment.