From dc06551967531757573380e2b513f5eaaf5a83ea Mon Sep 17 00:00:00 2001
From: "russell@unturf.com" <russell@unturf.com>
Date: Mon, 6 Apr 2026 14:20:13 -0400
Subject: [PATCH] =?UTF-8?q?docs:=20use=20make=20migration=20=E2=80=94=20ne?=
 =?UTF-8?q?ver=20hand-write=20revision=20IDs?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 CLAUDE.md | 26 ++++++++++++++++----------
 Makefile  | 17 +++++++++++++++++
 2 files changed, 33 insertions(+), 10 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index be53cde..099e61d 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -155,22 +155,28 @@ When making changes to database models, always create Alembic migrations:
 
 ### Creating Migrations
 
-**CRITICAL**: ALWAYS use `alembic revision` to generate migration files. NEVER manually create migration files or make up revision IDs. Alembic generates unique revision IDs that are required for proper migration tracking.
+**CRITICAL**: ALWAYS use `make migration` to generate migration files. NEVER manually create migration files. NEVER hand-write or invent revision IDs. Alembic generates cryptographically unique revision IDs — a made-up ID like `a1b2c3d4e5f6` will corrupt the migration chain and break production deploys.
 
 ```bash
-# Activate environment first
-source env/bin/activate
+# The ONLY correct way to create a migration:
+make migration m="description of change"
+# → writes make_post_sell/scripts/alembic/versions/05be3044c2d2_description_of_change.py
+# → revision ID is auto-generated (e.g. 05be3044c2d2), never invent one
 
-# Create a new migration (manual) - ALWAYS use this command
-alembic -c data/development.ini revision -m "description of change"
+# Apply pending migrations:
+make migrate
 
-# OR: Create autogenerated migration (compares DB with models)
-alembic -c data/development.ini revision --autogenerate -m "description of change"
-
-# Edit the generated migration file in make_post_sell/scripts/alembic/versions/
-# The file will have a proper unique ID like: 05be3044c2d2_description_of_change.py
+# Check status:
+make migration-status
 ```
 
+If `make` is not available, the raw command is:
+```bash
+env/bin/alembic -c data/development.ini revision --autogenerate -m "description of change"
+```
+
+The generated file lives in `make_post_sell/scripts/alembic/versions/`. Edit it to add `_column_exists` / `_table_exists` guards (see idempotent pattern below), then commit it.
+
 ### Running Migrations
 ```bash
 # Apply all pending migrations
diff --git a/Makefile b/Makefile
index 10056b7..163d40e 100644
--- a/Makefile
+++ b/Makefile
@@ -150,6 +150,23 @@ init-db: venv config
 	$(MPS_INIT) $(DATA_DIR)/$(CONFIG_FILE)
 	$(ALEMBIC) -c $(DATA_DIR)/$(CONFIG_FILE) stamp head
 
+# Create a new Alembic migration with a proper auto-generated revision ID.
+# Usage: make migration m="description of change"
+# Autogenerate compares current models against DB schema and writes the diff.
+# ALWAYS use this — NEVER hand-write revision IDs.
+migration: venv config
+	@if [ -z "$(m)" ]; then echo "ERROR: provide a message: make migration m=\"add foo column\""; exit 1; fi
+	$(ALEMBIC) -c $(DATA_DIR)/$(CONFIG_FILE) revision --autogenerate -m "$(m)"
+
+# Apply all pending Alembic migrations.
+migrate: venv config
+	$(ALEMBIC) -c $(DATA_DIR)/$(CONFIG_FILE) upgrade head
+
+# Show current migration status.
+migration-status: venv config
+	$(ALEMBIC) -c $(DATA_DIR)/$(CONFIG_FILE) current
+	$(ALEMBIC) -c $(DATA_DIR)/$(CONFIG_FILE) history --verbose
+
 # Start the development server.
 serve: venv config
 	$(PSERVE) $(DATA_DIR)/$(CONFIG_FILE) --reload