[Docs] Undocumented behavior: DataSource with "Update Only" / "Create and Update" drops all unrelated tables + missing `exclude-prefixes` documentation

[fractal3000]

Summary

When adding a new Data Source with DB Schema Management = "Update Only" or "Create and Update" (on an already existing database), Jmix/Liquibase silently drops all database tables that are not mapped to any Jmix entity. This behavior is undocumented, potentially destructive, and can lead to data loss in production environments.

Additionally, the settings available to mitigate this behavior (exclude-prefixes) are not documented anywhere in the official Jmix documentation.

---

Environment

• Jmix (all versions using Liquibase-based schema management)
• IntelliJ IDEA with Jmix Studio plugin

---

Steps to Reproduce

The issue manifests in two scenarios:

Scenario A — Update Only

1. Have an existing database with tables — some mapped to Jmix entities, some not (e.g., tables from a legacy system, external integrations, etc.)
2. In Jmix Studio, add a new Additional Data Source
3. Set DB Schema Management to Update Only
4. Run the application or apply the generated changelog

Scenario B — Create and Update on an existing database

1. Have an existing database with tables not mapped to any Jmix entity
2. In Jmix Studio, add a new Additional Data Source
3. Set DB Schema Management to Create and Update
4. Run the application or apply the generated changelog

---

Actual Behavior

All tables not associated with any Jmix entity are dropped. Only standard Liquibase service tables remain:

• DATABASECHANGELOG
• DATABASECHANGELOGLOCK

---

Expected Behavior

• With Update Only mode — Liquibase should only apply new changesets and leave unrelated tables untouched
• With Create and Update mode on an existing database — Liquibase should create missing entity tables and leave unrelated tables untouched

---

Impact

This behavior is silently destructive. A developer who is unaware of it can permanently lose data in a production database without any warning or confirmation prompt.

---

Workaround (Currently Undocumented)

Two undocumented settings exist to exclude tables from Liquibase management by prefix:

1. Per-project: application.properties

# Replace 'main' with your DataStore name
main.datasource.studio.liquibase.exclude-prefixes=legacy_,ext_,custom_

This instructs Jmix Studio to skip tables with the specified prefixes when generating changelogs.

2. Global: IntelliJ IDEA Registry

Via Help → Find Action → Registry, set the key:

io.jmix.liquibase.excludePrefixes=legacy_,ext_,custom_

This applies globally across all Jmix projects in the IDE.

Scope	Key	Effect
Per-project	<store>.datasource.studio.liquibase.exclude-prefixes	Affects specific DataStore only
Global (IDE)	io.jmix.liquibase.excludePrefixes	Applies to all projects in IDE

---

What Should Be Documented

1. The drop behavior itself — clearly explain that both Update Only and Create and Update modes will remove tables not associated with Jmix entities when applied to an existing database
2. exclude-prefixes property — document both the application.properties key and the IDE Registry key, with examples
3. A warning in the "Add Data Source" wizard or in the DB Schema Management documentation about the destructive nature of this behavior
4. Limitation: exclude-prefixes works only by prefix — tables without a common prefix cannot be excluded individually. This limitation should also be noted.

---

Suggested Documentation Location

• Jmix Docs: Data Sources
• Jmix Docs: Liquibase
• Jmix Studio "Add Data Source" wizard — inline warning or tooltip

---

Additional Notes

These settings were discovered empirically (by encountering data loss) and through source code inspection — not through official documentation. Given how destructive the default behavior is, proper documentation is critical for developer safety.