> ## Documentation Index
> Fetch the complete documentation index at: https://docs.onnucleus.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Upgrades & Migrations

> Zero-downtime rolling upgrades and automatic Liquibase database migrations.

# Nucleus Core Banking — Upgrade Guide

## Overview

Nucleus utilizes automated **rolling upgrades** — each release includes deterministic Liquibase changesets that execute and lock during container startup. No manual SQL DDL execution is required.

***

## Pre-Upgrade Checklist

* [ ] Execute full database backup of tenant databases (`nucleus_tenants`, `nucleus_default`, and individual tenant schemas)
* [ ] Inspect current engine version: `GET /nucleus/actuator/info`
* [ ] Review release changelog for breaking changes or new module dependencies
* [ ] Ensure the deployment license is active and valid beyond the maintenance window

***

## Upgrade Procedure (Docker Compose)

```bash theme={null}
# 1. Pull the target engine and console images
docker compose pull

# 2. Gracefully stop operational tasks
docker compose down

# 3. Create pre-upgrade snapshot
docker exec -t mariadb mariadb-dump -u root -p"$DB_PASS" --all-databases > pre_upgrade_$(date +%Y%m%d%H%M).sql

# 4. Start the upgraded containers
docker compose up -d

# 5. Monitor migration progress
docker compose logs -f nucleus-engine | grep -i "liquibase\|migration\|completed"

# 6. Verify health
curl -fks https://localhost:8443/nucleus/actuator/health
```

***

## Rollback Strategy

If a migration fails or data discrepancies occur during post-upgrade sanity checks:

1. Stop the application stack: `docker compose down`
2. Restore the database from the pre-upgrade snapshot:
   ```bash theme={null}
   mariadb -u root -p"$DB_PASS" < pre_upgrade_*.sql
   ```
3. Revert your container tag in `docker-compose.yml` to the previous stable release.
4. Launch the stack: `docker compose up -d`