chore: add full control of the migration process

Author: zookzook

README.md

@@ -634,6 +634,64 @@ The following  options are available:
 * `:otp_app` - the name of the otp_app to resolve the `priv` folder, defaults to `:mongodb_driver`. In most cases you use your application name.
 * `:topology` - the topology for running the migrations, `:topology` defaults to `:mongo`
 
+### Supporting multiple topologies:
+
+Each function `lock/1, unlock/1, migrate/1, drop/1` accepts a keyword list (options) to override the default config having 
+full control of the migration process. The options are passed through the migration scripts. 
+
+That means you can support multiple topologies, databases and migration collections. Example
+
+    Mongo.start_link(name: :topology_1, url: "mongodb://localhost:27017/mig_test_1", timeout: 60_000, pool_size: 5, idle_interval: 10_000)
+    Mongo.start_link(name: :topology_2, url: "mongodb://localhost:27017/mig_test_2", timeout: 60_000, pool_size: 5, idle_interval: 10_000)
+
+    IO.puts("running default migration")
+    Mongo.Migration.migrate() ## default values specified in the configs
+
+    IO.puts("running topology_2 migration")
+    Mongo.Migration.migrate([topology: :topology_2]) ## override the topology 
+
+Adding the options parameter in the `up/1` and `down/1` function of the migration script is supported as well. It is
+possible to pass additional parameters to the migration scripts.
+
+    defmodule Mongo.Migrations.Topology.CreateIndex do
+        def up(opts) do 
+            IO.inspect(opts)
+            ...
+        end
+        
+        def down(opts) do
+            IO.inspect(opts)
+            ...
+        end
+    end
+
+The topology is part of the namespace and of the migration path as well. The default value is defined in the configuration.
+You can specify the topology in the case of creating a new migration script by appending the name to the script call:
+```elixir
+
+mix mongo.gen.migration add_indexes topology_2
+
+```
+
+In `priv/topology_2/mongo/migrations` you will find an Elixir script like `20220322173354_add_indexes.exs`:
+
+```elixr
+defmodule Mongo.Migrations.Topology2.AddIndexes do
+    ...
+end
+
+```
+
+By using the `:topology` keyword, you can organise the migration scripts in different sub-folders. The migration path is prefixed with the `priv` folder of the application and the topology name.
+
+If you call
+
+    Mongo.Migration.migrate([topology: :topology_2])
+
+then the migration scripts under `/priv/topology_2/` are used and the options keyword list is passed through
+to the `up/1` function if it is implemented. That means you can create migration scripts for multiple topologies
+separated in sub folders and module namespaces.
+
 ## Auth Mechanisms
 
 For versions of Mongo 3.0 and greater, the auth mechanism defaults to SCRAM.

lib/mongo/migration.ex

@@ -2,38 +2,39 @@ defmodule Mongo.Migration do
   @moduledoc false
   use Mongo.Collection
 
-  def migrate() do
-    with :locked <- lock() do
-      migration_files!()
+  def migrate(opts \\ []) do
+    with :locked <- lock(opts) do
+      migration_files!(opts)
       |> compile_migrations()
-      |> Enum.each(fn {mod, version} -> run_up(version, mod) end)
+      |> Enum.each(fn {mod, version} -> run_up(version, mod, opts) end)
 
-      unlock()
+      unlock(opts)
     end
   rescue
     error ->
       IO.puts("🚨 Error when migrating: #{inspect(error)}")
-      unlock()
+      unlock(opts)
   end
 
-  def drop() do
-    with :locked <- lock() do
-      migration_files!()
+  def drop(opts \\ []) do
+    with :locked <- lock(opts) do
+      migration_files!(opts)
       |> compile_migrations()
       |> Enum.reverse()
-      |> Enum.each(fn {mod, version} -> run_down(version, mod) end)
+      |> Enum.each(fn {mod, version} -> run_down(version, mod, opts) end)
 
-      unlock()
+      unlock(opts)
     end
   rescue
     error ->
       IO.puts("🚨 Error when dropping: #{inspect(error)}")
-      unlock()
+      unlock(opts)
   end
 
-  def lock() do
-    topology = get_config()[:topology]
-    collection = get_config()[:collection]
+  def lock(opts \\ []) do
+    topology = get_config(opts)[:topology]
+    collection = get_config(opts)[:collection]
+
     query = %{_id: "lock", used: false}
     set = %{"$set": %{used: true}}
 
@@ -51,9 +52,9 @@ defmodule Mongo.Migration do
     end
   end
 
-  def unlock() do
-    topology = get_config()[:topology]
-    collection = get_config()[:collection]
+  def unlock(opts \\ []) do
+    topology = get_config(opts)[:topology]
+    collection = get_config(opts)[:collection]
     query = %{_id: "lock", used: true}
     set = %{"$set": %{used: false}}
 
@@ -67,13 +68,25 @@ defmodule Mongo.Migration do
     end
   end
 
-  defp run_up(version, mod) do
-    topology = get_config()[:topology]
-    collection = get_config()[:collection]
+  defp run_up(version, mod, opts) do
+    topology = get_config(opts)[:topology]
+    collection = get_config(opts)[:collection]
 
     case Mongo.find_one(topology, collection, %{version: version}) do
       nil ->
