Migrate a project's configuration files and database schemas to a target nSelf version. Distinct from nself update, which replaces the CLI binary — nself upgrade updates what's inside your project directory.
# Upgrade the current project to v1.1.0
nself upgrade v1.1.0
# Preview what will change without applying
nself upgrade v1.1.0 --dry-runnself upgrade <VERSION> [FLAGS]When a new nSelf version introduces changes to the stack — new required services, config keys, or database schema — your existing projects need a migration step before they can run the new version.nself upgrade handles that migration:
.env or the project manifest.env.dev, docker-compose.yml if present, plugin configs)nself migrate internallynself buildMost patch releases (v1.0.x → v1.0.x+1) require no migration — the CLI handles them transparently on the next nself start. Minor releases (v1.0.x → v1.1.0) typically include at least config changes. Major releases (v1.x → v2.0) include breaking SQL migrations.
Always run --dry-run first on production projects.
| Argument | Description |
|---|---|
VERSION | Target version to migrate to, e.g. v1.1.0. Must be greater than the current project version. |
| Flag | Type | Default | Description |
|---|---|---|---|
--dry-run | bool | false | Show what would change without applying anything |
--yes | bool | false | Skip the confirmation prompt |
--no-build | bool | false | Skip nself build after the migration (run it manually later) |
--backup | bool | true | Take a Postgres snapshot before running SQL migrations |
--env | string | local | Target environment: local, staging, prod |
# 1. Update the CLI binary first
nself update
# 2. Preview the migration
nself upgrade v1.1.0 --dry-run
# Config changes:
# .env.dev: added NSELF_FAMILY_ENABLED, NSELF_SENTRY_ENABLED
# plugins/: nself-status-page requires new env var NSELF_STATUS_PAGE_SLUG
# SQL migrations:
# 0042_add_tenant_plan_column.sql (ALTER TABLE np_licenses)
# 0043_nfamily_tables.sql (CREATE TABLE np_family_*)
#
# Run without --dry-run to apply.
# 3. Back up your data (automatic unless --backup=false)
# The CLI will create a pg_dump before running SQL migrations.
# 4. Apply
nself upgrade v1.1.0| Command | What it changes |
|---|---|
nself update | The CLI binary and Admin Docker image on your machine |
nself upgrade <v> | Config files and database schemas inside your project |
You typically run both: nself update first (machine-level), then nself upgrade <v> (project-level).
SQL migrations that run during nself upgrade are wrapped in transactions where possible. If a migration fails, the transaction is rolled back and the project remains on the previous version. If the migration succeeds but you still need to roll back, restore from the automatic backup:
# List available backups
nself backup list
# Restore from the upgrade backup
nself backup restore --id <backup-id>