Upgrade Guide
This document lists the notable changes for each Erupt release. Read the sections in version order.
V 2.4.0 Upgrade Guide
This section covers what to watch for when upgrading from 2.3.x to 2.4.0.
Requirements
| Item | Requirement |
|---|---|
| Erupt | Upgrade every dependency to 2.4.0 |
| Spring Boot | 3.5.16, same as 2.3.x, no change needed |
| JDK | JDK 17 minimum, unchanged; builds on JDK 27 are verified |
| Database | No new minimum version; schema changes below |
| erupt-cloud | The server and every node must move to 2.4.0 together: power and payload checks, references, Excel and uploads now happen on the server, so old nodes no longer match its protocol |
| erupt-flow / erupt-tenant / erupt-cube | Upgrade to their 2.4.0 releases |
Step 1: Change the Dependency Version
<properties>
<erupt.version>2.4.0</erupt.version>
</properties>No artifactId was renamed, so 2.3.x coordinates keep working. The one module move is the Kubernetes admin: the web terminal left erupt-data-k8s for the standalone erupt-k8s-dashboard, so projects that use the terminal add that dependency instead.
Step 2: Add New Modules (Optional)
2.4.0 open-sources the modules below. Leaving them out changes nothing; adding one seeds its menus and tables on first start. erupt-spring-boot-starter-all already includes the first six.
| Module | artifactId | Purpose |
|---|---|---|
| Public links | erupt-share | One link opens a form or any menu page to the public |
| Outbound webhooks | erupt-webhook | Add / update / delete events POSTed to external URLs |
| Runtime settings | erupt-config | Settings layered by Spring profile, applied on save |
| Record history | erupt-revision | Field-level history, rollback and a recycle bin |
| File center | erupt-file-center | Browse the upload directory, local folders, S3 and SFTP |
| AI software delivery | erupt-ai-dev | Requirement pool plus coding CLIs; nothing runs while no CLI is installed on the server |
| Node Lite | erupt-cloud-node-lite and -solon / -quarkus / -micronaut / -vertx / -ktor / -servlet | erupt-cloud nodes without Spring |
Before adding erupt-revision
Every model records history by default. Add @Power(revision = false) first to models with sensitive fields that are not PASSWORD fields, or with very frequent writes.
Breaking and Behavior Changes
1. Export Is On by Default Default changed
@Power(export) now defaults to true, and the role's menu buttons decide who may export, as they do for add / edit / delete. Menus created from now on carry the Export button; existing menus are left as they are. Write @Power(export = false) on models that must not be exported and @View(export = false) on columns that must stay in. See @Power.
2. Choice Values and Declared Limits Are Enforced on the Server Default changed
erupt.choice-validateis on: add, edit, cell edit and Excel import refuse CHOICE / MULTI_CHOICE values outside the options the user is offered. A value equal to the stored one passes, so old data does not block editing. Opt a field out with@ChoiceType(validate = false), or everything witherupt.choice-validate: false. See CHOICE.- INPUT length, NUMBER / SLIDER ranges, RATE bounds, TAGS count and allowed values, DATE FUTURE / HISTORY and ranges, and every sub-table row's rules run on the server. Clients that write out-of-range values straight through the API are refused. See server-side enforcement.
3. erupt.init-method-enum Becomes erupt.init-modules-menu Property renamed
Module menus no longer rely on .erupt/<module>.loaded marker files. A fingerprint is stored in the new e_upms_module table and reconciled on every start: new menus and buttons of a module arrive, fields an admin edited are kept, and menus a module stops declaring are disabled rather than deleted. The default admin account is created once per database.
erupt:
init-modules-menu: true # replaces init-method-enum; false seeds no menus and runs no initFunProjects that set init-method-enum: none switch to init-modules-menu: false. See Menu Management.
4. X-Forwarded-For Is Believed Only from a Trusted Proxy Check reverse proxies
The client IP keys the login lock and the IP whitelist. From 2.4.0 X-Forwarded-For is read only when the direct peer is a trusted proxy, loopback and private ranges by default; Proxy-Client-IP and WL-Proxy-Client-IP are no longer read. A reverse proxy on a public address must be added, otherwise every user shows up as the proxy's IP and the login lock hits everyone at once:
erupt:
upms:
trusted-proxies: 127.0.0.0/8,::1,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16,203.0.113.105. upms Tables Gain a Tenant Column and Per-tenant Uniqueness Schema change
e_upms_user / e_upms_role / e_upms_org / e_upms_post and the login log, operation log and comment tables gain a tenant_id column ('0' for the platform), filtered by Hibernate @TenantId. Projects without multi-tenancy notice nothing; custom SQL inserting into these tables may set tenant_id = '0', though the column has that default. SQL in Database Changes below.
6. erupt-tenant Refactor: Tenant Users Move into the upms Tables Manual migration
erupt-tenant no longer keeps a user directory of its own: tenant users, roles and orgs share e_upms_user / e_upms_role / e_upms_org with the platform, told apart by the Hibernate @TenantId column tenant_id. Tenant menus no longer have a table either; packages point at the platform menus directly.
Removed tables (2.4.0 neither creates nor reads them):
| Table | Was | In 2.4.0 |
|---|---|---|
e_tenant_menu | Tenant menus | Packages pick from the platform's e_upms_menu |
t_e_upms_user, t_e_upms_user_role | Tenant users and their roles | e_upms_user, e_upms_user_role |
t_e_upms_role, t_e_upms_role_menu | Tenant roles and their menus | e_upms_role, e_upms_role_menu |
t_e_upms_org | Tenant orgs | e_upms_org |
Removed classes: TenantUpmsUser, TenantUpmsUserSimple, TenantUpmsRole, TenantUpmsOrg (with their DataProxies and handlers) and EruptTenantMenu; use erupt-upms's EruptUser / EruptRole / EruptOrg instead.
The upgrade does not migrate old rows. Before starting 2.4.0:
- Drop the old single-column unique indexes on
e_upms_user.account,e_upms_role.code,e_upms_org.code,e_upms_post.codeande_upms_sso.code(find their names withSHOW INDEX FROM <table> WHERE Non_unique = 0;). - Copy each tenant's users / roles / orgs from
t_e_upms_*into the matchinge_upms_*table withtenant_idset to that tenant'se_tenant_config.tenant_id, or re-create them in the tenant admin. - Package menus are now picked from the platform's
e_upms_menu;e_tenant_menuis no longer used, so tick the menus again.
/tenant/change-pwd, /tenant/menu and /tenant/userinfo are removed; a tenant session uses the platform's /change-pwd, /menu and /userinfo. /tenant/subscription is now /tenant/info. See Multi-tenant UPMS.
After the refactor, every module built on erupt-upms is tenant-isolated with no extra work:
- erupt-flow: flow definitions, groups and instances are kept per tenant, approvers resolve within the instance's tenant, and the scheduler advances each instance in its own tenant's session; see erupt-flow multi-tenancy
- erupt-sso: a tenant can configure its own identity providers, listed on the tenant login page, and single sign-on opens a tenant session
- Login log / operation log / online users / record comments / record history: a tenant sees only its own rows
- Subscription and trial: package trial days, a grace period after expiry, and locking; see Subscription and Trial
7. Printing No Longer Grants Reading a Record Permission tightened
@Power(print) is a model switch only. Printing and reading a record by id both require edit or viewDetails and check the record's row scope, so models with viewDetails = false no longer show print buttons. Template print names a saved template with ?config=<id> and no longer accepts template content in the request body; clients calling the print endpoint themselves must adapt. See Print.
8. Components Are Inferred from the Java Type
EditType.AUTO now follows the field type: an enum becomes CHOICE, Collection<Enum> MULTI_CHOICE, Map KEY_VALUE, an @Erupt type a reference, a collection a sub-table. DateType.Type defaults to AUTO, so LocalDateTime shows as date-time and LocalTime as time. Projects that relied on the old DATE default for LocalDateTime fields will see date-time pickers. See AUTO.
9. Removed Capabilities
- The Requesty and OrcaRouter LLM adapters are gone; move those models to OpenRouter or the Open AI Adapter
- erupt-ai-decision's HTTP endpoints are removed; the Java API is unchanged
- erupt-ai-dev has no
executor.enabledswitch: an installed coding CLI is the switch
Default Value Changes to Watch
| Item | 2.3.x | 2.4.0 |
|---|---|---|
@Power(export) | false | true |
@Power(batchEdit) | — | true, tables show a Batch edit button |
@Power(revision) | — | true, effective with erupt-revision |
erupt.choice-validate | — | true |
erupt.init-modules-menu | init-method-enum: file | true |
erupt.upms.trusted-proxies | X-Forwarded-For from anyone | Loopback and private ranges |
DateType.Type | DATE | AUTO, inferred from the Java type |
EditType.AUTO on an enum field | INPUT | CHOICE with the enum constants |
erupt-config refresh-seconds | — | 0; instances refresh over Redis or poll if you enable it |
Database Changes
Show the schema changes
Schema changes are applied by JPA / Hibernate at startup. Run them by hand only when automatic DDL is disabled (
spring.jpa.hibernate.ddl-auto=noneorvalidate).
The full SQL is in 2.4.0 changelog → Database Changes:
e_upms_user,e_upms_role,e_upms_org,e_upms_post: newtenant_id, unique constraints become tenant + account / codee_upms_login_log,e_upms_operate_log: newtenant_ide_upms_sso: newtenant_id,idp_certificate;e_upms_sso_bind: newtenant_id(with erupt-sso)e_record_comment: newtenant_id(with erupt-comment)e_flow,e_flow_group,e_flow_instance: newtenant_id(with erupt-flow)e_tenant_package: newtrial_days(with erupt-tenant)- No longer used (drop by hand once migrated):
e_tenant_menu,t_e_upms_user,t_e_upms_user_role,t_e_upms_role,t_e_upms_role_menu,t_e_upms_org(with erupt-tenant) - New tables created by Hibernate:
e_upms_module, plus the new modules'e_share_link,e_webhook,e_webhook_log,e_config_profile,e_config_item,e_record_revisionande_ai_dev_*
Post-upgrade Checklist
After restarting, confirm in order:
- Export rights: models that must not be exported carry
@Power(export = false)(change 1) - API writers: integrations writing through
/erupt-api/datasend option values and field values within the declared limits (change 2) - Renamed property:
init-method-enuminapplication.ymlis nowinit-modules-menu(change 3) - Client IP: behind a reverse proxy the login log shows real user IPs, and public proxies are in
trusted-proxies(change 4) - erupt-tenant projects: old unique indexes dropped, tenant users / roles / orgs moved into
e_upms_*, package menus ticked again (change 6) - erupt-cloud projects: the server and every node run 2.4.0
- Date fields: spot-check the pickers of
LocalDateTime/LocalTimefields (change 8) - Automatic DDL disabled: the SQL above has been run
- Frontend cache: the translation sheet is now versioned; force-refresh the browser if a page looks wrong
V 2.3.0 Upgrade Guide
This section covers what to watch for when upgrading from 2.2.x to 2.3.0.
Requirements
| Item | Requirement |
|---|---|
| Erupt | Bump every dependency to 2.3.0 |
| Spring Boot | 3.5.16, same as 2.2.x, nothing to change |
| JDK | JDK 17 minimum, unchanged |
| Database | No minimum-version change; schema changes below |
| erupt-cloud-node | Projects using erupt-cloud-node must upgrade the node service to 2.3.0 as well |
Step 1: Bump the dependency version
<properties>
<erupt.version>2.3.0</erupt.version>
</properties>Without a shared property, change the <version> of every xyz.erupt coordinate in pom.xml to 2.3.0. No artifactId was renamed or retired in this release; 2.2.x coordinates keep working.
Step 2: Add the new modules (optional)
2.3.0 open-sources five modules. Leaving them out changes nothing; adding one initializes its menus and tables on first start. erupt-spring-boot-starter-all already includes the first three.
| Module | artifactId | Purpose |
|---|---|---|
| Single sign-on | erupt-sso | OAuth2 / OIDC providers configured in the admin with 17 presets; the login page shows their buttons automatically, and erupt-notice can push to Feishu / DingTalk / WeCom / Slack through the same credentials |
| Record comments | erupt-comment | A comment stream on any record; @mention notices need erupt-notice |
| AI Decision | erupt-ai-decision | Typed, probability-backed judgements; depends on erupt-data-jpa only |
| DingTalk Notable data source | erupt-data-dingtalk | Bind a DingTalk Notable sheet as an @Erupt model |
| Airtable data source | erupt-data-airtable | Bind an Airtable table as an @Erupt model |
erupt-sso needs a registered redirect URI
Each provider's redirect URI is <erupt host>/erupt-api/sso/callback/<code> and must match what is registered in the provider's console; see the module page.
Breaking and behavioural changes
1. The login lock is on by default changed default
Affects: every project that signs in through erupt-upms.
Ten failed passwords for one account from one IP lock the pair for ten minutes; a wrong captcha counts too. Regular users will hardly ever hit it. Load tests, automated logins or many users behind one egress IP can tune or disable it:
erupt:
upms:
login-lock:
enable: true
max-failures: 10
lock-minutes: 102. A password change signs out the other sessions
Whether the user changes their password or an admin uses Reset Password, every other session of that account is revoked at once; only the session that made the change stays. Automation that relied on old sessions surviving a password change needs adjusting.
3. Account status, expiry and IP whitelist apply to every login path
The three checks moved into EruptUserService.checkAccountUsable and run for password logins, erupt-sso and custom LoginProxy logins alike. A project whose LoginProxy used to bypass them will now be refused.
4. logoPath: null in app.js now means "no logo" check app.js
Affects: projects whose app.js says logoPath: null (the 2.2.x template default) while still showing the bundled logo.
From 2.3.0 the three logo keys share one rule: leave a key out for the default (the bundled Erupt mark; collapsed and login logos follow logoPath), set it to null or '' to show nothing in that slot. If the header logo disappears after upgrading, delete the logoPath: null line or point it at your own logo. A collapsed sidebar with no logo at all shows the site's initial instead of the Erupt mark.
5. Strict validation of sort fields and condition keys
Sort fields and queryColumn condition keys must now be legal property paths (dotted Java identifiers), and condition values are bound as parameters. A client calling /erupt-api/data/... directly with an expression in sort (such as id desc, (select ...)) is refused; send field names only.
6. erupt-generator rewritten
The generator moved from typing models in by hand to importing them from a database. e_generator_class / e_generator_field gain columns; old rows survive but lack the new column name, java type and similar fields, so re-importing is recommended. The per-field "unique" switch and the print button are gone, and the module no longer depends on freemarker or erupt-tpl.
7. The EruptUser form is no longer a wizard
The four DIVIDE step markers (accountStep / orgStep / pwdStep / securityStep) became GROUP fields (orgGroup / pwdGroup / securityGroup). All are @Transient, so there is no database impact; only custom code that referenced those field names needs to change.
Changed defaults worth knowing
| Item | 2.2.x | 2.3.0 |
|---|---|---|
@BoolType(type) | — | AUTO: a notNull BOOLEAN renders as a switch, others as radios; restore the old look with @BoolType(type = BoolType.Type.RADIO), see BOOLEAN |
| Empty BOOLEAN table cell | Empty tag | Nothing |
| Row click opens the detail panel | On | Off (users can enable it in the settings drawer) |
| Whole-tree menu drag sorting | Supported | Removed, menus follow the server order; favorites still drag |
theme.customizable | — | true; false locks the appearance for everyone |
Attachment domain fileDomain | Set in app.js | Served by /erupt-app; an empty app.js value adopts it |
| Enum columns of new tables | Native enum / check constraint | Plain VARCHAR; existing tables untouched |
@Power(comment) | — | true; with erupt-comment installed every model accepts comments, add @Power(comment = false) to sensitive ones |
Database Changes
INFO
Hibernate applies these changes automatically at startup; run them by hand only when automatic DDL is disabled (spring.jpa.hibernate.ddl-auto=none or validate).
The full SQL is in 2.3.0 Changelog → Database Changes. It covers:
e_upms_user: new columnsmfa_enabled,mfa_secret,mfa_recovery_codese_generator_class,e_generator_field: new columns (with erupt-generator)e_remote_host: newfile_transfercolumn (with erupt-remote)- Tables of the new modules, created by Hibernate:
e_upms_sso,e_upms_sso_role,e_upms_sso_bind(erupt-sso);e_record_comment(erupt-comment);e_ai_decision_def,e_ai_decision_model,e_ai_decision_question(erupt-ai-decision)
Post-upgrade Checklist
After restarting, confirm in order:
- Login lock thresholds — 10 failures / 10 minutes by default; tune for load tests and automated logins (change 1)
- Header logo — remove
logoPath: nullfromapp.jsor set a real path (change 4) - Custom LoginProxy — make sure the account status / expiry / IP whitelist checks are what you expect for your login flow (change 3)
- Required BOOLEAN fields — spot-check switches vs radios in forms and pin
@BoolType(type)where needed - MFA for administrators — have every admin enrol in two-factor authentication from the avatar menu
- Projects adding erupt-comment — add
@Power(comment = false)to models that must not carry comments; @mention notices need erupt-notice - Old erupt-generator rows — they lack the new fields, re-import from the database
- Projects with automatic DDL disabled — confirm the SQL above has been run
- Frontend cache — the frontend changed a lot (skins, login page, form panel); force-refresh the browser if styles look off
V 2.2.0 Upgrade Guide
This section covers the notable changes when upgrading from 2.1.x to 2.2.0.
Requirements
| Item | Requirement |
|---|---|
| Erupt | Every dependency moves to 2.2.0 |
| Spring Boot | 3.5.16, same as 2.1.x — nothing to change |
| JDK | 17 minimum, unchanged |
| Database | No minimum version change; schema changes are listed below |
| erupt-cloud-node | Projects using erupt-cloud-node must upgrade their node services to 2.2.0 as well |
Step 1: Bump the dependency version
Most projects manage the version through one property, so this is the only edit:
<properties>
<erupt.version>2.2.0</erupt.version>
</properties>Without a shared property, change the <version> of every xyz.erupt coordinate in pom.xml to 2.2.0 — framework modules assemble against a matching version, and mixing versions fails at startup.
TIP
Projects on erupt-spring-boot-starter or erupt-spring-boot-starter-all only need the starter's own version bumped; it manages the submodules.
This release renames no artifactIds and retires no modules, so 2.1.x coordinates carry over as they are.
Step 2: Add the new modules (optional)
2.2.0 open-sources two modules. Skipping them changes nothing; adding one initializes its menu on the first startup, with no manual menu setup:
| Module | artifactId | Purpose |
|---|---|---|
| Model Atlas | erupt-atlas | Model relation graph, lineage, coupling matrix, structural audit, and the Erupt class registry moved over from erupt-monitor |
| Remote Access | erupt-remote | VNC desktops and SSH shells in the browser |
<dependency>
<groupId>xyz.erupt</groupId>
<artifactId>erupt-atlas</artifactId>
<version>${erupt.version}</version>
</dependency>erupt-remote needs configuration
A multi-node deployment must give every node the same erupt.remote.secret-key, or credentials encrypted on one node cannot be decrypted on another. The reverse proxy also has to forward the WebSocket upgrade for /erupt-remote — see the module docs.
Breaking Changes
1. User and role lists are no longer scoped to their creator wider access
Who is affected: systems that grant the User Management or Role Management menu to non-admin users.
In 2.1.x EruptUser inherited a @PreDataProxy from LookerSelf, and EruptRoleDataProxy carried the same rule inline: a user whose isAdmin flag was false only saw rows whose createUser was itself.
The rule did not hold. beforeFetch applies to the list query, while reading, updating and deleting by id go through verifyIdPermissions, which builds its own query from the primary key alone. The rows were hidden from the list but still readable, editable and deletable by id — a boundary in appearance only.
As of 2.2.0, visibility for both models is decided by menu and role permissions, the way the rest of erupt works. EruptUser now extends HyperModelCreatorVo — LookerSelf's own superclass — so the mapped columns are unchanged and no schema migration is needed. LookerSelf itself is kept: it is public API a downstream entity may still extend.
Review right after upgrading
This widens access: a non-admin holding the User or Role menu now sees every row. Check that those menus are assigned as intended.
2. erupt-designer data moves to SQLite
Who is affected: projects using erupt-designer that already hold business data.
Designer model data no longer lives in the e_designer_data table of the main database. It moves to an embedded SQLite file (data/designer.db by default), with one real table per published design.
- Nothing is migrated automatically: re-publishing a design after the upgrade creates its new table. To keep existing rows, export them from
e_designer_dataas JSON and re-import. - The old table is left behind:
e_designer_datais neither read nor written any more, and Hibernate will not drop it. Once its data is migrated or no longer needed, drop it by hand withDROP TABLE e_designer_data(irreversible). The design config tablee_designerstays in use — do not drop it. - Include it in your backups: the file is separate from the main database; containerized deployments must mount it on a persistent volume or lose the data on rebuild.
- The design config itself (
e_designer) is unaffected; the path is configurable witherupt.designer.db-path.
3. Font Awesome 7
Who is affected: every project that customizes menu icons or @Drill / @RowOperation icons.
font-awesome 4.7 stopped in 2016; 2.2.0 moves to @fortawesome/fontawesome-free 7.x. Legacy class names keep resolving through v4-shims — of the 786 FA4 class names, only meanpath and tripadvisor lose a glyph.
One visual change: FA7 gives every .fa a default width of 1.25em (FA4 had none), so icons sit in a uniform box. Set --fa-width: auto for the old metrics.
4. The Erupt class registry moves from erupt-monitor to erupt-atlas
Who is affected: projects that use the System Monitoring → Erupt Class Registry menu, and code that references xyz.erupt.monitor.model.EruptClassInfo.
The class registry (EruptClassInfo) and its field drill (EruptFieldInfo) read the same live registry the model atlas draws. From 2.2.0 both live in erupt-atlas, under the xyz.erupt.atlas package instead of xyz.erupt.monitor; erupt-monitor is back to pure system monitoring (service, cache, diagnosis). Registry rows gain an Open in Atlas action that jumps straight to that model's relation graph.
Menu initialization only adds, never moves, so the existing EruptClassInfo / EruptFieldInfo menu rows stay under System Monitoring. Handle them according to your setup:
| Setup | After the upgrade | What to do |
|---|---|---|
Only erupt-monitor | The old menu points at a model that is no longer registered and fails to open | Add erupt-atlas, or delete Erupt Class Registry and the hidden EruptFieldInfo menu in menu management |
erupt-atlas as well (including erupt-spring-boot-starter-all) | The old menu keeps working but stays under System Monitoring; the new Model Atlas root only holds Model Graph | Move Erupt Class Registry under Model Atlas in menu management, or delete the old menu and restart so the framework recreates it in the new place |
Custom code referencing xyz.erupt.monitor.model.* or EruptClassInfoDataService | Compilation fails | Switch to xyz.erupt.atlas.model.* / xyz.erupt.atlas.service.* and make sure erupt-atlas is a dependency |
Changed defaults worth knowing
| Item | 2.1.x | 2.2.0 |
|---|---|---|
@Power(cellEdit) | — | true; tables offer cell editing by default, see @Power |
@Edit(ai) | — | true; text fields offer the AI writing assistant |
| Frontend theme color | #00B515 | rgb(22, 119, 255), overridable with theme.primaryColor in app.js |
| Menu tree expand level | 5 levels | 1 level |
Tightening the defaults
- Rows that must always be changed as a reviewed whole:
@Erupt(power = @Power(cellEdit = false)) - A field the grid should never edit:
@Edit(cellEdit = false) - A model AI must not touch at all:
@Erupt(power = @Power(ai = false))
Database Changes
INFO
Schema changes are applied automatically by JPA / Hibernate at startup. Run them manually only if automatic DDL is disabled (spring.jpa.hibernate.ddl-auto=none or validate).
The full SQL is in 2.2.0 Changelog → Database Changes. It covers:
e_remote_host: created when erupt-remote is added; Hibernate builds it on its owne_ai_canvas_model: new table;data_typeandtarget_modelone_ai_canvasare migrated and then dropped (when erupt-ai-canvas is used)e_ai_chat_message: newimagescolumn (when erupt-ai is used)e_designer_data: no longer used; drop it manually once its data is migrated (when erupt-designer is used)
Post-upgrade Checklist
After restarting, verify in order:
- User / role menu grants — non-admins now see every row of those two tables; confirm the grants are what you intend (breaking change 1).
- Cell editing on sensitive models — tables offer cell editing by default. Add
@Power(cellEdit = false)to models that must be changed as a reviewed whole, and@Edit(cellEdit = false)to fields a grid should never touch. - AI writing assistant scope — text fields offer it by default; add
@Power(ai = false)to models AI must stay out of. - Anonymous telemetry — on by default; disable it with
erupt.telemetry.enabled=falseon intranet-only or compliance-sensitive deployments. - erupt-designer volume — containerized deployments should confirm
data/designer.dbis on a persistent volume and included in backups. - Menu icons — spot-check custom icons under Font Awesome 7, and look up replacements in the FA7 library if any are missing.
- Frontend cache — the frontend changed substantially (theme system, icon set); hard-refresh the browser if styling looks wrong.
- Projects with automatic DDL disabled — confirm the SQL above has been applied.
- Erupt Class Registry menu — it moved to erupt-atlas with its model; confirm the old menu under System Monitoring still opens (erupt-atlas present) or has been deleted (breaking change 4).
V 2.1.0 Upgrade Guide
This section covers the notable changes when upgrading from 2.0.x to 2.1.0.
Requirements
- Upgrade Spring Boot to 3.5.16 (projects using
<parent>withspring-boot-starter-parentonly need to change the version number). - JDK 17 is the minimum supported version (unchanged).
- Change the Erupt version to
2.1.0across all modules. - Projects using erupt-cloud-node: all node services must also be upgraded to 2.1.0.
Breaking Changes
1. erupt-jpa Renamed to erupt-data-jpa
Affected scope: Projects that declare the erupt-jpa dependency explicitly in pom.xml.
2.1.0 folds the JPA data source into the erupt-data connector layer, so the artifactId changed from erupt-jpa to erupt-data-jpa. The Java package is unchanged — it is still xyz.erupt.jpa.* (e.g. xyz.erupt.jpa.model.BaseModel, xyz.erupt.jpa.dao.EruptDao) — so only the dependency coordinates need updating; no application code changes are required.
<!-- Old (build fails: dependency not found) -->
<dependency>
<groupId>xyz.erupt</groupId>
<artifactId>erupt-jpa</artifactId>
<version>${erupt.version}</version>
</dependency>
<!-- New -->
<dependency>
<groupId>xyz.erupt</groupId>
<artifactId>erupt-data-jpa</artifactId>
<version>${erupt.version}</version>
</dependency>2. erupt-mongodb Renamed to erupt-data-mongodb
Affected scope: Projects that declare the erupt-mongodb dependency explicitly in pom.xml.
Same as JPA: the artifactId changed from erupt-mongodb to erupt-data-mongodb. The Java package is still xyz.erupt.mongodb.*, so no application code changes are required.
<!-- Old (build fails: dependency not found) -->
<dependency>
<groupId>xyz.erupt</groupId>
<artifactId>erupt-mongodb</artifactId>
<version>${erupt.version}</version>
</dependency>
<!-- New -->
<dependency>
<groupId>xyz.erupt</groupId>
<artifactId>erupt-data-mongodb</artifactId>
<version>${erupt.version}</version>
</dependency>TIP
Projects using erupt-spring-boot-starter or erupt-spring-boot-starter-all get these dependencies from the starter and need no manual change.
3. The erupt-tpl-ui.amis Module Was Removed
Affected scope: Projects depending on the AMIS template integration module.
The AMIS integration inside erupt-tpl-ui (artifactId erupt-tpl-ui.amis) has been removed in 2.1.0. Delete the dependency from your pom.xml:
<!-- No longer published — remove it -->
<dependency>
<groupId>xyz.erupt</groupId>
<artifactId>erupt-tpl-ui.amis</artifactId>
<version>${erupt.version}</version>
</dependency>If your project renders AMIS pages, migrate to one of the other erupt-tpl skins (erupt-tpl-ui.ant-design, erupt-tpl-ui.element-ui, erupt-tpl-ui.element-plus), or build custom pages with erupt-ai-canvas. The artifactIds of those three skins are unchanged — only their directory moved from erupt-tpl-ui/ to erupt-tpl/, which does not affect dependency declarations.
V 2.0.0 Upgrade Guide
This section covers the notable changes when upgrading from 1.14.x to 2.0.0.
Requirements
- Upgrade Spring Boot to 3.5.15 (projects using
<parent>withspring-boot-starter-parentonly need to change the version number). - JDK 17 is the minimum supported version (unchanged).
- Change the Erupt version to
2.0.0across all modules. - Projects using erupt-cloud-node: all node services must also be upgraded to 2.0.0.
Breaking Changes
1. Password Encryption Upgraded (MD5 → SHA-512 + Salt)
Affected scope: All systems that use Erupt's built-in UPMS login.
After upgrading, the system uses SHA-512 with a random salt for newly created and reset passwords. This change is backward compatible — the checkPwd method in EruptUserService checks the encryptType column: users whose encryptType is null or MD5 (i.e. all existing users) can still log in with their current passwords. Only new and reset passwords will use SHA-512 + salt going forward. Thanks to 段鹏鹏 for contributing this security improvement (Gitee !35).
How to handle:
- No forced migration required: Existing users can continue to log in without any action.
- Optional batch migration: If you want to upgrade all passwords to the new algorithm, use
SecretUtil.encodePassword(plaintext, salt)to re-hash them and update thepassword,salt, andencrypt_typecolumns in thee_upms_usertable.
2. DataProxy.extraContent Signature Changed
Affected scope: Classes that implement DataProxy and override extraContent.
| Old signature | New signature | |
|---|---|---|
| Method | default String extraContent(List<Condition> conditions) | default String extraContent(List<Condition> conditions, Collection<Map<String, Object>> list) |
The new second parameter list provides the current page's data rows, enabling dynamic HTML that references actual row values.
// Old (must be updated if overridden)
@Override
public String extraContent(List<Condition> conditions) {
return "<div>Custom content</div>";
}
// New
@Override
public String extraContent(List<Condition> conditions, Collection<Map<String, Object>> list) {
return "<div>Custom content — " + list.size() + " rows on this page</div>";
}3. HTML_EDITOR Default Editor Changed to CKEditor
Affected scope: Any module using the EditType.HTML_EDITOR field type.
In 2.0.0 the default rich-text editor for HTML_EDITOR has changed from UEditor to CKEditor. After upgrading, any HTML_EDITOR field that does not explicitly specify an editor type will automatically render with CKEditor.
To keep using UEditor, declare it explicitly via annotation:
@Edit(
type = EditType.HTML_EDITOR,
htmlEditorType = @HtmlEditorType(type = HtmlEditorType.Type.UEDITOR)
)
private String content;4. AutoCompleteHandler, ChoiceFetchHandler, TagsFetchHandler Require a Generic Type Parameter
Affected scope: Classes that implement any of these interfaces.
The fetchFilter method's parameter type has changed from Map<String, Object> formData to the actual model object (generic T). The interfaces are now generic.
// Old (compilation error after upgrade)
class MyHandler implements ChoiceFetchHandler {
@Override
public List<String> fetchFilter(Map<String, Object> formData, ...) {
String value = (String) formData.get("someField");
...
}
}
// New
class MyHandler implements ChoiceFetchHandler<MyEruptClass> {
@Override
public List<String> fetchFilter(MyEruptClass data, ...) {
String value = data.getSomeField();
...
}
}The migration for AutoCompleteHandler and TagsFetchHandler follows the same pattern.
5. Excel Import Template Format Changed from .xls to .xlsx
Affected scope: Users with cached or bookmarked import template download links.
The generated import template format has been upgraded from the legacy .xls to .xlsx. Clear your browser cache or re-download the template if you are using a previously downloaded file.
6. @Search.vague Removed
Affected scope: Any field annotated with @Search(vague = true) or @Search(vague = false).
// Old (compilation error after upgrade)
@Edit(search = @Search(vague = true))
@Edit(search = @Search(vague = false))
// New
@Edit(search = @Search) // equivalent to the old vague = true (advanced search is now the default)
@Edit(search = @Search(value = true)) // just enables search; no other changeAdvanced search (range queries, fuzzy matching, etc.) is now the default behaviour for each component — no extra configuration needed.
7. EruptApiModel Deleted
Affected scope: Any code that references EruptApiModel.PromptWay.
// Old (compilation error after upgrade)
throw new EruptApiErrorTip("Error message", EruptApiModel.PromptWay.MESSAGE);
throw new EruptApiErrorTip("Error message", EruptApiModel.PromptWay.NOTIFY);
// New
throw new EruptApiErrorTip("Error message", R.PromptWay.MESSAGE);
throw new EruptApiErrorTip("Error message", R.PromptWay.NOTIFY);If your project references EruptApiModel directly, replace it with R<T>:
// Old
import xyz.erupt.core.view.EruptApiModel;
// New
import xyz.erupt.core.view.R;8. ChoiceTrigger Interface Removed
Affected scope: Classes that implemented ChoiceTrigger.
This interface was deprecated in earlier versions and has been removed in 2.0.0. Use @ChoiceType.fetchHandler instead:
// New: implement a linked-selection handler
@Edit(
choiceType = @ChoiceType(fetchHandler = MyChoiceFetchHandler.class)
)9. Login / Change-Password Endpoints Switched to HTTP POST
Affected scope: Custom login pages and any frontend code that calls these endpoints directly.
| Endpoint | Old method | New method |
|---|---|---|
/erupt-api/erupt-user/login | GET | POST |
/erupt-api/erupt-user/change-pwd | GET | POST |
If you have a custom login page, change the corresponding AJAX calls from GET to POST.
Quick API Migration Reference
| Old API | New API |
|---|---|
EruptApiModel.PromptWay.MESSAGE | R.PromptWay.MESSAGE |
EruptApiModel.PromptWay.NOTIFY | R.PromptWay.NOTIFY |
EruptApiModel.PromptWay.DIALOG | R.PromptWay.DIALOG |
@Search(vague = true) | @Search |
@Search(vague = false) | @Search(value = true) |
ChoiceTrigger interface | @ChoiceType.fetchHandler |
MD5Util | EncryptUtil / SecretUtil |
EditType.COLLAPSE | EditType.GROUP |
Database Changes
INFO
All schema changes are applied automatically by JPA / Hibernate at startup. Manual DDL is only needed when your project has disabled Hibernate auto-DDL (spring.jpa.hibernate.ddl-auto=none or validate).
New columns in e_upms_user
ALTER TABLE e_upms_user ADD COLUMN salt VARCHAR(64);
ALTER TABLE e_upms_user ADD COLUMN encrypt_type VARCHAR(20);Required Upgrade Actions
WARNING
The following steps must be completed before starting the application for the first time after the upgrade. Skipping them will cause routing mismatches or blank pages in the affected modules.
Step 1: Delete the .erupt directory
The .erupt directory (located in the JVM working directory) stores module-initialization marker files. Deleting it causes the framework to re-run all module menu-initialization logic on the next startup:
rm -rf .eruptStep 2: Manually delete stale menus
Log in to the admin UI → System Settings → Menu Management, and delete the following menus as applicable:
If using erupt-monitor
2.0.0 completely rewrites erupt-monitor. The menu structure is entirely different from the old version and cannot be migrated automatically:
Find the "System Monitor" (or Monitor) root menu and delete all its child menus along with the root menu itself.
If using erupt-terminal
2.0.0 refactors the terminal module's frontend UI; the old route has changed:
Find the "Terminal" menu and delete it.
Step 3: Restart the application
After restarting, the system will automatically generate the latest menus for the affected modules.