From d356f04333908a1a7b428df746b9d54f84055ef3 Mon Sep 17 00:00:00 2001
From: fedoraBee <9395414+fedoraBee@users.noreply.github.com>
Date: Tue, 21 Apr 2026 17:08:36 +0200
Subject: [PATCH] docs: add upgrade and database migration guide

- Create MIGRATION.md clarifying Postgres is opt-in for existing v0.4.x users
- Document the JSON export/import workflow for migrating SQLite to Postgres
- Link migration guide in README.md
- Bump version to 0.5.0-rc5
---
 CHANGELOG.md |  8 ++++++++
 MIGRATION.md | 46 ++++++++++++++++++++++++++++++++++++++++++++++
 Makefile     |  2 +-
 README.md    |  6 ++++++
 4 files changed, 61 insertions(+), 1 deletion(-)
 create mode 100644 MIGRATION.md

diff --git a/CHANGELOG.md b/CHANGELOG.md
index d644d1a..2a6e149 100644
--- a/CHANGELOG.md
+++ b/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
diff --git a/MIGRATION.md b/MIGRATION.md
new file mode 100644
index 0000000..dcae414
--- /dev/null
+++ b/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.
diff --git a/Makefile b/Makefile
index 80eeb8d..44bc617 100644
--- a/Makefile
+++ b/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
diff --git a/README.md b/README.md
index c8badc6..8164890 100644
--- a/README.md
+++ b/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)