diff --git a/docs/cli.md b/docs/cli.md
index 4b733ef5..45bd3374 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -305,6 +305,33 @@ haiku-rag init [--db /path/to/your.lancedb]
 
 This creates the database with the configured settings. **All other commands require an existing database** - they will fail with an informative error if the database doesn't exist.
 
+### Migrate Database
+
+Apply pending database migrations:
+
+```bash
+haiku-rag migrate [--db /path/to/your.lancedb]
+```
+
+When you upgrade haiku.rag to a new version that includes schema changes, the database requires migration. Opening a database with pending migrations will display an error:
+
+```
+Error: Database requires migration from 0.19.0 to 0.26.5. 3 migration(s) pending. Run 'haiku-rag migrate' to upgrade.
+```
+
+Run `haiku-rag migrate` to apply the pending migrations. The command shows which migrations were applied:
+
+```
+Applied 3 migration(s):
+  - 0.20.0: Add 'docling_document_json' and 'docling_version' columns
+  - 0.23.1: Add content_fts column for contextualized FTS search
+  - 0.25.0: Compress docling_document with gzip
+Migration completed successfully.
+```
+
+!!! tip
+    Back up your database before running migrations. While migrations are designed to be safe, having a backup provides peace of mind for production databases.
+
 ### Info
 
 Display database metadata:
diff --git a/docs/python.md b/docs/python.md
index da4b9d71..f04fffc7 100644
--- a/docs/python.md
+++ b/docs/python.md
@@ -18,7 +18,7 @@ async with HaikuRAG("path/to/database.lancedb") as client:
     # Your code here
     pass
 
-# Open in read-only mode (blocks writes, skips upgrades)
+# Open in read-only mode (blocks writes)
 async with HaikuRAG("path/to/database.lancedb", read_only=True) as client:
     results = await client.search("query")  # Read operations work
     # await client.create_document(...)  # Would raise ReadOnlyError
@@ -28,7 +28,10 @@ async with HaikuRAG("path/to/database.lancedb", read_only=True) as client:
     Databases must be explicitly created with `create=True` or via `haiku-rag init` before use. Operations on non-existent databases will raise `FileNotFoundError`.
 
 !!! note
-    Read-only mode is useful for safely accessing databases without risk of modification. It blocks all write operations, skips database upgrades on open, and prevents settings from being saved.
+    Read-only mode is useful for safely accessing databases without risk of modification. It blocks all write operations and prevents settings from being saved.
+
+!!! warning "Database Migrations"
+    When upgrading haiku.rag to a version with schema changes, opening an existing database will raise `MigrationRequiredError`. Run `haiku-rag migrate` to apply pending migrations before using the database. See [CLI Database Management](cli.md#migrate-database) for details.
 
 ## Document Management
 
diff --git a/tests/test_cli.py b/tests/test_cli.py
index 3f7bef08..f3f8e266 100644
--- a/tests/test_cli.py
+++ b/tests/test_cli.py
@@ -2,7 +2,7 @@ from unittest.mock import AsyncMock, MagicMock, patch
 
 from typer.testing import CliRunner
 
-from haiku.rag.cli import cli
+from haiku.rag.cli import _cli as cli
 
 runner = CliRunner()