A NocoBase upgrade can replace application code or an image, update plugins, and run plugin migrations that alter database structure, data, or plugin configuration. The exact changes depend on your current and target versions, installation method, and enabled plugins—so there is no universal list of tables or settings that every upgrade changes. Back up the database before starting.
What an upgrade can change
Application code or image
For an app created with the nb CLI, the documented upgrade flow stops the app, downloads and replaces its saved source or image, synchronizes commercial plugins, upgrades and starts the app, then refreshes runtime information. The precise actions depend on the app’s setup and selected target version. See NocoBase’s Upgrade NocoBase App guide.
The --skip-download option is for cases where the target source or image is already prepared. It also skips commercial-plugin synchronization, so it is not simply a way to omit downloading while keeping every other default action.
Plugins
Built-in plugins update with the core version. Third-party plugins follow their own installation and update procedures and may require yarn nocobase upgrade --skip-code-update. Commercial plugins have separate activation and upgrade instructions. Consult the plugin installation and upgrade documentation for the relevant plugin category.
#1 Best Overall
Database schema, data, and plugin configuration
Plugin migrations can adjust table structures, move data, and update plugin configuration or internal logic. Depending on the migration, it can run before plugins load, after collection configurations synchronize to the database, or after plugins load. Version ranges determine which migrations apply. The migration guide and Migration API describe these mechanisms.
That does not mean every upgrade performs a wholesale data conversion. Nor is an upgrade necessarily “only code.” The actual changes depend on the upgrade path and the migrations for the plugins enabled in your app.
Which upgrade route applies to your app?
First identify how the app was installed, its current version, and the target version. NocoBase documents different procedures for apps initialized with nb, Git source installations, and create-nocobase-app installations; their actions should not be treated as interchangeable.
| Installation or situation | What the documented route means | Reference |
|---|---|---|
Initialized with nb |
Use the app-upgrade workflow, which may download and replace source or image and synchronize commercial plugins. | Upgrade NocoBase App |
| Git source installation | The documented procedure includes pulling code, installing dependencies, running yarn nocobase upgrade, and starting NocoBase. The guide recommends a database backup first. |
Upgrading a Git Source Installation |
create-nocobase-app installation |
Follow that installation route’s instructions; they say to stop the running instance before upgrading and recommend a database backup. | Upgrading a create-nocobase-app Installation |
| Moving from NocoBase 2.0 to 2.1 | The guide distinguishes the older yarn nocobase commands from the globally installed nb CLI used in 2.1 and later. A stable 2.0 app can keep its existing installation and upgrade method. |
NocoBase 2.0 to 2.1 Upgrade Guide |
The 2.0-to-2.1 CLI change does not by itself require an existing app to move to nb. The guide describes creating a new nb-managed app as a separate migration: move the old database and storage, provide the required environment variables, verify the new app, and then switch production traffic. That is different from continuing to upgrade the existing app in place.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Scan for outdated or missing drivers - takes under a minute3Clear out junk files and repair common Windows errorsPrepare and verify the upgrade
- Confirm the route and target. Check how the app was installed and which version you intend to run. The
nb app upgradeinstructions apply to apps installed withnb init; use the matching guide for other routes. - Back up the database. NocoBase recommends this in its Git-source and
create-nocobase-appupgrade instructions. Ensure you know how to restore the backup; an untested backup is not a dependable recovery plan. - Stop the app if the route requires it, then follow its upgrade procedure. For Git source, the documented sequence includes pulling code, installing dependencies, running
yarn nocobase upgrade, and starting NocoBase again. - Check the result. After an
nbupgrade, inspect environment information and app logs, then confirm an administrator can sign in.
How cluster upgrades differ
NocoBase says online cluster upgrades are not currently supported. Its documented procedure calls for a maintenance window, suspending external services, stopping all app instances, backing up, updating the version, starting one node and waiting for the update, and checking functionality before starting the remaining nodes and restoring load-balancer traffic. Follow the Cluster Operations instructions for the deployment.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.What you can conclude before upgrading
You can identify the likely categories of change—application code or image, plugins, and any applicable migrations—but you cannot determine an exact list of modified tables or settings from the phrase “NocoBase upgrade” alone. That list depends on the versions being crossed and migrations belonging to the enabled plugins. Check the release and plugin instructions for that specific path rather than assuming the database will be untouched or broadly transformed.
NocoBase’s Release Management discussion of backup restore versus migration concerns synchronizing environments; it is a separate subject from the mechanics of upgrading the core application.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
