feat: add MongoDB database option to Phoenix installer

Author: tevoinea-mdb

installer/lib/mix/tasks/phx.new.ex

@@ -25,6 +25,7 @@ defmodule Mix.Tasks.Phx.New do
 
         * `postgres` - via https://github.com/elixir-ecto/postgrex
         * `mysql` - via https://github.com/elixir-ecto/myxql
+        * `mongo` - via https://github.com/elixir-mongo/mongodb_ecto
         * `mssql` - via https://github.com/livehelpnow/tds
         * `sqlite3` - via https://github.com/elixir-sqlite/ecto_sqlite3
 

installer/lib/phx_new/generator.ex

@@ -406,6 +406,10 @@ defmodule Phx.New.Generator do
     {:ecto_sqlite3, Ecto.Adapters.SQLite3, fs_db_config(app, module)}
   end
 
+  defp get_ecto_adapter("mongo", app, module) do
+    {:mongodb_ecto, Mongo.Ecto, mongo_db_config(app, module)}
+  end
+
   defp get_ecto_adapter(db, _app, _mod) do
     Mix.raise("Unknown database #{inspect(db)}")
   end
@@ -455,6 +459,38 @@ defmodule Phx.New.Generator do
     ]
   end
 
+  defp mongo_db_config(app, module) do
+    [
+      dev: [
+        mongo_url: "mongodb://localhost:27017/#{app}_dev",
+        pool_size: 10,
+        stacktrace: true,
+        show_sensitive_data_on_connection_error: true
+      ],
+      test: [
+        mongo_url:
+          {:literal,
+           ~s|"mongodb://localhost:27017/#{app}_test\#{System.get_env("MIX_TEST_PARTITION")}"|},
+        pool_size: 5
+      ],
+      test_setup_all: "",
+      test_setup: "Mongo.Ecto.truncate(#{inspect(module)}.Repo)",
+      prod_variables: """
+      database_url =
+        System.get_env("DATABASE_URL") ||
+          raise \"""
+          environment variable DATABASE_URL is missing.
+          For example: mongodb://user:pass@host/database
+          \"""
+      """,
+      prod_config: """
+      mongo_url: database_url,
+      pool_size: String.to_integer(System.get_env("POOL_SIZE") || "10")
+      """,
+      binary_id: true
+    ]
+  end
+
   defp socket_db_config(app, module, user, pass) do
     [
       dev: [

installer/lib/phx_new/interactive.ex

@@ -4,6 +4,7 @@ defmodule Phx.New.Interactive do
   @databases [
     {"postgres", "PostgreSQL (postgrex)"},
     {"mysql", "MySQL (myxql)"},
+    {"mongo", "MongoDB (mongodb_ecto)"},
     {"mssql", "MSSQL (tds)"},
     {"sqlite3", "SQLite3 (ecto_sqlite3)"},
     {"none", "None"}

installer/lib/phx_new/project.ex

@@ -66,6 +66,10 @@ defmodule Phx.New.Project do
     Keyword.fetch!(binding, :mailer)
   end
 
+  def mongo?(%Project{opts: opts}) do
+    Keyword.get(opts, :database) == "mongo"
+  end
+
   def verbose?(%Project{opts: opts}) do
     Keyword.get(opts, :verbose, false)
   end

installer/lib/phx_new/single.ex

@@ -105,6 +105,10 @@ defmodule Phx.New.Single do
     {:eex, :app, "phx_mailer/lib/app_name/mailer.ex.eex": "lib/:app/mailer.ex"}
   ])
 
+  template(:docker_compose, [
+    {:eex, :project, "phx_single/docker-compose.yml.eex": "docker-compose.yml"}
+  ])
+
   def prepare_project(%Project{app: app, base_path: base_path} = project) when not is_nil(app) do
     if in_umbrella?(base_path) do
       %{project | in_umbrella?: true, project_path: Path.dirname(Path.dirname(base_path))}
@@ -147,6 +151,7 @@ defmodule Phx.New.Single do
     if Project.html?(project), do: gen_html(project)
     if Project.mailer?(project), do: gen_mailer(project)
     if Project.gettext?(project), do: gen_gettext(project)
+    if Project.mongo?(project), do: gen_docker_compose(project)
 
     gen_assets(project)
     project
@@ -186,4 +191,8 @@ defmodule Phx.New.Single do
   def gen_mailer(%Project{} = project) do
     copy_from(project, __MODULE__, :mailer)
   end
+
+  def gen_docker_compose(%Project{} = project) do
+    copy_from(project, __MODULE__, :docker_compose)
+  end
 end

installer/templates/phx_ecto/data_case.ex.eex

@@ -7,11 +7,16 @@ defmodule <%= @app_module %>.DataCase do
   your tests.
 
   Finally, if the test case interacts with the database,
+  <% if String.trim(@adapter_config[:test_setup_all]) == "" do %>
+  we truncate all collections before each test, so changes done
+  to the database are reverted.
+  <% else %>
   we enable the SQL sandbox, so changes done to the database
   are reverted at the end of every test. If you are using
   PostgreSQL, you can even run database tests asynchronously
   by setting `use <%= @app_module %>.DataCase, async: true`, although
   this option is not recommended for other databases.
+  <% end %>
   """
 
   use ExUnit.CaseTemplate

installer/templates/phx_single/docker-compose.yml.eex

@@ -0,0 +1,7 @@
+services:
+  mongodb:
+    image: mongo:latest
+    ports:
+      - "27017:27017"
+    environment:
+      MONGO_INITDB_DATABASE: <%= @app_name %>_dev

installer/templates/usage-rules/ecto.md

@@ -0,0 +1,11 @@
+## MongoDB
+
+When the project uses `--database mongo` (adapter: `Mongo.Ecto`):
+
+- **Primary keys must be `:binary_id`** — configured automatically via `config :app, :generators, binary_id: true`. All `mix phx.gen.*` commands honour this automatically; no `--binary-id` flag needed.
+- **No SQL joins** — use embedded schemas (`embeds_one`, `embeds_many`) for nested data, or separate queries for associations.
+- **Migrations create collections and indexes**, not tables. `create table(:name)` → MongoDB collection. `add :col, :type` → no-op (schema-less).
+- **Test isolation** uses `Mongo.Ecto.truncate(Repo)` before each test, not `Ecto.Adapters.SQL.Sandbox`.
+- **Connection string** uses `mongo_url:` config key. In production, set `DATABASE_URL` env var to a MongoDB URI (`mongodb://...` or `mongodb+srv://...`).
+- **Atlas** — swap `DATABASE_URL` to your Atlas connection string; no code changes needed.
+- `:decimal` type is not supported by `mongodb_ecto`.

installer/test/phx_new_test.exs

@@ -748,6 +748,35 @@ defmodule Mix.Tasks.Phx.NewTest do
     end)
   end
 
+  test "new with mongo adapter" do
+    in_tmp("new with mongo adapter", fn ->
+      project_path = Path.join(File.cwd!(), "custom_path")
+      Mix.Tasks.Phx.New.run([project_path, "--database", "mongo"])
+
+      assert_file("custom_path/mix.exs", ":mongodb_ecto")
+
+      assert_file("custom_path/config/dev.exs", [
+        ~r/mongo_url:/,
+        ~r/mongodb:\/\/localhost:27017/
+      ])
+
+      assert_file("custom_path/config/test.exs", [~r/mongo_url:/])
+
+      assert_file("custom_path/config/runtime.exs", [~r/DATABASE_URL/])
+
+      assert_file("custom_path/config/config.exs", ~r/generators: \[.*binary_id: true.*\]/)
+
+      assert_file("custom_path/lib/custom_path/repo.ex", "Mongo.Ecto")
+
+      assert_file(
+        "custom_path/test/support/data_case.ex",
+        "Mongo.Ecto.truncate"
+      )
+
+      assert_file("custom_path/docker-compose.yml", "mongo:7")
+    end)
+  end
+
   test "new with invalid database adapter" do
     in_tmp("new with invalid database adapter", fn ->
       project_path = Path.join(File.cwd!(), "custom_path")
@@ -863,8 +892,8 @@ defmodule Mix.Tasks.Phx.NewTest do
     in_tmp("new interactive custom", fn ->
       # path
       send(self(), {:mix_shell_input, :prompt, "custom_app"})
-      # database: sqlite3 (option 4)
-      send(self(), {:mix_shell_input, :prompt, "4"})
+      # database: sqlite3 (option 5)
+      send(self(), {:mix_shell_input, :prompt, "5"})
       # binary_id: yes
       send(self(), {:mix_shell_input, :prompt, "y"})
       # web: API-only (option 3, skips assets prompt)

installer/test/phx_new_umbrella_test.exs

@@ -680,6 +680,33 @@ defmodule Mix.Tasks.Phx.New.UmbrellaTest do
     end)
   end
 
+  test "new with mongo adapter" do
+    in_tmp("new with mongo adapter", fn ->
+      app = "custom_path"
+      project_path = Path.join(File.cwd!(), app)
+      Mix.Tasks.Phx.New.run([project_path, "--umbrella", "--database", "mongo"])
+
+      assert_file(app_path(app, "mix.exs"), ":mongodb_ecto")
+      assert_file(app_path(app, "lib/custom_path/repo.ex"), "Mongo.Ecto")
+
+      assert_file(root_path(app, "config/dev.exs"), [
+        ~r/mongo_url:/,
+        ~r/mongodb:\/\/localhost:27017/
+      ])
+
+      assert_file(root_path(app, "config/test.exs"), [~r/mongo_url:/])
+
+      assert_file(root_path(app, "config/runtime.exs"), [~r/DATABASE_URL/])
+
+      assert_file(root_path(app, "config/config.exs"), ~r/generators: \[.*binary_id: true.*\]/)
+
+      assert_file(
+        app_path(app, "test/support/data_case.ex"),
+        "Mongo.Ecto.truncate"
+      )
+    end)
+  end
+
   test "new with invalid database adapter" do
     in_tmp("new with invalid database adapter", fn ->
       project_path = Path.join(File.cwd!(), "custom_path")