-        mod.up()
+        ## check, if the function supports options
+
+        cond do
+          function_exported?(mod, :up, 1) ->
+            apply(mod, :up, [opts])
+
+          function_exported?(mod, :up, 0) ->
+            apply(mod, :up, [])
+
+          true ->
+            raise "The module does not export the up function!"
+        end
+
         Mongo.insert_one(topology, collection, %{version: version})
         IO.puts("⚡️ Successfully migrated #{mod}")
 
@@ -87,13 +100,24 @@ defmodule Mongo.Migration do
       reraise e, __STACKTRACE__
   end
 
-  defp run_down(version, mod) do
-    topology = get_config()[:topology]
-    collection = get_config()[:collection]
+  defp run_down(version, mod, opts) do
+    topology = get_config(opts)[:topology]
+    collection = get_config(opts)[:collection]
 
     case Mongo.find_one(topology, collection, %{version: version}) do
       %{"version" => _version} ->
-        mod.down()
+        ## check, if the function supports options
+        cond do
+          function_exported?(mod, :down, 1) ->
+            apply(mod, :down, [opts])
+
+          function_exported?(mod, :down, 0) ->
+            apply(mod, :down, [])
+
+          true ->
+            raise "The module does not export the down function!"
+        end
+
         Mongo.delete_one(topology, collection, %{version: version})
         IO.puts("💥 Successfully dropped #{mod}")
 
@@ -107,30 +131,39 @@ defmodule Mongo.Migration do
       reraise e, __STACKTRACE__
   end
 
-  def get_config() do
+  def get_config(opts \\ []) do
     defaults = [topology: :mongo, collection: "migrations", path: "mongo/migrations", otp_app: :mongodb_driver]
-    Keyword.merge(defaults, Application.get_env(:mongodb_driver, :migration, []))
+
+    defaults
+    |> Keyword.merge(Application.get_env(:mongodb_driver, :migration, []))
+    |> Keyword.merge(opts)
   end
 
-  def migration_file_path() do
-    path = get_config()[:path]
-    otp_app = get_config()[:otp_app]
-    Path.join([:code.priv_dir(otp_app), path])
+  def migration_file_path(opts \\ []) do
+    path = get_config(opts)[:path]
+    topology = get_config(opts)[:topology]
+    otp_app = get_config(opts)[:otp_app]
+    Path.join([:code.priv_dir(otp_app), to_string(topology), path])
   end
 
-  defp migration_files!() do
-    file_path = migration_file_path()
+  def migration_files!(opts) do
+    file_path = migration_file_path(opts)
+
+    case File.ls(file_path) do
+      {:ok, files} ->
+        files
+        |> Enum.sort()
+        |> Enum.map(fn file_name -> file_path <> "/" <> file_name end)
 
-    case File.ls(migration_file_path()) do
-      {:ok, files} -> Enum.sort(files)
-      {:error, _error} -> raise "Could not find migrations file path #{inspect(file_path)}"
+      {:error, _error} ->
+        raise "Could not find migrations file path #{inspect(file_path)}"
     end
   end
 
   defp compile_migrations(files) do
     Enum.map(files, fn file ->
       mod =
-        (migration_file_path() <> "/" <> file)
+        file
         |> Code.compile_file()
         |> Enum.map(&elem(&1, 0))
         |> List.first()

lib/tasks/gen/migration.ex

@@ -12,8 +12,20 @@ defmodule Mix.Tasks.Mongo.Gen.Migration do
 
   @spec run([String.t()]) :: integer()
   def run(args) do
-    migrations_path = migration_file_path()
-    name = List.first(args)
+    {name, topology} =
+      case args do
+        [name | [topology | _xs]] ->
+          {name, topology}
+
+        [name | _xs] ->
+          {name, Migration.get_config()[:topology]}
+
+        _other ->
+          Mix.raise("Filename is missing")
+      end
+
+    migrations_path = migration_file_path(topology)
+
     base_name = "#{underscore(name)}.exs"
     current_timestamp = timestamp()
     file = Path.join(migrations_path, "#{current_timestamp}_#{base_name}")
@@ -24,16 +36,16 @@ defmodule Mix.Tasks.Mongo.Gen.Migration do
       Mix.raise("Migration can't be created, there is already a migration file with name #{name}.")
     end
 
-    assigns = [mod: Module.concat([Mongo, Migrations, camelize(name)])]
+    assigns = [mod: Module.concat([Mongo, Migrations, camelize(to_string(topology)), camelize(name)])]
     create_file(file, migration_template(assigns))
     String.to_integer(current_timestamp)
   end
 
   @doc """
   Returns the private repository path relative to the source.
   """
-  def migration_file_path() do
-    path = "priv/" <> Migration.get_config()[:path]
+  def migration_file_path(topology) do
+    path = "priv/#{topology}/#{Migration.get_config()[:path]}"
     otp_app = Migration.get_config()[:otp_app]
     Path.join(Mix.Project.deps_paths()[otp_app] || File.cwd!(), path)
   end