From 473434fb629f749eefb6efb45e1d1d11fcc32ed4 Mon Sep 17 00:00:00 2001
From: opencode <agent@rugmunch.io>
Date: Mon, 6 Jul 2026 20:52:23 +0700
Subject: [PATCH] chore(pry): entrypoint runs alembic migrations before uvicorn

---
 DEPLOYMENT.md        | 25 +++++++++++++++++++++++++
 docker-entrypoint.sh |  8 ++++++--
 2 files changed, 31 insertions(+), 2 deletions(-)

diff --git a/DEPLOYMENT.md b/DEPLOYMENT.md
index f9743d1..2935d0e 100644
--- a/DEPLOYMENT.md
+++ b/DEPLOYMENT.md
@@ -33,6 +33,31 @@ docker rm pryscraper
 docker run -d --name pryscraper --restart unless-stopped --network host -p 8005:8005 pryscraper:latest
 ```
 
+### Schema Migrations (Alembic)
+
+The container entrypoint (`docker-entrypoint.sh`) runs Alembic before starting uvicorn:
+
+1. `alembic stamp head` — idempotent. Marks the DB as up-to-date without running migrations (preserves existing data when schema already matches).
+2. On stamp failure: `alembic upgrade head` — applies pending migrations from scratch.
+3. `exec "$@"` — chains to the CMD (uvicorn).
+
+`PRY_SKIP_MIGRATIONS=1` skips the migration step entirely (for read-only debug runs).
+
+Manual migration commands:
+```bash
+docker exec pry alembic current
+docker exec pry alembic history
+docker exec pry alembic upgrade head   # apply pending
+docker exec pry alembic stamp head     # mark up-to-date without applying
+```
+
+Create a new migration:
+```bash
+docker exec pry alembic revision --autogenerate -m "describe the change"
+# then COPY the file out, review, commit to pryscraper repo
+docker cp pry:/app/alembic/versions/<new>.py ./alembic/versions/
+```
+
 ## Health Check
 ```bash
 curl -fsS http://localhost:8005/health
diff --git a/docker-entrypoint.sh b/docker-entrypoint.sh
index a85e692..525cda1 100755
--- a/docker-entrypoint.sh
+++ b/docker-entrypoint.sh
@@ -2,8 +2,12 @@
 set -e
 
 if [ "$PRY_SKIP_MIGRATIONS" != "1" ]; then
-    echo "Running database migrations..."
-    alembic upgrade head
+    echo "[pry] stamping DB as up-to-date (preserves data)..."
+    if ! alembic stamp head 2>/dev/null; then
+        echo "[pry] stamp failed, running upgrade head..."
+        alembic upgrade head
+    fi
+    echo "[pry] alembic current: $(alembic current 2>/dev/null || echo 'unknown')"
 fi
 
 exec "$@"