General DiscussionCan I upgrade directly from Dify v1.9.2 to v1.16.1 while preserving all data?

[gongchangping]

Self Checks

• I have searched for existing issues search for existing issues, including closed ones.
• I confirm that I am using English to submit this report (我已阅读并同意 Language Policy).
• [FOR CHINESE USERS] 请务必使用英文提交 Issue，否则会被关闭。谢谢！:)
• Please do not modify this template :) and fill in all the required fields.

Content

I currently deploy Dify v1.9.2 via docker-compose and use the built-in PostgreSQL with pgvector. I need to retain all existing application, conversation and knowledge base data after the upgrade.
My main business scenarios: Chat Apps, Knowledge Base and Workflows.
I have several questions:
Is direct upgrade from v1.9.2 to v1.16.1 supported? Are there any known database migration compatibility risks?
If a direct upgrade is not recommended, do I need to upgrade incrementally (e.g. upgrade to v1.15.0 first, then upgrade to v1.16.1)?
Could you provide the complete safe upgrade steps to prevent data loss?
Are there breaking changes in configuration, environment variables or docker-compose files I need to pay attention to?
Deployment information:
Deployment way: docker-compose
Database: Default PostgreSQL container with pgvector
No external vector database
Thanks for your advice.

[dosubot[bot]]

Yes, a direct upgrade from v1.9.2 to v1.16.1 is supported — Dify's Alembic-based migration system handles sequential schema changes automatically, and no incremental upgrades are needed. All your data (apps, conversations, knowledge bases, workflows) will be preserved [1]. In fact, this is essentially the same upgrade path you asked about previously in discussion #39009, just targeting 1.16.1 instead of 1.15.0.

Here are the complete steps:

1. Back up everything first:

docker compose exec db pg_dump -U postgres dify > dify_backup_1.9.2.sql
cp -r ./volumes ./volumes_backup

2. Pull new images and restart:

cd docker
git pull
docker compose pull
docker compose up -d

3. Run database migration (runs automatically on startup if MIGRATION_ENABLED=true, which is the default, but you can also run manually) [1]:

docker compose exec api flask upgrade-db

4. Run the plugin backfill (required when upgrading past 1.15.0 — must be run manually) [2]:

docker compose exec api flask backfill-plugin-auto-upgrade

5. Apply the model_type SQL fix — 1.14.x renamed enum values without migrating existing rows. Run this against your dify database if you see "Credentials unavailable" in the UI [3]:

-- Run for each table: provider_models, provider_model_credentials,
-- tenant_default_models, provider_model_settings, load_balancing_model_configs
UPDATE provider_models SET model_type = 'llm' WHERE model_type = 'text-generation';
UPDATE provider_models SET model_type = 'text-embedding' WHERE model_type = 'embeddings';
UPDATE provider_models SET model_type = 'rerank' WHERE model_type = 'reranking';
-- (repeat the same 3 UPDATE statements for the other 4 tables)

If tenant_default_models throws a duplicate key error (SQLSTATE 23505), delete the stale rows first:

DELETE FROM tenant_default_models WHERE model_type IN ('text-generation','embeddings','reranking');

6. Clean up stale plugin directories from ./volumes/plugin_daemon/plugin/ once plugins are confirmed working in the UI [4].

Breaking changes to watch for between 1.9.2 and 1.16.1:

Change	Action
SSRF proxy default-deny (1.15.0)	If workflows or HTTP-request nodes call internal/private URLs, add SSRF_PROXY_ALLOW_PRIVATE_DOMAINS and/or SSRF_PROXY_ALLOW_PRIVATE_IPS to .env [3]
DB_TYPE env var required (1.15.0)	Add DB_TYPE=postgresql to your .env [3]
Duplicate plugin_unique_identifier (1.13→1.14 path)	If the plugin daemon crashes with SQLSTATE 23505, deduplicate the dify_plugin.plugins table [5]
Agent V2 (1.16.0)	Enabled by default; adds agent_backend and local_sandbox services to docker-compose. No action required unless you want to disable it [6]
docker-compose.yaml is auto-generated	Don't edit docker-compose.yaml directly — all customization goes into docker/.env [1]

Compare the new .env.example against your existing .env to catch any new required variables. If you run into specific errors during the upgrade, share the logs and I can help troubleshoot.

To reply, just mention @dosu.

---

Share context across your team and agents. Try Dosu.