Are there any guides / docs on upgrading from v2 to v4? Do i have to upgrade to v3 first?
I saw the docs mention that look at the release nodes to see whats changed but i was wondering if there were any definitive guides that serve as sort of checklist when upgrading from v2 -> v3 and v3 -> v4 for self-hosted zitadel.
1 Reply
Hi @Shardool, I'm an AI assistant for ZITADEL. While a team member reviews this question, I'll see if I can find relevant sources for your question.
Answer
Based on the available sources, there isn't a comprehensive upgrade guide that specifically covers v2 → v3 → v4 migrations as a checklist. However, I can provide some key information about these upgrades:
Critical Requirements for v3
For upgrading to ZITADEL v3, you must migrate from CockroachDB to PostgreSQL if you're currently using CockroachDB (1) . ZITADEL v3 requires PostgreSQL as a database and will not start if CockroachDB is configured . You can use the mirror command to migrate data to PostgreSQL before deploying v3 (2) (1) .
General Upgrade Process
From the community discussions, the general upgrade process involves (3) :
1. Backup your database
2. Read technical advisories for breaking changes
3. For versions ≥ 2.44.0, use the
--init-projections flag if you want migration to finish before runtime starts
4. Run zitadel setup between version upgrades (4)
5. Start the normal ZITADEL container when setup shows "setup successful" (3)
Potential Issues
Community members have reported various issues during major version upgrades, including migration errors (5) and functionality problems after upgrading to v4 (4) . Some users have needed to rollback and retry upgrades .
I wasn't able to find a direct answer for comprehensive upgrade guides, here are some relevant sources:
1. Technical Adv
isory 10015 : Details the CockroachDB to PostgreSQL migration requirement for v3
2. Mirror data from cockroach to postgres : Provides the migration process for database changes
For the most current and complete upgrade procedures, you may want to click the "Ask for help" button to have a team member provide specific guidance for your version upgrade path.
To learn more, see the sources I considered:
[1] Technical Advisory 10015
[2] Mirror data from cockroach to postgres
[3] Upgrade Zitadel from v2.37.3 to latest
[4] Discord message from @larzous on 2025-08-04
[5] [Bug]: Upgrade to v2.71.5 fails with migration error ("idp_templates6_ldap2" already exists)
Feel free to tag @Ask Inkeep with additional questions.