docs: add upgrade and database migration guide

CHANGELOG.md

@@ -6,6 +6,14 @@ The format is based on
 [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.0-rc5] - 2026-04-21
+
+### Added
+
+- **Documentation**: Added `MIGRATION.md` to clarify the non-breaking upgrade
+  path from `v0.4.x` to `v0.5.x` and document the opt-in SQLite to PostgreSQL
+  migration workflow.
+
 ## [0.5.0-rc4] - 2026-04-21
 
 ### Added

MIGRATION.md

@@ -0,0 +1,46 @@
+# Upgrading & Migration Guide
+
+## Upgrading from v0.4.x to v0.5.x
+
+Version 0.5.x introduces optional support for PostgreSQL to handle Open WebUI
+state, providing better scalability compared to the default SQLite database.
+
+**⚠️ Important: PostgreSQL is strictly OPT-IN.** If you are upgrading an
+existing v0.4.x installation, **no action is required**. Your existing SQLite
+database will remain intact, untouched, and will continue to function normally.
+We do not silently break existing user setups.
+
+### Migrating from SQLite to PostgreSQL (Optional)
+
+If your deployment has grown and you explicitly wish to transition your existing
+SQLite data to PostgreSQL, follow these steps:
+
+1. **Export Existing Data:** Log into your current Open WebUI instance as an
+   Administrator. Navigate to **Admin Panel > Settings > Workspace > Data** and
+   click **Export All Data**. This will download a JSON file containing your
+   users, chats, prompts, and configurations.
+
+2. **Backup Volumes (Safety First):** Run the included disaster recovery script
+   to snapshot your data before making changes:
+
+   ```bash
+   ./scripts/backup-ai-stack.sh
+   ```
+
+3. **Enable PostgreSQL:** Edit `/etc/sysconfig/podman-ai-stack` (or your local
+   configuration) and set the `DATABASE_URL` variable as documented in the
+   README. Ensure you have the `postgres.container` quadlet enabled.
+
+4. **Restart the Stack:** Reload your systemd daemon and restart the pod. Open
+   WebUI will detect the new `DATABASE_URL` and initialize a fresh, empty
+   PostgreSQL database.
+
+   ```bash
+   systemctl --user daemon-reload
+   systemctl --user restart podman-ai-stack-pod
+   ```
+
+5. **Import Data:** Create an initial admin account on the fresh
+   PostgreSQL-backed instance. Navigate back to **Admin Panel > Settings >
+   Workspace > Data** and click **Import Data**, uploading the JSON file you
+   exported in Step 1.

Makefile

@@ -1,7 +1,7 @@
 # Makefile for podman-ai-stack
 
 NAME := podman-ai-stack
-VERSION := 0.5.0-rc4
+VERSION := 0.5.0-rc5
 RPM_VERSION := $(subst -,~,$(VERSION))
 BUILD_DIR := $(CURDIR)/rpmbuild
 RPM_DIR := $(BUILD_DIR)/RPMS/noarch

README.md

@@ -358,6 +358,12 @@ sudo systemctl enable --now podman-auto-update.timer
 > ℹ️ For Rootfull deployments, the RPM package automatically enables this timer
 > during installation.
 
+## ⬆️ Upgrading & Migration
+
+Are you upgrading from a previous version (e.g., v0.4.x to v0.5.x)? Check out
+our [Migration Guide](MIGRATION.md) for information on database transitions and
+backwards compatibility.
+
 ## 💾 Backup & Restore
 
 Open WebUI and Ollama store important state (chats, configurations, and models)