ZITADEL v2 to v3 — what do I need to change?
Decide whether a self-hosted identity platform can stay on ZITADEL v2 or must plan a v3 migration now that the roadmap ties v3 to a license change and CockroachDB support removal.
Blockers
- CockroachDB support removed in v3 and beyond
- package/zitadel-v3 incompatible with runtime/cockroachdb: ZITADEL explicitly states CockroachDB is discontinued in v3 and beyond
Who this is for
- cost-sensitive
- compliance
- enterprise
Candidates
Stay on ZITADEL v2 short-term
As of 2026-04-08, ZITADEL's roadmap shows v3 as General Availability / Stable, while v2 remains available but is no longer the forward path. v3 is the release that changed the core license from Apache 2.0 to AGPLv3 and removed CockroachDB support. If you are self-hosting v2 and need to avoid the AGPLv3 change immediately, staying on v2 preserves the older licensing position for now. Public self-host commercial pricing is not listed; ZITADEL says customers who cannot use AGPL 3.0 should contact sales for a commercial license, and enterprise self-hosted pricing is custom.
When to choose
Use this only as a temporary hold if you are already on PostgreSQL, your current v2 deployment is stable, and the AGPLv3 change creates legal or procurement delay. The decisive factor is whether delaying the license review is more important than moving onto the actively current major version.
Tradeoffs
Lowest immediate migration effort and avoids taking the v3 license change right now, but it leaves you off the current major line and pushes migration work later.
Cautions
Do not treat this as a durable strategy if you need current-major support posture. If you are still on CockroachDB, v2 is effectively your last ZITADEL line without a database migration because v3 and later drop CockroachDB.
Plan and execute a migration to ZITADEL v3 now
As of 2026-04-08, ZITADEL v3 is GA/stable and is the release line that switched licensing to AGPLv3, introduced Actions V2, and removed CockroachDB support. ZITADEL explicitly states CockroachDB is discontinued in v3 and beyond and provides a mirror-based migration guide from CockroachDB to PostgreSQL. For organizations that cannot use AGPLv3, ZITADEL's documented path is a commercial license via sales, with enterprise pricing listed as custom rather than public. ZITADEL also states self-hosting support is available under an enterprise agreement.
When to choose
Use this if you want to stay on the active major line, especially if you need future ZITADEL features or a supported path beyond v2. The decisive factor is that any CockroachDB-backed deployment must migrate databases before or during the v3 move.
Tradeoffs
Keeps you on the current major release and avoids further delay, but it may require both a legal review of AGPLv3 and an operational CockroachDB-to-PostgreSQL migration.
Cautions
The database migration is not optional for CockroachDB users. The mirror workflow has prerequisites and limitations, including destination initialization, key handling, and verification steps, so treat this as a real platform migration rather than a simple version bump.
Try with your AI agent
$ npm install -g pocketlantern $ pocketlantern init # Restart Claude Code, Cursor, or your MCP client, then ask: # "ZITADEL v2 to v3 — what do I need to change?"