changelog: add entry for db

Signed-off-by: Kristoffer Dalby <kristoffer@tailscale.com>

CHANGELOG.md

@@ -2,6 +2,43 @@
 
 ## Next
 
+### Database integrity improvements
+
+This release includes a significant database migration that addresses longstanding
+issues with the database schema and data integrity that has accumulated over the
+years. The migration introduces a `schema.sql` file as the source of truth for
+the expected database schema to ensure new migrations that will cause divergence
+does not occur again.
+
+These issues arose from a combination of factors discovered over time: SQLite
+foreign keys not being enforced for many early versions, all migrations being
+run in one large function until version 0.23.0, and inconsistent use of GORM's
+AutoMigrate feature. Moving forward, all new migrations will be explicit SQL
+operations rather than relying on GORM AutoMigrate, and foreign keys will be
+enforced throughout the migration process.
+
+We are only improving SQLite databases with this change - PostgreSQL databases
+are not affected.
+
+Please read the [PR description](https://github.com/juanfont/headscale/pull/2617)
+for more technical details about the issues and solutions.
+
+**SQLite Database Backup Example:**
+```bash
+# Stop headscale
+systemctl stop headscale
+
+# Backup sqlite database
+cp /var/lib/headscale/db.sqlite /var/lib/headscale/db.sqlite.backup
+
+# Backup sqlite WAL/SHM files (if they exist)
+cp /var/lib/headscale/db.sqlite-wal /var/lib/headscale/db.sqlite-wal.backup
+cp /var/lib/headscale/db.sqlite-shm /var/lib/headscale/db.sqlite-shm.backup
+
+# Start headscale (migration will run automatically)
+systemctl start headscale
+```
+
 ### BREAKING
 
 - Policy: Zero or empty destination port is no longer allowed
@@ -9,6 +46,12 @@
 
 ### Changes
 
+- **Database schema migration improvements for SQLite**
+  [#2617](https://github.com/juanfont/headscale/pull/2617)
+  - **IMPORTANT: Backup your SQLite database before upgrading**
+  - Introduces safer table renaming migration strategy
+  - Addresses longstanding database integrity issues
+
 - Remove policy v1 code [#2600](https://github.com/juanfont/headscale/pull/2600)
 - Refactor Debian/Ubuntu packaging and drop support for Ubuntu 20.04.
   [#2614](https://github.com/juanfont/headscale/pull/2614)