From cda83371c4b25e42ab0285837ea5138d75ad909b Mon Sep 17 00:00:00 2001
From: myrmidex <myrmidex@myrmidex.net>
Date: Thu, 18 Jun 2026 23:48:27 +0200
Subject: [PATCH] 31 - Add dev-migrate shell helpers

---
 shell.nix | 41 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 41 insertions(+)

diff --git a/shell.nix b/shell.nix
index af9389b..fede276 100644
--- a/shell.nix
+++ b/shell.nix
@@ -119,6 +119,44 @@ pkgs.mkShell {
       $COMPOSE exec php vendor/bin/php-cs-fixer fix "$@"
     }
 
+    # ===================
+    # DATABASE / MIGRATION COMMANDS
+    # ===================
+    # The Doctrine migration workflow, simplified. Typical loop:
+    #   1. change an entity mapping
+    #   2. dev-migrate-diff   -> generate ONE migration from the mapping (review it!)
+    #   3. dev-migrate        -> apply to BOTH dev and test DBs
+    # If you generated/applied a wrong migration: dev-migrate-prev rolls back BOTH DBs,
+    # then delete the bad migrations/Version*.php file and re-run dev-migrate-diff.
+
+    dev-migrate-diff() {
+      # Generate a migration from the diff between entity mappings and the dev DB schema.
+      # ALWAYS read the generated migrations/Version*.php before applying it.
+      echo "Generating migration from entity mapping diff..."
+      $COMPOSE exec php php bin/console doctrine:migrations:diff "$@"
+      echo ""
+      echo ">> Review the new file in migrations/ before running dev-migrate."
+    }
+
+    dev-migrate() {
+      # Apply pending migrations to BOTH the dev and test databases.
+      # Interactive: Doctrine will prompt before destructive/unregistered changes — read them.
+      echo "=== Migrating DEV database (buckets) ==="
+      $COMPOSE exec php php bin/console doctrine:migrations:migrate "$@"
+      echo ""
+      echo "=== Migrating TEST database (buckets_test) ==="
+      $COMPOSE exec php php bin/console doctrine:migrations:migrate --env=test "$@"
+    }
+
+    dev-migrate-prev() {
+      # Roll back the most recent migration on BOTH the dev and test databases.
+      echo "=== Rolling back DEV database (buckets) one step ==="
+      $COMPOSE exec php php bin/console doctrine:migrations:migrate prev "$@"
+      echo ""
+      echo "=== Rolling back TEST database (buckets_test) one step ==="
+      $COMPOSE exec php php bin/console doctrine:migrations:migrate prev --env=test "$@"
+    }
+
     # ===================
     # BUILD COMMANDS
     # ===================
@@ -174,6 +212,9 @@ pkgs.mkShell {
     echo "  dev-stan [args]     Run PHPStan static analysis"
     echo "  dev-cs [args]       Check code style (dry-run)"
     echo "  dev-cs-fix [args]   Apply code style fixes"
+    echo "  dev-migrate-diff    Generate a migration from entity mappings"
+    echo "  dev-migrate         Apply migrations to dev + test DBs"
+    echo "  dev-migrate-prev    Roll back one migration on dev + test DBs"
     echo "  base-build          Build and push image"
     echo ""
     echo "Services:"