# Incremental Migration
[< Repo Testing](repo-testing.md) | [Up: README](../README.md)
This guide covers adopting DoubleDown into an existing Elixir/Phoenix
codebase alongside direct Ecto.Repo calls. You don't need to migrate
everything at once — the two styles coexist cleanly.
## Strategy: new code first
The highest-impact, lowest-risk approach is:
1. **Don't migrate existing tests.** They work, they have value, leave
them on the Ecto sandbox.
2. **Write new domain logic behind contracts.** New contexts,
new features, new orchestration functions.
3. **Migrate existing code opportunistically.** When you're already
changing a function, wrap it in a contract boundary.
This means your test suite gradually shifts from slow DB-backed tests
to fast in-memory tests as new code accumulates — without any
big-bang migration.
## The two-contract pattern
Most domain logic interacts with the database in two ways:
1. **Generic Repo operations** — `insert`, `update`, `delete`, `get`,
`transact`. These are the same across all features.
2. **Domain-specific queries** — "find active users with overdue
invoices", "get the latest shift for this employee". These are
unique to each feature.
DoubleDown handles these with two contracts:
- **`DoubleDown.Repo`** — ships with DoubleDown, covers all
generic Repo operations. One facade per app, shared by all features.
- **A per-feature Queries contract** — you define this with `defcallback`
for each feature's domain-specific reads.
### Example: wrapping a context function
Suppose you have a `Billing.create_invoice/1` function that:
1. Validates params and builds a changeset
2. Looks up the customer's payment method
3. Inserts the invoice
4. Inserts line items
**Step 1: Create a Repo facade** (once per app)
```elixir
defmodule MyApp.Repo do
use DoubleDown.ContractFacade, contract: DoubleDown.Repo, otp_app: :my_app
end
```
```elixir
# config/config.exs
config :my_app, DoubleDown.Repo, impl: MyApp.EctoRepo
# config/test.exs
config :my_app, DoubleDown.Repo, impl: nil
```
**Step 2: Define a Queries contract** for the domain reads
```elixir
defmodule MyApp.Billing.Queries do
use DoubleDown.ContractFacade, otp_app: :my_app
defcallback get_payment_method(customer_id :: integer()) ::
{:ok, PaymentMethod.t()} | {:error, :not_found}
end
```
```elixir
# config/config.exs
config :my_app, MyApp.Billing.Queries, impl: MyApp.Billing.Queries.Ecto
# config/test.exs
config :my_app, MyApp.Billing.Queries, impl: nil
```
**Step 3: Implement the Ecto adapter** for Queries
```elixir
defmodule MyApp.Billing.Queries.Ecto do
@behaviour MyApp.Billing.Queries
@impl true
def get_payment_method(customer_id) do
case MyApp.EctoRepo.get_by(PaymentMethod, customer_id: customer_id) do
nil -> {:error, :not_found}
pm -> {:ok, pm}
end
end
end
```
**Step 4: Write the domain function** using both contracts
```elixir
defmodule MyApp.Billing do
alias MyApp.Repo
alias MyApp.Billing.Queries
def create_invoice(params) do
Repo.transact(fn ->
with {:ok, pm} <- Queries.get_payment_method(params.customer_id),
{:ok, invoice} <- Repo.insert(Invoice.changeset(params, pm)),
{:ok, _items} <- insert_line_items(invoice, params.items) do
{:ok, invoice}
end
end, [])
end
defp insert_line_items(invoice, items) do
Enum.reduce_while(items, {:ok, []}, fn item, {:ok, acc} ->
case Repo.insert(LineItem.changeset(invoice, item)) do
{:ok, li} -> {:cont, {:ok, [li | acc]}}
{:error, cs} -> {:halt, {:error, cs}}
end
end)
end
end
```
**Step 5: Test without a database**
```elixir
defmodule MyApp.BillingTest do
use ExUnit.Case, async: true
alias MyApp.Billing.Queries
setup do
# Queries — stub domain-specific reads
DoubleDown.Double.stub(Queries, :get_payment_method, fn [_customer_id] ->
{:ok, %PaymentMethod{id: 1, type: :card}}
end)
# Repo — stateless writes via Repo.Stub stub
DoubleDown.Double.stub(DoubleDown.Repo, DoubleDown.Repo.Stub)
:ok
end
test "create_invoice inserts invoice and line items" do
DoubleDown.Testing.enable_log(DoubleDown.Repo)
assert {:ok, %Invoice{}} =
MyApp.Billing.create_invoice(%{
customer_id: 1,
items: [%{description: "Widget", amount: 100}]
})
log = DoubleDown.Testing.get_log(DoubleDown.Repo)
operations = Enum.map(log, fn {_, op, _, _} -> op end)
assert :insert in operations
end
end
```
This test runs in < 1ms. No database, no sandbox, no factories.
## Coexisting with direct Ecto.Repo calls
Code that hasn't been migrated continues to call `MyApp.EctoRepo`
directly. Code behind contract boundaries calls `MyApp.Repo` (the
facade). Both work in the same application — there's no conflict.
In tests:
- **Migrated code** uses `DoubleDown.Double` (expect/stub/fake)
— no DB needed, `async: true`
- **Unmigrated code** uses `Ecto.Adapters.SQL.Sandbox` as before
The two can even coexist in the same test if needed (e.g., an
integration test that uses the real DB for some operations and
stubs others).
## The fail-fast pattern
Set `impl: nil` in `config/test.exs` for every contract:
```elixir
# config/test.exs
config :my_app, DoubleDown.Repo, impl: nil
config :my_app, MyApp.Billing.Queries, impl: nil
```
This ensures any test that forgets to set up a double gets an
immediate error instead of silently hitting the real implementation.
For integration tests that intentionally use the real DB, use `fake`
with the production module:
```elixir
DoubleDown.Double.fake(DoubleDown.Repo, MyApp.EctoRepo)
```
## Choosing a Repo fake
- **`Repo.InMemory`** (recommended) — closed-world stateful fake.
The state is the complete truth — all bare-schema reads work
without a fallback. Use this for most tests, especially with
ExMachina factories.
- **`Repo.OpenInMemory`** — open-world stateful fake. The state may
be incomplete — reads for missing records fall through to a
fallback function. Use when you need fine-grained control over
which reads come from state vs fallback.
- **`Repo.Stub`** — stateless stub. Writes succeed but store
nothing. No read-after-write. Fastest setup — use for simple
command-style functions that just write and return.
## What stays on the DB
Some things should remain as integration tests against a real database:
- **Query correctness** — `from u in User, where: u.age > 21` can't
be evaluated in memory. Test these via the Ecto adapter.
- **Constraint validation** — unique indexes, foreign keys, check
constraints.
- **Transaction isolation** — rollback behaviour, concurrent writes.
- **Migration testing** — schema changes against a real DB.
- **End-to-end flows** — API → context → DB → response.
The goal isn't to eliminate DB tests — it's to ensure that the tests
which don't *need* a DB don't *use* a DB.
---
[< Repo Testing](repo-testing.md) | [Up: README](../README.md)
