From 5088c9637eb9a6ed34280081a46f6b08f3942659 Mon Sep 17 00:00:00 2001
From: Frank Dugan III <frankdugan3@pm.me>
Date: Wed, 5 May 2021 13:58:11 -0500
Subject: [PATCH] feat: document script to iterate migrations

---
 documentation/migrations_and_tasks.md | 48 +++++++++++++++++++++------
 1 file changed, 38 insertions(+), 10 deletions(-)

diff --git a/documentation/migrations_and_tasks.md b/documentation/migrations_and_tasks.md
index 6ec6188e..586db63b 100644
--- a/documentation/migrations_and_tasks.md
+++ b/documentation/migrations_and_tasks.md
@@ -4,20 +4,19 @@
 
 The available tasks are:
 
-* `mix ash_postgres.generate_migrations`
-* `mix ash_postgres.create`
-* `mix ash_postgres.drop`
-* `mix ash_postgres.migrate` (use `mix ash_postgres.migrate --tenants` to run tenant migrations)
+- `mix ash_postgres.generate_migrations`
+- `mix ash_postgres.create`
+- `mix ash_postgres.drop`
+- `mix ash_postgres.migrate` (use `mix ash_postgres.migrate --tenants` to run tenant migrations)
 
 AshPostgres is built on top of ecto, so much of its behavior is pass-through/orchestration of that tooling.
 
 ## Basic Workflow
 
-* Make resource changes
-* Run `mix ash_postgres.generate_migrations` to generate migrations and resource snapshots
-* Run `mix ash_postgres.migrate` to run those migrations
-* Run `mix ash_postgres.migrate --tenants` *as well* if you have multi-tenant resources.
-
+- Make resource changes
+- Run `mix ash_postgres.generate_migrations` to generate migrations and resource snapshots
+- Run `mix ash_postgres.migrate` to run those migrations
+- Run `mix ash_postgres.migrate --tenants` _as well_ if you have multi-tenant resources.
 
 For more information on generating migrations, see the module documentation here:
 `Mix.Tasks.AshPostgres.GenerateMigrations`, or run `mix help ash_postgres.generate_migrations`
@@ -25,11 +24,40 @@ For more information on generating migrations, see the module documentation here
 For running your migrations, there is a mix task that will find all of the repos configured in your apis and run their
 migrations. It is a thin wrapper around `mix ecto.migrate`. Ours is called `mix ash_postgres.migrate`
 
-If you want to run or rollback individual migrations, use the corresponding 
+If you want to run or rollback individual migrations, use the corresponding
 
 For tenant migrations (see the multitenancy guides for more) generated by multitenant resources, make sure you are using
 `mix ash_postgres.generate_migrations`. It is not sufficient to run `mix ash_postgres.migrate --migrations_path tenant_migrations_path`. You will also need to define a `list_tenants/0` function in your repo module. See `AshPostgres.Repo` for more.
 
+### Regenerating Migrations
+
+Often, you will run into a situation where you want to make a slight change to a resource after you've already generated and run migrations. If you are using git and would like to undo those changes, then regenerate the migrations, this script may prove useful:
+
+```bash
+#!/bin/bash
+
+# Get count of untracked migrations
+N_MIGRATIONS=$(git ls-files --others priv/repo/migrations | wc -l)
+
+# Rollback untracked migrations
+mix ecto.rollback -n $N_MIGRATIONS
+
+# Delete untracked migrations and snapshots
+git ls-files --others priv/repo/migrations | xargs rm
+git ls-files --others priv/resource_snapshots | xargs rm
+
+# Regenerate migrations
+mix ash_postgres.generate_migrations
+
+# Run migrations if flag
+if echo $* | grep -e "-m" -q
+then
+  mix ecto.migrate
+fi
+```
+
+After saving this file to something like `regen.sh`, make it executable with `chmod +x regen.sh`. Now you can run it with `./regen.sh`. If you would like the migrations to automatically run after regeneration, add the `-m` flag: `./regen.sh -m`.
+
 ## Multiple Repos
 
 If you are using multiple repos, you will likely need to use `mix ecto.migrate` and manage it separately for each repo, as the options would