Skip to content

Sandbox docs: fix error in docs, add information around start_owner!/2 #665

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
May 10, 2025
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 13 additions & 10 deletions lib/ecto/adapters/sql/sandbox.ex
Original file line number Diff line number Diff line change
Expand Up @@ -48,12 +48,6 @@ defmodule Ecto.Adapters.SQL.Sandbox do
:ok = Ecto.Adapters.SQL.Sandbox.checkout(Repo)
end

setup tags do
pid = Ecto.Adapters.SQL.Sandbox.start_owner!(Repo, shared: not tags[:async])
on_exit(fn -> Ecto.Adapters.SQL.Sandbox.stop_owner(pid) end)
:ok
end

test "create post" do
# Use the repository as usual
assert %Post{} = Repo.insert!(%Post{})
Expand Down Expand Up @@ -417,18 +411,27 @@ defmodule Ecto.Adapters.SQL.Sandbox do
end

@doc """
Starts a process that owns the connection and returns its pid.
Starts a process that will check out and own a connection, then returns that process's pid.

The owner process is not linked to the caller, it is your responsibility to
ensure it will be stopped. In tests, this is done by terminating the pool
in an `ExUnit.Callbacks.on_exit/2` callback:
The process is not linked to the caller, so it is your responsibility to ensure that it will be
stopped with `stop_owner/1`. In tests, this is done in an `ExUnit.Callbacks.on_exit/2` callback:

setup tags do
pid = Ecto.Adapters.SQL.Sandbox.start_owner!(MyApp.Repo, shared: not tags[:async])
on_exit(fn -> Ecto.Adapters.SQL.Sandbox.stop_owner(pid) end)
:ok
end

## `start_owner!/2` vs `checkout/2`

`start_owner!/2` should be used in place of `checkout/2`.

`start_owner!/2` solves the problem of unlinked processes started in a test outliving the test process and causing ownership errors.
For example, `LiveView`'s `live(...)` test helper starts a process linked to the LiveView supervisor, not the test process.
These errors can be eliminated by having the owner of the connection be a separate process from the test process.

Outside of that scenario, `checkout/2` involves less overhead than this function and so can be preferable.

## Options

* `:shared` - if `true`, the pool runs in the shared mode. Defaults to `false`
Expand Down
Loading