
elixir
Elixir development skills: Phoenix, OTP, Ports, Ecto, Tidewave MCP, testing, configuration, style, and anti-patterns
- version
- 0.1.25
- GitHub stars
- 27
Install
/plugin install elixir@vinnie357Run it inside Claude Code after adding the marketplace with /plugin marketplace add vinnie357/claude-skills.
Contents
Discovered from sourceSkills 9
Elixir Anti-Patterns Detection and Refactoring
You are an expert at identifying Elixir anti-patterns and suggesting idiomatic refactorings. Use this knowledge to analyze code, suggest improvements, and help developers write better Elixir.
Code-Related Anti-Patterns
1. Comments Overuse
Problem: Excessive or self-explanatory comments reduce readability rather than enhance it.
Detection:
- Inline comments explaining obvious code
- Comments for every function line
- Comments duplicating what code already says clearly
Refactoring:
- Use clear function and variable names instead of explanatory comments
- Replace inline comments with
@docand@moduledocfor documentation - Use module attributes for configuration values
Example:
# Bad
def calculate() do
# Get current time
now = DateTime.utc_now()
# Add 5 minutes
DateTime.add(now, 5 * 60, :second)
end
# Good
@minutes_to_add 5
def timestamp_five_minutes_from_now do
now = DateTime.utc_now()
DateTime.add(now, @minutes_to_add * 60, :second)
end
2. Complex else Clauses in with
Problem: Flattening all error handling into a single complex else block obscures which clause produced which error.
Detection:
- Large
elseblocks with many pattern match clauses - Difficulty determining error sources
- Complex error handling logic in
else
Refactoring:
- Normalize return types in private functions
- Handle errors closer to their source
- Let
withfocus on success paths
Example:
# Bad
def read_config(path) do
with {:ok, content} <- File.read(path),
{:ok, decoded} <- Jason.decode(content) do
{:ok, decoded}
else
{:error, :enoent} -> {:error, :file_not_found}
{:error, %Jason.DecodeError{}} -> {:error, :invalid_json}
{:error, reason} -> {:error, reason}
end
end
# Good
def read_config(path) do
with {:ok, content} <- read_file(path),
{:ok, config} <- parse_json(content) do
{:ok, config}
end
end
defp read_file(path) do
case File.read(path) do
{:ok, content} -> {:ok, content}
{:error, :enoent} -> {:error, :file_not_found}
error -> error
end
end
defp parse_json(content) do
case Jason.decode(content) do
{:ok, data} -> {:ok, data}
{:error, _} -> {:error, :invalid_json}
end
end
3. Complex Extractions in Clauses
Problem: Extracting values across multiple clauses and arguments makes it unclear which variables serve pattern/guard purposes versus function body usage.
Detection:
- Many variable extractions in function heads
- Mixed guard and body variable usage
- Unclear variable purposes
Refactoring:
- Extract only pattern/guard-related variables in function signatures
- Use capture patterns like
%User{age: age} = user - Extract body variables inside the clause
Example:
# Bad
def process(%User{age: age, name: name, email: email} = user) when age >= 18 do
# Only using name and email in body, not age
send_email(email, "Hello #{name}")
end
# Good
def process(%User{age: age} = user) when age >= 18 do
send_email(user.email, "Hello #{user.name}")
end
4. Dynamic Atom Creation
Problem: Atoms aren't garbage-collected and are limited to ~1 million. Uncontrolled dynamic atom creation poses memory and security risks.
Detection:
String.to_atom/1with untrusted input- Converting user input directly to atoms
- Unbounded atom creation in loops
Refactoring:
- Use explicit mappings via pattern-matching
- Use
String.to_existing_atom/1with pre-defined atoms - Keep strings when atom conversion isn't necessary
Example:
# Bad - Security risk!
def set_role(user, role_string) do
%{user | role: String.to_atom(role_string)}
end
# Good
def set_role(user, role) when role in [:admin, :editor, :viewer] do
%{user | role: role}
end
# Or with pattern matching
def set_role(user, "admin"), do: %{user | role: :admin}
def set_role(user, "editor"), do: %{user | role: :editor}
def set_role(user, "viewer"), do: %{user | role: :viewer}
def set_role(_user, invalid), do: {:error, "Invalid role: #{invalid}"}
5. Long Parameter List
Problem: Functions with excessive parameters become confusing and error-prone to use.
Detection:
- Functions with 4+ parameters
- Parameters that are conceptually related
- Difficult to remember parameter order
Refactoring:
- Group related parameters into maps or structs
- Use keyword lists for optional parameters
- Create domain objects
Example:
# Bad
def create_loan(user_id, user_name, user_email, book_id, book_title, book_isbn) do
# ...
end
# Good
def create_loan(user, book) do
# ...
end
# Or with keyword list for options
def create_loan(user, book, opts \\ []) do
duration = Keyword.get(opts, :duration, 14)
renewable = Keyword.get(opts, :renewable, true)
# ...
end
6. Namespace Trespassing
Problem: Defining modules outside your library's namespace risks conflicts since the Erlang VM loads only one module instance per name.
Detection:
- Library defining modules in common namespaces (e.g.,
Plug.*when you're not Plug) - Modules without library prefix
- Potential naming conflicts with other libraries
Refactoring:
- Always prefix modules with your library namespace
- Use clear, unique top-level module names
Example:
# Bad - Library named :plug_auth
defmodule Plug.Auth do
# This conflicts with the actual Plug library!
end
# Good
defmodule PlugAuth do
# ...
end
defmodule PlugAuth.Session do
# ...
end
7. Non-assertive Map Access
Problem: Using dynamic access (map[:key]) for required keys masks missing data, allowing nil to propagate instead of failing fast.
Detection:
map[:key]for required/expected keys- Nil checks after map access
- Silent failures from missing keys
Refactoring:
- Use static access (
map.key) for required keys - Pattern-match on struct/map keys
- Reserve dynamic access for optional fields
Example:
# Bad
def distance(point) do
x = point[:x] # Returns nil if :x is missing!
y = point[:y]
:math.sqrt(x * x + y * y) # Crashes on nil, but unclear why
end
# Good
def distance(%{x: x, y: y}) do
:math.sqrt(x * x + y * y) # Clear error if keys missing
end
# Or with structs
defmodule Point do
defstruct [:x, :y]
end
def distance(%Point{x: x, y: y}) do
:math.sqrt(x * x + y * y)
end
8. Non-assertive Pattern Matching
Problem: Writing defensive code that returns incorrect values instead of using pattern matching to assert expected structures causes silent failures.
Detection:
- Defensive nil checks instead of pattern matching
- Functions returning invalid data on unexpected input
- Avoiding crashes when crashes are appropriate
Refactoring:
- Use pattern matching to assert expected structures
- Let functions crash on invalid input
- Trust supervisors to handle failures
Example:
# Bad
def parse_query_param(param) do
case String.split(param, "=") do
[key, value] -> {key, value}
_ -> {"", ""} # Silent failure!
end
end
# Good
def parse_query_param(param) do
[key, value] = String.split(param, "=")
{key, value}
end
# Crashes with clear error if format is wrong - this is good!
9. Non-assertive Truthiness
Problem: Using truthiness operators (&&, ||, !) when all operands are boolean is unnecessarily generic and unclear.
Detection:
&&,||,!with boolean expressions- Comparisons like
is_binary(x) && is_integer(y) - Mixing boolean and truthy logic
Refactoring:
- Use
and,or,notfor boolean-only operations - Reserve
&&,||,!for truthy/falsy logic
Example:
# Bad
def valid_user?(name, age) do
is_binary(name) && is_integer(age) && age >= 18
end
# Good
def valid_user?(name, age) do
is_binary(name) and is_integer(age) and age >= 18
end
# Truthy operators are OK for nil/value checks
def get_name(user) do
user[:name] || "Anonymous"
end
10. Structs with 32 Fields or More
Problem: Structs with 32+ fields switch from Erlang's efficient flat-map representation to hash maps, increasing memory usage.
Detection:
- Struct definitions with 32+ fields
- Large, flat data structures
- Performance degradation with many fields
Refactoring:
- Nest optional fields into metadata structures
- Use nested structs for related fields
- Group frequently-accessed fields separately
Example:
# Bad
defmodule User do
defstruct [
:id, :email, :name, :age, :address, :city, :state, :zip,
:phone, :mobile, :fax, :company, :title, :department,
:created_at, :updated_at, :last_login, :login_count,
:preference1, :preference2, :preference3, :preference4,
# ... 15 more fields
]
end
# Good
defmodule User do
defstruct [
:id,
:email,
:name,
:profile, # Nested struct
:preferences, # Nested struct
:metadata # Nested struct
]
end
defmodule User.Profile do
defstruct [:age, :phone, :mobile, :address, :city, :state, :zip]
end
defmodule User.Preferences do
defstruct [:theme, :notifications, :language]
end
Design-Related Anti-Patterns
Alternative return types, boolean obsession, exceptions used for control flow, primitive
obsession, unrelated multi-clause functions, and using application configuration for libraries:
see references/design-anti-patterns.md. This split follows upstream's own code/design
division — a real seam, not an arbitrary cut.
Usage Guidelines
When reviewing or writing Elixir code:
- Scan for anti-patterns - Check code against the patterns listed above
- Explain the problem - Help the developer understand why it's an issue
- Suggest refactoring - Provide concrete, idiomatic alternatives
- Consider context - Sometimes anti-patterns are acceptable for specific use cases
- Prioritize - Focus on high-impact issues first (security, performance, maintainability)
Key Principles
- Let it crash - Use pattern matching to assert expectations; don't write defensive code
- Fail fast - Expose errors early rather than propagating nil or invalid data
- Be explicit - Prefer clear, specific code over clever or terse solutions
- Model your domain - Create types that represent business concepts
- Design for clarity - Code should be obvious to read and maintain
Elixir Configuration
Guide for proper application configuration in Elixir, with emphasis on understanding and correctly using runtime vs compile-time configuration.
Critical Principle
Runtime configuration is the preferred approach. Only use compile-time configuration when values must affect compilation itself.
Configuration Files
config/config.exs (Compile-Time)
Evaluated during project compilation, before your application starts.
import Config
# Basic configuration
config :my_app, MyApp.Repo,
database: "my_app_dev",
username: "postgres",
password: "postgres",
hostname: "localhost"
# Environment-specific config
config :my_app,
environment: config_env()
# Import environment-specific config files
import_config "#{config_env()}.exs"
Key characteristics:
- Runs at compile time
- Uses
import Config(notuse Mix.Config) - Can use
config_env()andconfig_target() - Can import other config files with
import_config/1 - Deep-merges keyword lists
- Library config.exs is NOT evaluated when used as a dependency
config/runtime.exs (Runtime)
Evaluated right before applications start in both Mix and releases.
import Config
# Read from environment variables
config :my_app, MyApp.Repo,
database: System.get_env("DATABASE_NAME") || "my_app_dev",
username: System.get_env("DATABASE_USER") || "postgres",
password: System.get_env("DATABASE_PASSWORD") || "postgres",
hostname: System.get_env("DATABASE_HOST") || "localhost",
pool_size: String.to_integer(System.get_env("POOL_SIZE") || "10")
# Conditional runtime configuration
if config_env() == :prod do
config :my_app, MyAppWeb.Endpoint,
secret_key_base: System.fetch_env!("SECRET_KEY_BASE"),
http: [port: String.to_integer(System.fetch_env!("PORT"))]
end
Key characteristics:
- Runs at application startup (both dev and prod)
- Executes in both Mix projects and releases
- Used for environment variables and runtime values
- Does NOT support
import_config/1 - Can use
System.get_envandSystem.fetch_env!
config/dev.exs, config/test.exs, config/prod.exs
Environment-specific compile-time configuration, typically imported from config.exs:
# config/config.exs
import_config "#{config_env()}.exs"
# config/dev.exs
import Config
config :my_app, MyApp.Repo,
show_sensitive_data_on_connection_error: true,
pool_size: 10
# config/test.exs
import Config
config :my_app, MyApp.Repo,
pool: Ecto.Adapters.SQL.Sandbox,
pool_size: 10
# config/prod.exs
import Config
# Production-specific compile-time config only
config :my_app, MyAppWeb.Endpoint,
cache_static_manifest: "priv/static/cache_manifest.json"
Accessing Configuration
Runtime Access (Preferred)
Use in function bodies to read configuration at runtime:
Application.get_env/3
defmodule MyApp.Service do
def start_link do
# Get with default value
timeout = Application.get_env(:my_app, :timeout, 5000)
GenServer.start_link(__MODULE__, timeout, name: __MODULE__)
end
end
When to use:
- Reading config in function bodies (most common)
- When a sensible default exists
- When config might change between environments
Application.fetch_env!/2
defmodule MyApp.Mailer do
def deliver(email) do
# Raise if not configured (for required config)
api_key = Application.fetch_env!(:my_app, :mailgun_api_key)
send_email(email, api_key)
end
end
When to use:
- Required configuration that must exist
- When you want explicit errors for missing config
- When no sensible default exists
Application.fetch_env/2
defmodule MyApp.Cache do
def get(key) do
case Application.fetch_env(:my_app, :cache_adapter) do
{:ok, adapter} -> adapter.get(key)
:error -> nil # No caching configured
end
end
end
When to use:
- Optional configuration
- When you need pattern matching on result
- When absence of config is a valid state
Compile-Time Access (Use Sparingly)
Use only when configuration must affect compilation:
Application.compile_env/3
defmodule MyApp.JSONEncoder do
# Only use compile_env when the value affects compilation
@json_library Application.compile_env(:my_app, :json_library, Jason)
def encode(data) do
# The specific library is compiled into the module
@json_library.encode(data)
end
end
When to use:
- Configuration affects which code gets compiled
- Performance-critical paths where indirection is costly
- Compile-time optimizations or code generation
Warning: Mix tracks compile-time config and raises errors if values diverge between compile and runtime.
Application.compile_env!/2
defmodule MyApp.Adapter do
# Raises at compile time if not configured
@adapter Application.compile_env!(:my_app, :storage_adapter)
def store(data) do
@adapter.put(data)
end
end
When to use:
- Required compile-time configuration
- Adapters or behaviors selected at compile time
Common Patterns
Five worked patterns — environment variables in runtime, dev/prod split, storing config_env()
for runtime access, optional features, and child specs with runtime config: see
references/patterns.md.
Anti-Patterns to Avoid
❌ Using compile_env for Runtime Values
# DON'T: Using compile_env for environment variables
defmodule MyApp.Service do
@api_key Application.compile_env(:my_app, :api_key)
def call do
# This won't work correctly in releases!
HTTPoison.get(url, [{"Authorization", @api_key}])
end
end
Why it's wrong: Environment variables aren't available at compile time in releases.
Correct approach:
defmodule MyApp.Service do
def call do
# Read at runtime
api_key = Application.fetch_env!(:my_app, :api_key)
HTTPoison.get(url, [{"Authorization", api_key}])
end
end
❌ Reading Other Application's Config
# DON'T: Directly access other app's configuration
defmodule MyApp do
def logger_level do
Application.get_env(:logger, :level) # Fragile coupling
end
end
Why it's wrong: Creates tight coupling and breaks encapsulation.
Correct approach:
# Configure it in your own app
# config/config.exs
config :my_app, :log_level, :info
# Then read your own config
defmodule MyApp do
def log_level do
Application.get_env(:my_app, :log_level, :info)
end
end
❌ Using Application Config in Libraries
# DON'T: In a library
defmodule MyLibrary do
def process(data) do
# Library reading its own application environment
timeout = Application.get_env(:my_library, :timeout, 5000)
do_work(data, timeout)
end
end
Why it's wrong: Library config.exs is not evaluated when used as a dependency.
Correct approach:
# DO: Accept options as arguments
defmodule MyLibrary do
def process(data, opts \\ []) do
timeout = Keyword.get(opts, :timeout, 5000)
do_work(data, timeout)
end
end
# Users configure in their application
defmodule MyApp.Worker do
def run do
opts = Application.get_env(:my_app, :my_library_opts, [])
MyLibrary.process(data, opts)
end
end
❌ Using Mix Module in Application Code
# DON'T: Use Mix.env() in application code
defmodule MyApp do
def environment do
Mix.env() # Won't work in releases!
end
end
Why it's wrong: Mix is not available in production releases.
Correct approach:
# Store it in config
# config/config.exs
config :my_app, :environment, config_env()
# Access from application environment
defmodule MyApp do
def environment do
Application.fetch_env!(:my_app, :environment)
end
end
Config Functions Reference
In Configuration Files
| Function | Description | Where to Use |
|---|---|---|
config/2 | Configure app with keyword list | All config files |
config/3 | Configure app key with value | All config files |
config_env/0 | Get current environment (:dev, :test, :prod) | All config files |
config_target/0 | Get build target | All config files |
import_config/1 | Import other config files | Not in runtime.exs |
In Application Code
| Function | Return Type | Use Case |
|---|---|---|
Application.get_env/3 | value | default | Runtime with default |
Application.fetch_env/2 | {:ok, value} | :error | Runtime with pattern matching |
Application.fetch_env!/2 | value (raises if missing) | Required runtime config |
Application.compile_env/3 | value | Compile-time with default |
Application.compile_env!/2 | value (raises if missing) | Required compile-time config |
Migration Guide
Moving from use Mix.Config to import Config, and moving runtime values out of
config.exs into runtime.exs: see references/migration.md.
Best Practices Summary
- Default to Runtime Configuration: Use
Application.get_env/3in function bodies - Use runtime.exs for Environment Variables: Never read env vars in
config.exs - Use compile_env Only When Necessary: Only when config affects compilation
- Libraries Should Not Use Application Config: Accept options as function arguments
- Never Use Mix in Application Code: Use
config_env()in config files, store result - Validate Required Config Early: Use
fetch_env!/2in application start for required values - Provide Sensible Defaults: Use
get_env/3with defaults for optional config - Document Configuration: Add comments explaining what each config key does
- Use runtime.exs for Releases: Essential for Elixir releases and deployments
- Store config_env() for Runtime Use: Can't call
config_env()outside config files
Debugging Configuration
Check Current Configuration
# In IEx
Application.get_all_env(:my_app)
# Check specific key
Application.fetch_env(:my_app, :some_key)
# See all applications
Application.loaded_applications()
Common Issues
Problem: Config not available in tests
# config/test.exs
import Config
config :my_app, :test_value, "configured"
Problem: Different values in dev vs release
Check that runtime.exs is being used and environment variables are set correctly.
Problem: Compile-time config not updating
# Clean and recompile
mix clean
mix compile
Resources
- Config Module Docs: https://hexdocs.pm/elixir/Config.html
- Application Module Docs: https://hexdocs.pm/elixir/Application.html
- Runtime Configuration Guide: https://hexdocs.pm/mix/Mix.Tasks.Release.html#module-runtime-configuration
Key Insights
"Reading the application environment at runtime is the preferred approach."
"If you are writing a library to be used by other developers, it is generally recommended to avoid the application environment, as the application environment is effectively a global storage."
"config/config of a library is not evaluated when the library is used as a dependency, as configuration is always meant to configure the current project."
Configuration is a cross-cutting concern. Default to runtime configuration with Application.get_env/3, and only reach for compile-time configuration when you have a specific need for it that justifies the trade-offs.
Ecto
Canonical reference for Ecto data work in Elixir. Verified against ecto 3.13.5 / ecto_sql 3.13.5 (signatures pulled from installed dep source). Newer minor versions add APIs but keep these signatures stable.
The default rule
Ecto schemas + changesets are the default. Raw SQL via Ecto.Adapters.SQL.query/4 is the fallback.
Reads can use raw SQL when no Ecto query DSL covers the case. Writes go through changesets so validation and constraints run. Bypassing changesets silently ships malformed rows — bugs surface at read time, not write time.
Reach for raw SQL only when one of the escape-hatch criteria applies. Default to Repo.all, Repo.insert, Repo.update, Repo.delete and changesets.
Reads — query DSL
Use the Ecto.Query DSL (from, where, join, select, fragment) over string SQL. The DSL composes, type-checks against the schema, and prevents SQL injection.
import Ecto.Query
# Good — composable, type-safe
def list_open_epics(repo_filter) do
from(e in Epic,
where: e.status == "open" and e.target_repos == ^repo_filter,
order_by: [desc: e.priority],
select: e
)
|> Repo.all()
end
# Use fragment/1 only for SQL the DSL cannot express
def case_insensitive_search(term) do
from(e in Epic,
where: fragment("? ILIKE ?", e.title, ^"%#{term}%")
)
|> Repo.all()
end
# Bad — string SQL, no schema typing, no composition
Ecto.Adapters.SQL.query!(Repo,
"SELECT * FROM epics WHERE status = $1",
["open"]
)
Repo.get/3 (single by primary key), Repo.one/2 (assert single result), Repo.all/2 (list), Repo.exists?/2 (boolean) cover most read entry points.
Writes — changesets
Every write builds a %Ecto.Changeset{} from a struct + attrs, then runs through Repo.insert/2, Repo.update/2, or Repo.delete/2.
Verified signatures (ecto 3.13.5):
Ecto.Changeset.cast(data, params, permitted, opts \\ [])
Ecto.Changeset.validate_required(changeset, fields, opts \\ [])
Ecto.Changeset.unique_constraint(changeset, field_or_fields, opts \\ [])
Ecto.Changeset.validate_format(changeset, field, regex, opts \\ [])
Real exemplar from Vantageex.Epics.Epic:
def changeset(epic, attrs) do
epic
|> cast(attrs, [:external_id, :title, :slug, :objective, :status, :priority])
|> validate_required([:external_id, :title, :slug, :objective])
|> validate_inclusion(:status, @valid_statuses)
|> unique_constraint(:slug)
end
Return tuples are {:ok, struct} on success or {:error, %Ecto.Changeset{}} on validation/constraint failure. Pattern-match both branches:
def create_epic(attrs) do
%Epic{}
|> Epic.changeset(attrs)
|> Repo.insert()
end
case create_epic(attrs) do
{:ok, epic} -> handle_success(epic)
{:error, changeset} -> render_errors(changeset)
end
For bang-vs-non-bang and idiomatic error returns, see /elixir:style.
Batch writes
Repo.update_all/3 and Repo.delete_all/2 skip changesets — no per-row validation, no before_*/after_* hooks. Use them for mass updates where validation is irrelevant or already enforced upstream.
# Bulk: clear stale fields across many rows
from(e in Epic, where: e.status == "stale")
|> Repo.update_all(set: [last_peek_output: nil])
When validation matters, prefer N changeset updates inside a transaction over one update_all. Measure before bulk-updating "for performance" — Postgres handles thousands of indexed updates in milliseconds.
Migrations
Schema changes use add, alter, drop, create index, create table macros. Verified signatures (ecto_sql 3.13.5):
Ecto.Migration.add(column, type, opts \\ [])
Ecto.Migration.execute(command) # binary, 0-arity fn, or list
defmacro create(object, do: block) # for tables/indexes with column blocks
defmodule MyApp.Repo.Migrations.AddPriorityToEpics do
use Ecto.Migration
def change do
alter table(:epics) do
add :priority, :integer, default: 10, null: false
end
create index(:epics, [:priority])
end
end
Data migrations — local snapshot schema pattern
Data migrations transform existing rows. Two rules:
- Never
aliasthe live application schema. The live schema evolves; a migration written againstMyApp.Epics.Epictoday breaks when fields get renamed or removed in a future migration. Replay from scratch fails. - Define a local snapshot schema inside the migration module. It captures the schema's shape at this point in history.
defmodule MyApp.Repo.Migrations.BackfillEpicPriority do
use Ecto.Migration
import Ecto.Query
defmodule Epic do
use Ecto.Schema
schema "epics" do
field :priority, :integer
field :status, :string
end
end
def change do
repo = repo()
from(e in Epic, where: is_nil(e.priority))
|> repo.all()
|> Enum.each(fn epic ->
epic
|> Ecto.Changeset.change(priority: priority_for_status(epic.status))
|> repo.update!()
end)
end
defp priority_for_status("urgent"), do: 1
defp priority_for_status(_), do: 10
end
This pattern dogfoods Ecto end-to-end: queries via DSL, writes via changesets, schemas frozen to migration time. See references/migrations.md for additional recipes.
When execute/1 is appropriate
execute/1 runs raw SQL inside a migration. Use it for DB-specific DDL the macros do not cover:
- Postgres extensions:
execute("CREATE EXTENSION IF NOT EXISTS pgcrypto") - Custom indexes:
execute("CREATE INDEX CONCURRENTLY ...")(note:CONCURRENTLYrequires@disable_ddl_transaction true) - Trigger functions, materialized views, partitioning DDL
execute/1 is never the right tool for data transformations. Use the local-snapshot pattern above.
Multi-step atomic ops — Ecto.Multi
Ecto.Multi chains operations into one transaction. If any step fails, prior steps roll back. As of ecto 3.13, Repo.transaction/2 is deprecated — use Repo.transact/2.
Verified signatures:
Ecto.Multi.new() # empty %Ecto.Multi{}
Ecto.Multi.insert(multi, name, changeset_or_struct_or_fn, opts \\ [])
Ecto.Multi.update(multi, name, changeset_or_fn, opts \\ [])
Repo.transact(multi_or_fn, opts \\ [])
def transfer_funds(from_id, to_id, amount) do
Ecto.Multi.new()
|> Ecto.Multi.update(:debit, debit_changeset(from_id, amount))
|> Ecto.Multi.update(:credit, credit_changeset(to_id, amount))
|> Ecto.Multi.insert(:audit, fn %{debit: debit} ->
AuditLog.changeset(%AuditLog{}, %{from: debit.id, amount: amount})
end)
|> Repo.transact()
end
On success: {:ok, %{debit: ..., credit: ..., audit: ...}}. On failure: {:error, failed_step_name, failed_value, changes_so_far}. Pattern-match the four-tuple for the failed-step branch.
The third argument to Multi.insert/4 and Multi.update/4 accepts a 1-arity function fn changes -> changeset end — that is how downstream steps reference upstream results.
When raw SQL IS appropriate
Escape hatch criteria. Each one requires evidence, not assumption.
- Complex CTEs / window functions Ecto's DSL does not expose. Document the missing DSL feature in a comment.
- DB-specific features: PostGIS spatial queries, full-text search ranking with custom dictionaries, advisory locks.
- Perf-critical hot paths with measured Ecto overhead. Benchmark first; "it feels slow" is not evidence.
- One-off reads in tidewave eval (single-cell exploration). Never one-off writes — those go through a changeset even at the REPL.
# Acceptable: PostGIS — no DSL covers ST_DWithin
{:ok, %{rows: rows}} =
Ecto.Adapters.SQL.query(
Repo,
"SELECT id FROM places WHERE ST_DWithin(location, ST_MakePoint($1, $2)::geography, $3)",
[lng, lat, radius]
)
Anti-patterns
repo().query!("UPDATE ...") in migrations
Bypasses Ecto, hides errors, locks the migration to the current row shape. Replace with the local-snapshot pattern.
# Bad
def change do
repo().query!("UPDATE epics SET priority = 1 WHERE status = 'urgent'")
end
# Good — snapshot schema + Repo.update_all (or Repo.update for per-row validation)
defmodule Epic do
use Ecto.Schema
schema "epics" do
field :priority, :integer
field :status, :string
end
end
def change do
from(e in Epic, where: e.status == "urgent")
|> repo().update_all(set: [priority: 1])
end
Bypassing changeset validation via insert_all
Repo.insert_all/3 inserts raw maps without changesets. Use it only when you have already validated the data upstream OR when the rows are infrastructure (e.g. seed data). For user input, always go through a changeset.
Importing live application schema into old migrations
# Bad — couples migration N to whatever Epic looks like at HEAD
defmodule MyApp.Repo.Migrations.OldMigration do
alias MyApp.Epics.Epic # WRONG
...
end
A schema change six months from now breaks migration replay. Define a local snapshot schema instead (see Migrations above).
"Raw SQL because it's faster"
Without measurement, this is fabrication. Ecto's overhead vs raw SQL is microseconds per row. Most perceived "slow Ecto" is N+1 queries (fix with Repo.preload/3 or a join), missing indexes, or unbounded result sets — not the DSL itself.
References
references/migrations.md— local snapshot schema deep dive, common DDL recipes, reversible migrations,@disable_ddl_transactionrulesreferences/migrations-audit.md— repeatable two-phase (haiku indexer + opus reviewer) template for auditing a repo's migrations for/elixir:ectocompliance; reuses across repos by swapping the app namespacereferences/changesets.md—cast_assoc,validate_*catalog, custom validations,prepare_changes/2- HexDocs: Ecto, Ecto.Changeset, Ecto.Query, Ecto.Multi, Ecto.Migration
/elixir:tidewave— runtime introspection of schemas viamcp__tidewave__get_ecto_schemasand live API doc lookup/elixir:phoenix— context-pattern integration (changeset usage in Phoenix contexts)/elixir:style— bang-vs-non-bang return semantics, idiomatic error returns
Anti-fabrication
Every API signature in this skill is verified from the installed source under deps/ecto/ and deps/ecto_sql/ (ecto 3.13.5). When this skill is loaded:
- Cite signatures from
mcp__tidewave__get_docsor the installed dep source — not memory. - Mark any unverified function as "requires investigation".
- See
/core:anti-fabricationfor the authoritative guide.
Elixir OTP and Concurrency
This skill activates when working with OTP behaviors, building concurrent systems, managing processes, or implementing fault-tolerant architectures in Elixir.
OTP Behaviors
Full catalogs for GenServer, Supervisor, Task, and Agent — client/server structure, dynamic supervision, restart configuration — live in references/behaviors.md. Two decisions from that catalog are worth keeping here:
- Agent vs GenServer: use Agent for simple key-value state; use GenServer when you need complex logic, callbacks, or process lifecycle management.
- Supervisor restart strategies:
:one_for_onerestarts only the crashed child;:one_for_allrestarts every child;:rest_for_onerestarts the crashed child and every child started after it.
Process Communication
send/receive
Basic message passing:
# Send message
send(pid, {:hello, "world"})
# Receive message
receive do
{:hello, msg} -> IO.puts(msg)
after
5000 -> IO.puts("Timeout")
end
Process Registration
Register processes by name:
# Local registration
Process.register(self(), :my_process)
send(:my_process, :hello)
# Via Registry
{:ok, _} = Registry.start_link(keys: :unique, name: MyApp.Registry)
{:ok, pid} = GenServer.start_link(MyWorker, nil,
name: {:via, Registry, {MyApp.Registry, "worker_1"}}
)
# Look up process
[{pid, _}] = Registry.lookup(MyApp.Registry, "worker_1")
Process Links and Monitors
Links - Bidirectional, propagate exits:
# Link processes
Process.link(pid)
# Spawn linked
spawn_link(fn -> do_work() end)
Monitors - Unidirectional, receive DOWN messages:
ref = Process.monitor(pid)
receive do
{:DOWN, ^ref, :process, ^pid, reason} ->
IO.puts("Process died: #{inspect(reason)}")
end
Concurrency Patterns
Pipeline Pattern
Chain operations with concurrency:
defmodule Pipeline do
def process(data) do
data
|> async(&step1/1)
|> async(&step2/1)
|> async(&step3/1)
|> await_all()
end
defp async(input, fun) do
Task.async(fn -> fun.(input) end)
end
defp await_all(tasks) when is_list(tasks) do
Enum.map(tasks, &Task.await/1)
end
end
Worker Pool
Implement a worker pool:
defmodule MyApp.WorkerPool do
use GenServer
def start_link(opts) do
pool_size = Keyword.get(opts, :size, 10)
GenServer.start_link(__MODULE__, pool_size, name: __MODULE__)
end
def execute(fun) do
GenServer.call(__MODULE__, {:execute, fun})
end
@impl true
def init(pool_size) do
workers = for _ <- 1..pool_size do
{:ok, pid} = Task.Supervisor.start_link()
pid
end
{:ok, %{workers: workers, index: 0}}
end
@impl true
def handle_call({:execute, fun}, _from, state) do
worker = Enum.at(state.workers, state.index)
task = Task.Supervisor.async_nolink(worker, fun)
new_index = rem(state.index + 1, length(state.workers))
{:reply, task, %{state | index: new_index}}
end
end
Backpressure with GenStage
For producer-consumer pipelines:
defmodule Producer do
use GenStage
def start_link(initial) do
GenStage.start_link(__MODULE__, initial, name: __MODULE__)
end
def init(initial) do
{:producer, initial}
end
def handle_demand(demand, state) do
events = Enum.to_list(state..state + demand - 1)
{:noreply, events, state + demand}
end
end
defmodule Consumer do
use GenStage
def start_link() do
GenStage.start_link(__MODULE__, :ok)
end
def init(:ok) do
{:consumer, :ok}
end
def handle_events(events, _from, state) do
Enum.each(events, &process_event/1)
{:noreply, [], state}
end
end
ETS - Erlang Term Storage
In-memory key-value storage:
# Create table
:ets.new(:my_table, [:named_table, :public, read_concurrency: true])
# Insert
:ets.insert(:my_table, {:key, "value"})
# Lookup
[{:key, value}] = :ets.lookup(:my_table, :key)
# Delete
:ets.delete(:my_table, :key)
# Match patterns
:ets.match(:my_table, {:"$1", "value"})
# Iterate
:ets.foldl(fn {k, v}, acc -> [{k, v} | acc] end, [], :my_table)
ETS Best Practices
- Use
read_concurrency: truefor read-heavy workloads - Use
write_concurrency: truefor write-heavy workloads - Prefer
:set(default) for unique keys - Use
:bagor:duplicate_bagfor multiple values per key - Always own ETS tables in a GenServer or Supervisor to prevent data loss
Error Handling and Fault Tolerance
Let-it-crash philosophy, when to handle errors explicitly instead, and a circuit-breaker pattern live in references/fault-tolerance.md.
Testing Concurrent Systems
Testing GenServers
defmodule MyApp.CounterTest do
use ExUnit.Case, async: true
test "increments counter" do
{:ok, pid} = MyApp.Counter.start_link(0)
assert MyApp.Counter.increment(pid) == 1
assert MyApp.Counter.increment(pid) == 2
assert MyApp.Counter.get_value(pid) == 2
end
end
Testing Asynchronous Processes
test "process receives message" do
parent = self()
spawn(fn ->
receive do
:ping -> send(parent, :pong)
end
end)
send(pid, :ping)
assert_receive :pong, 1000
end
Testing Supervision
test "supervisor restarts crashed worker" do
{:ok, sup} = Supervisor.start_link([MyApp.Worker], strategy: :one_for_one)
[{_, worker_pid, _, _}] = Supervisor.which_children(sup)
# Crash the worker
Process.exit(worker_pid, :kill)
# Wait for restart
Process.sleep(100)
# Verify new worker started
[{_, new_pid, _, _}] = Supervisor.which_children(sup)
assert new_pid != worker_pid
assert Process.alive?(new_pid)
end
Debugging Concurrent Systems
Observer
Launch Observer for visual process inspection:
:observer.start()
Process Info
Inspect running processes:
# List all processes
Process.list()
# Process information
Process.info(pid)
# Message queue length
{:message_queue_len, count} = Process.info(pid, :message_queue_len)
# Current function
{:current_function, {mod, fun, arity}} = Process.info(pid, :current_function)
Tracing
Use :sys module for debugging:
# Enable tracing
:sys.trace(pid, true)
# Get state
:sys.get_state(pid)
# Get status
:sys.get_status(pid)
Performance Considerations
Process Spawning
- Processes are lightweight (< 2KB overhead)
- Spawning thousands/millions of processes is normal
- Use process pools when spawn rate is very high
Message Passing
- Messages are copied between processes
- Large messages are expensive - consider ETS or persistent_term
- Use binary for efficient large data transfer
Bottlenecks
- Single GenServer can become bottleneck
- Solution: shard state across multiple processes
- Use ETS with
read_concurrencyfor read-heavy workloads
Key Principles
- Embrace concurrency: Use processes liberally, they're cheap
- Let it crash: Don't write defensive code, use supervision
- Isolate failures: Design supervision trees to contain failures
- Communicate via messages: Avoid shared state between processes
- Use the right tool: GenServer for state, Task for work, Agent for simple state
- Test at boundaries: Test process APIs, not internal implementation
- Monitor and observe: Use Observer and logging to understand system behavior
References
references/behaviors.md— Full GenServer, Supervisor, Task, and Agent catalogreferences/fault-tolerance.md— Let-it-crash philosophy, explicit error handling, circuit breaker pattern
Phoenix Framework Development
This skill activates when working with Phoenix web applications, including setup, development, LiveView, contexts, controllers, and channels.
Current versions: Phoenix 1.8.x (current: 1.8.5), Phoenix LiveView 1.1.x (current: 1.1.27). Requires Elixir 1.14+, Erlang/OTP 25+.
Phoenix Project Structure
Follow Phoenix conventions:
lib/
my_app/ # Business logic and contexts
accounts/ # Domain contexts
repo.ex
my_app_web/ # Web interface
controllers/
live/ # LiveView modules
components/ # Function components
router.ex
endpoint.ex
Runtime configuration
config/runtime.exs runs at every boot (dev, test, prod). Three settings have caused production outages when configured incorrectly:
Phoenix Endpoint :ip bind config
The Endpoint's :ip bind tuple MUST be set at the TOP LEVEL of runtime.exs, env-driven, with a default of {0, 0, 0, 0} (all IPv4 interfaces). Do NOT gate it inside if port = System.get_env("PORT") do ... end, and do NOT override it later in a prod-only block that hardcodes {0,0,0,0,0,0,0,0} (IPv6 wildcard).
CORRECT:
# config/runtime.exs (top level, unconditional)
bind_address =
case System.get_env("BIND_ADDRESS", "0.0.0.0") do
"0.0.0.0" -> {0, 0, 0, 0}
"::" -> {0, 0, 0, 0, 0, 0, 0, 0}
other -> other |> String.to_charlist() |> :inet.parse_address() |> elem(1)
end
config :<app>, <App>Web.Endpoint, http: [ip: bind_address, port: ...]
WRONG (gates on PORT):
if port = System.get_env("PORT") do
config :<app>, <App>Web.Endpoint, http: [ip: {0, 0, 0, 0}, port: ...]
end
# Without PORT, Phoenix falls back to its default 127.0.0.1 — unreachable.
WRONG (later prod block clobbers env-driven setting):
# Top-level env-driven config OK ...
if config_env() == :prod do
config :<app>, <App>Web.Endpoint, http: [ip: {0, 0, 0, 0, 0, 0, 0, 0}, ...]
end
# IPv6 wildcard binds *:port IPv6 only — IPv4-only overlay networks (Tailscale on macOS) cannot reach it.
Default to IPv4 because most overlay networks route IPv4 first on macOS. Add IPv6 only when the deployment target explicitly requires it.
PHX_HOST matches the public DNS name
Set PHX_HOST to the externally-resolvable hostname the load balancer presents to the browser. LiveView's websocket upgrade matches Origin against PHX_HOST; a mismatch causes the LiveView socket to fail with 403 and the page reverts to a dead static render.
Dev-server restart after lib/**/*.ex changes
Phoenix live reload covers .heex / .html.eex templates and assets/ reliably. It does NOT reliably pick up changes to:
lib/**/*.ex— compiled Elixir modulesmix.exsor any dependency changeconfig/*.exs, especiallyruntime.exs- NIFs, native deps, BEAM-level plugins
- DB migrations that change already-loaded schema
After any of those changes, restart the dev server (kill + relaunch the mise run dev session or equivalent). /api/info-style endpoints report the git_sha at server-start time, NOT the currently-compiled-in-memory code, and cannot distinguish stale-dev from fresh-dev. Restart is the only reliable signal.
Context-Driven Design
Organize business logic into contexts (bounded domains):
Creating Contexts
Generate contexts with related schemas:
mix phx.gen.context Accounts User users email:string name:string
Structure contexts to encapsulate business logic:
defmodule MyApp.Accounts do
@moduledoc """
The Accounts context - manages user accounts and authentication.
"""
alias MyApp.Repo
alias MyApp.Accounts.User
def list_users do
Repo.all(User)
end
def get_user!(id), do: Repo.get!(User, id)
def create_user(attrs \\ %{}) do
%User{}
|> User.changeset(attrs)
|> Repo.insert()
end
def update_user(%User{} = user, attrs) do
user
|> User.changeset(attrs)
|> Repo.update()
end
end
Context Best Practices
- Keep contexts focused on a single domain
- Avoid cross-context dependencies when possible
- Use public API functions, not direct Repo access in web layer
- Name contexts after business domains, not technical layers
LiveView Development
LiveView enables rich, real-time experiences without writing JavaScript.
LiveView Lifecycle
Understand the mount → handle_event → render cycle:
defmodule MyAppWeb.UserLive.Index do
use MyAppWeb, :live_view
alias MyApp.Accounts
@impl true
def mount(_params, _session, socket) do
# Runs on initial page load and live connection
{:ok, assign(socket, :users, list_users())}
end
@impl true
def handle_params(params, _url, socket) do
# Runs after mount and on live patch
{:noreply, apply_action(socket, socket.assigns.live_action, params)}
end
@impl true
def handle_event("delete", %{"id" => id}, socket) do
user = Accounts.get_user!(id)
{:ok, _} = Accounts.delete_user(user)
{:noreply, assign(socket, :users, list_users())}
end
@impl true
def render(assigns) do
~H"""
<div>
<.table rows={@users} id="users">
<:col :let={user} label="Name"><%= user.name %></:col>
<:col :let={user} label="Email"><%= user.email %></:col>
<:action :let={user}>
<.button phx-click="delete" phx-value-id={user.id}>Delete</.button>
</:action>
</.table>
</div>
"""
end
defp list_users do
Accounts.list_users()
end
end
LiveView Best Practices
- Use
mount/3for initial data loading - Handle route changes in
handle_params/3 - Keep renders fast - compute in event handlers, not render
- Use
assign_new/3for expensive computations - Prefer LiveView over JavaScript for interactive UIs
- Use
phx-debounceandphx-throttlefor frequent events
Function Components
Create reusable components:
defmodule MyAppWeb.Components.UserCard do
use Phoenix.Component
attr :user, :map, required: true
attr :class, :string, default: ""
def user_card(assigns) do
~H"""
<div class={"card " <> @class}>
<h3><%= @user.name %></h3>
<p><%= @user.email %></p>
</div>
"""
end
end
Use with <.user_card user={@current_user} /> in templates.
Form Handling
Use changesets for validation:
@impl true
def mount(_params, _session, socket) do
changeset = Accounts.change_user(%User{})
{:ok, assign(socket, form: to_form(changeset))}
end
@impl true
def handle_event("validate", %{"user" => user_params}, socket) do
changeset =
%User{}
|> Accounts.change_user(user_params)
|> Map.put(:action, :validate)
{:noreply, assign(socket, form: to_form(changeset))}
end
@impl true
def handle_event("save", %{"user" => user_params}, socket) do
case Accounts.create_user(user_params) do
{:ok, user} ->
{:noreply,
socket
|> put_flash(:info, "User created successfully")
|> push_navigate(to: ~p"/users/#{user}")}
{:error, %Ecto.Changeset{} = changeset} ->
{:noreply, assign(socket, form: to_form(changeset))}
end
end
def render(assigns) do
~H"""
<.form for={@form} phx-change="validate" phx-submit="save">
<.input field={@form[:name]} label="Name" />
<.input field={@form[:email]} label="Email" type="email" />
<.button>Save</.button>
</.form>
"""
end
Routing
Route organization (pipelines, scopes) and LiveView routes with live actions: see
references/routing-and-channels.md.
Channels and PubSub
Custom Channels for real-time protocols and Phoenix.PubSub for cross-process broadcasts: see
references/routing-and-channels.md.
Testing Phoenix Applications
Controller Tests
defmodule MyAppWeb.UserControllerTest do
use MyAppWeb.ConnCase, async: true
test "GET /users", %{conn: conn} do
conn = get(conn, ~p"/users")
assert html_response(conn, 200) =~ "Listing Users"
end
end
LiveView Tests
defmodule MyAppWeb.UserLiveTest do
use MyAppWeb.ConnCase
import Phoenix.LiveViewTest
test "displays users", %{conn: conn} do
user = insert(:user)
{:ok, view, html} = live(conn, ~p"/users")
assert html =~ user.name
assert has_element?(view, "#user-#{user.id}")
end
test "creates user", %{conn: conn} do
{:ok, view, _html} = live(conn, ~p"/users/new")
assert view
|> form("#user-form", user: %{name: "Alice", email: "alice@example.com"})
|> render_submit()
assert_patch(view, ~p"/users")
end
end
Channel Tests
defmodule MyAppWeb.RoomChannelTest do
use MyAppWeb.ChannelCase
test "broadcasts are pushed to the client", %{socket: socket} do
{:ok, _, socket} = subscribe_and_join(socket, "room:lobby", %{})
broadcast_from!(socket, "new_msg", %{body: "test"})
assert_broadcast "new_msg", %{body: "test"}
end
end
Common Patterns
Preloading associations, pagination, and handling LiveView file uploads: see
references/common-patterns.md.
Performance Optimization
Database Query Optimization
- Use
preload/2to avoid N+1 queries - Add database indexes for frequently queried fields
- Use
select/3to load only needed fields - Consider using
Repo.stream/2for large datasets
LiveView Performance
- Move expensive computations to
handle_eventor background jobs - Use
assign_new/3for computed values - Implement
handle_continue/2for async operations after mount - Use temporary assigns for large lists:
assign(socket, :items, temporary: true)
Caching
Use Cachex or ETS for caching:
def get_user!(id) do
Cachex.fetch(:users, id, fn ->
{:commit, Repo.get!(User, id)}
end)
end
Security Best Practices
- Always validate and sanitize user input through changesets
- Use CSRF protection (enabled by default)
- Implement rate limiting for APIs
- Use
put_secure_browser_headersplug - Validate file uploads (type, size, content)
- Use prepared statements (Ecto does this automatically)
- Implement proper authentication and authorization
OpenAPI Contract-First
Define the OpenAPI spec for any HTTP API surface BEFORE implementing the controller. Clients (and Tier 2 test authors) generate from the spec; the implementation makes the spec true.
In Elixir, use open_api_spex for spec definitions:
defmodule <App>Web.UserSpec do
alias OpenApiSpex.{Schema, Operation}
@user_schema %Schema{
type: :object,
required: [:id, :email],
properties: %{
id: %Schema{type: :integer},
email: %Schema{type: :string, format: :email}
}
}
end
Wire the spec to the controller via @spec macros and serve it at /api/openapi. Tests assert response shapes against the spec rather than against hand-rolled JSON expectations; client SDKs regenerate from the spec on every spec change.
Tidewave MCP Dev Tools
Tidewave connects AI coding assistants to running Phoenix applications via MCP, exposing runtime introspection tools (Ecto schemas, code execution, docs, logs, SQL queries).
Add to mix.exs: {:tidewave, "~> 0.5", only: :dev}
Add to endpoint.ex before code_reloading?: plug Tidewave (guarded by if Mix.env() == :dev)
Connect Claude Code: claude mcp add --transport http tidewave http://localhost:4000/tidewave/mcp
Tidewave is dev-only — never deploy to production. It only accepts localhost requests by default.
For full setup, MCP tools reference, CLI app, editor configs, LiveView annotations, and troubleshooting, see /elixir:tidewave.
Key Principles
- Context boundaries: Keep business logic in contexts, not controllers/LiveViews
- LiveView first: Prefer LiveView over JavaScript for interactive features
- Changesets for validation: Always validate through Ecto changesets
- Pub/Sub for communication: Use Phoenix.PubSub for cross-process updates
- Test at boundaries: Test contexts, controllers, and LiveViews separately
- Follow conventions: Use Phoenix generators and follow established patterns
Elixir Ports
Ports are Elixir's mechanism for communicating with external OS programs via stdin/stdout. A Port is not a network port — it is a process-like entity that manages an external OS program, forwarding messages as bytes and delivering responses back to the owning Elixir process.
Port Fundamentals
Open a port with Port.open/2. The most common name forms are {:spawn, command} and {:spawn_executable, path}.
# Spawn by shell command string (uses shell, PATH lookups apply)
port = Port.open({:spawn, "cat"}, [:binary])
# Spawn executable directly (no shell, preferred for security)
port = Port.open({:spawn_executable, "/usr/bin/python3"}, [
:binary,
args: ["-u", "my_script.py"]
])
Send data to the port and receive from it:
# Send bytes to the external process's stdin
Port.command(port, "hello\n")
# Receive response — messages arrive in the process mailbox
receive do
{^port, {:data, data}} ->
IO.puts("Got: #{data}")
end
Close the port explicitly or let it close when the owner process exits:
Port.close(port)
# The port will reply {port, :closed} after the external process exits
Port Options Reference
| Option | Description |
|---|---|
:binary | Deliver data as binaries (recommended; default is charlists) |
{:packet, N} | Prefix each message with N-byte length header (N = 1, 2, or 4) |
{:line, L} | Deliver complete lines up to L bytes; partial lines flagged |
:stream | No framing — raw bytes delivered as received (default) |
:exit_status | Send {port, {:exit_status, code}} when the program exits |
:use_stdio | Use stdin/stdout for communication (default) |
:stderr_to_stdout | Merge stderr into stdout stream |
{:cd, dir} | Set working directory for the external process |
{:env, env_list} | EXTENDS the spawned process's environment (does NOT replace it) |
{:args, arg_list} | Argument list when using :spawn_executable |
{:arg0, string} | Override argv[0] for the external process |
:parallelism | Hint to scheduler for improved throughput |
Note on {:env, env_list}: This option extends the environment the BEAM already holds — the spawned process inherits every existing variable, and env_list adds to or overrides individual entries. There is no replace-all option. To withhold an inherited variable, pair its name with false (an empty charlist — ~c"" or [] — also unsets; Elixir's "" is a binary and raises). See the Security section.
Communication Patterns
Stream Mode (default)
Bytes are delivered as they arrive with no framing. Use :binary to get binaries instead of charlists.
port = Port.open({:spawn_executable, "/bin/cat"}, [:binary, :stream])
Port.command(port, "some data")
receive do
{^port, {:data, chunk}} -> IO.inspect(chunk)
end
Packet Mode
Use {:packet, N} for message framing. The external program must also implement the same N-byte big-endian length prefix.
# Elixir side
port = Port.open({:spawn_executable, "/usr/local/bin/my_worker"}, [
:binary,
{:packet, 4}
])
Port.command(port, encode_message("hello"))
receive do
{^port, {:data, response}} -> decode_message(response)
end
The external program reads a 4-byte big-endian integer as the message length, then reads that many bytes. It writes responses with the same framing.
Line Mode
port = Port.open({:spawn_executable, "/usr/bin/python3"}, [
:binary,
{:line, 4096},
args: ["script.py"]
])
receive do
{^port, {:data, {:eol, line}}} ->
IO.puts("Complete line: #{line}")
{^port, {:data, {:noeol, partial}}} ->
IO.puts("Partial line (too long): #{partial}")
end
Receiving Exit Status
port = Port.open({:spawn, "false"}, [:binary, :exit_status])
receive do
{^port, {:exit_status, code}} ->
IO.puts("Exited with code #{code}")
end
GenServer Port Wrapper
Wrapping a port in a GenServer is the standard OTP pattern for managing external processes. The GenServer owns the port, handles messages, and exposes a clean API.
defmodule MyApp.ExternalWorker do
use GenServer
@timeout 5_000
# Client API
def start_link(opts \\ []) do
GenServer.start_link(__MODULE__, opts, name: __MODULE__)
end
def call(payload) do
GenServer.call(__MODULE__, {:call, payload}, @timeout)
end
# Server Callbacks
@impl true
def init(_opts) do
executable = System.find_executable("my_worker") ||
raise "my_worker not found in PATH"
port =
Port.open({:spawn_executable, executable}, [
:binary,
{:packet, 4},
:exit_status
])
ref = Port.monitor(port)
{:ok, %{port: port, ref: ref, caller: nil}}
end
@impl true
def handle_call({:call, payload}, from, %{port: port} = state) do
encoded = :erlang.term_to_binary(payload)
Port.command(port, encoded)
{:noreply, %{state | caller: from}}
end
@impl true
def handle_info({port, {:data, data}}, %{port: port, caller: caller} = state) do
response = :erlang.binary_to_term(data)
GenServer.reply(caller, {:ok, response})
{:noreply, %{state | caller: nil}}
end
@impl true
def handle_info({port, {:exit_status, code}}, %{port: port} = state) do
{:stop, {:port_exited, code}, state}
end
@impl true
def handle_info({:DOWN, ref, :port, _port, reason}, %{ref: ref} = state) do
{:stop, {:port_down, reason}, state}
end
@impl true
def terminate(_reason, %{port: port}) do
if Port.info(port) != nil do
Port.close(port)
end
:ok
end
end
Key points in this pattern:
- Store the port in GenServer state
- Monitor the port with
Port.monitor/1to receive:DOWNmessages - Use
{:packet, N}for reliable message framing - Store the calling
frompid when waiting for a response - Reply via
GenServer.reply/2fromhandle_infowhen data arrives - Always check
Port.info(port)before closing interminate/2
Supervision
Add the GenServer to a supervision tree:
children = [
{MyApp.ExternalWorker, []},
# ...
]
Supervisor.start_link(children, strategy: :one_for_one)
When the external process crashes, the port sends an exit message, the GenServer stops, and the supervisor restarts it.
Port Lifecycle and Error Handling
Port Monitor
Use Port.monitor/1 (available since Elixir v1.6) to receive a {:DOWN, ref, :port, object, reason} message when a port closes:
port = Port.open({:spawn, "my_cmd"}, [:binary])
ref = Port.monitor(port)
receive do
{:DOWN, ^ref, :port, _port, reason} ->
IO.puts("Port closed: #{inspect(reason)}")
end
Checking if a Port is Alive
case Port.info(port) do
nil -> :port_closed
info -> {:alive, info}
end
Port Ownership Transfer
Transfer ownership with Port.connect/2. The old owner receives {port, :connected}:
Port.connect(port, new_owner_pid)
Crash Semantics
- When the port owner process terminates, the port closes automatically, and the external program receives SIGTERM.
- When the external program exits, the port sends
{port, {:exit_status, code}}(if:exit_statuswas set) and closes. - Ports are linked to their owning process by default.
Decision Guide: Port vs NIF vs C Node vs System.cmd
| Aspect | Port | NIF | C Node | System.cmd |
|---|---|---|---|---|
| Crash isolation | Yes — OS process | No — crashes the VM | Yes — OS process | Yes — subprocess |
| Latency | IPC overhead | Near zero | Message passing | Blocking, high |
| Complexity | Low–Medium | High | Very high | Very low |
| Scheduler impact | None | Blocks (use dirty NIFs for >1ms) | None | Blocks caller only |
| Security boundary | OS process isolation | Full VM access | OS process isolation | OS process isolation |
| Best for | Long-running, streaming | Sub-millisecond sync calls | Legacy C integration | One-shot commands |
Use Port when: the external program runs continuously, streams data, or must be isolated from VM crashes.
Use System.cmd/3 when: running a command once, synchronously, and the result is needed before proceeding. Returns {output, exit_status}.
Use NIF when: calling a C function with sub-millisecond latency requirements. Use dirty NIFs (ERL_NIF_DIRTY_JOB_CPU_BOUND or ERL_NIF_DIRTY_JOB_IO_BOUND) for work exceeding ~1ms to avoid blocking schedulers.
Use C Node when: integrating with an existing large C codebase that uses erl_interface/ei.
System.cmd Example
{output, 0} = System.cmd("ls", ["-la", "/tmp"],
cd: "/",
stderr_to_stdout: true
)
System.cmd/3 blocks the calling process until the command completes. It does not stream data.
Security Considerations
Prefer :spawn_executable Over :spawn
{:spawn, command} passes the command through a shell, which enables shell injection:
# UNSAFE — shell injection risk
user_input = "file.txt; rm -rf /"
Port.open({:spawn, "cat #{user_input}"}, [:binary])
# SAFE — no shell, arguments passed directly
Port.open({:spawn_executable, "/bin/cat"}, [
:binary,
args: [user_input]
])
Always use {:spawn_executable, path} with args: when any part of the command comes from user input or external data.
Validate Executable Paths
# Find and validate the executable at startup, not per-request
executable = System.find_executable("my_tool") ||
raise "my_tool executable not found in PATH"
Store the validated path in process state so it is resolved once at startup.
Environment Variable Inheritance
{:env, env_list} extends the spawned process's environment — it does not replace it. OTP documents this directly: "The environment of the started process is extended using the environment specifications in Env." The child therefore inherits every variable the BEAM holds, including any secrets in it, whether or not they appear in env_list.
The security consequence is the part that is easy to get backwards: passing a short env_list does not sandbox the child. There is no replace-all option, so a variable is only withheld if you name it and pair it with false. The OTP 27 and 28 docs also treat an empty Erlang string as unset, "just as if os:unsetenv/1 had been called" — so an empty value cannot be passed through to a child at all. From Elixir that means ~c"" or []; the Elixir literal "" is a binary and raises ArgumentError.
Do not build a "clean" environment by enumerating System.get_env/0 and passing it back in — the child already has those variables, so it withholds nothing, and it copies every secret value into a BEAM term where it can surface in crash dumps, :sys.get_state/1, exception messages, and any stray IO.inspect/1.
See references/erlang-ports.md for a deny example and a minimal allowlist helper.
Note: Name and Val must be Erlang strings (charlists). Binaries raise ArgumentError — unlike :cd, :args, and :arg0, whose typespecs explicitly allow binary(), the :env typespec does not. Convert with String.to_charlist/1. System.cmd/3 differs: it accepts binaries and takes nil (not false) as its unset marker, converting both before reaching the port.
Windows Batch File Injection
On Windows, spawning .bat or .cmd files via :spawn passes through cmd.exe, which has its own injection vectors. Use explicit executable paths and validate all arguments.
Testing Port-Based Code
Mock the Port Interaction
Test the GenServer wrapper by sending fake port messages directly:
defmodule MyApp.ExternalWorkerTest do
use ExUnit.Case, async: true
test "call sends to port and returns response" do
{:ok, pid} = MyApp.ExternalWorker.start_link([])
# Retrieve the port from state for inspection
%{port: port} = :sys.get_state(pid)
# Simulate the port sending a response
fake_response = :erlang.term_to_binary({:ok, "result"})
send(pid, {port, {:data, fake_response}})
# Verify state updated (caller cleared)
%{caller: nil} = :sys.get_state(pid)
end
test "handles port exit" do
{:ok, pid} = MyApp.ExternalWorker.start_link([])
ref = Process.monitor(pid)
%{port: port} = :sys.get_state(pid)
send(pid, {port, {:exit_status, 1}})
assert_receive {:DOWN, ^ref, :process, ^pid, {:port_exited, 1}}
end
end
Integration Test with a Real Port
For integration tests, use a real external program:
test "communicates with cat process" do
port = Port.open({:spawn_executable, "/bin/cat"}, [:binary, :stream])
Port.command(port, "hello")
assert_receive {^port, {:data, "hello"}}, 1_000
Port.close(port)
end
Use assert_receive with a timeout rather than bare receive in tests to avoid hanging on failure.
Common Pitfalls
Orphan processes on VM crash: If the BEAM VM is killed with SIGKILL (not SIGTERM), external port processes may not receive SIGTERM and can persist. Design external programs to detect closed stdin and exit.
Charlists vs binaries: Without :binary, data arrives as charlists (lists of integers). Always use :binary unless working with legacy code that expects charlists.
Assuming {:env, list} sandboxes the child: it extends the environment rather than replacing it, so the spawned process inherits everything the BEAM holds no matter how short the list is. Withholding a variable requires naming it explicitly with false. See the Security section.
Blocking the GenServer: A GenServer that sends a command and awaits a reply synchronously in handle_call will block the entire GenServer during the wait. The pattern above avoids this by storing the from and replying in handle_info.
Not monitoring the port: Without Port.monitor/1 or :exit_status, a silently exiting external process leaves the GenServer in a state where it will never receive a reply.
Packet mode mismatch: If the Elixir side uses {:packet, 4} but the external program uses a different framing, all messages will be corrupted or silently dropped. Verify the framing protocol matches on both sides.
References
See references/erlang-ports.md for:
- Complete
open_port/2Erlang option reference - Binary protocol wire format and byte calculations
erl_interface/eiC library overview- Port driver architecture (linked-in drivers)
- ERTS scheduling and backpressure options
Anti-Fabrication
Verify all port behavior claims through tool execution. Use Port.info/1 to confirm port state before asserting properties. Run actual port commands and check exit statuses rather than assuming behavior. Reference core:anti-fabrication for the complete validation methodology.
Key Principles
- Use
:spawn_executable: Avoid shell injection by passing arguments directly - Wrap ports in GenServer: Follow OTP patterns for lifecycle management and supervision
- Monitor the port: Use
Port.monitor/1to detect unexpected port closure - Use
{:packet, N}for framing: Stream mode requires external framing logic - Design for orphan processes: External programs should detect stdin closure and exit
- Test with
assert_receive: Avoid barereceivein tests to prevent hangs - Prefer Port over NIF for isolation: NIF crashes bring down the entire VM
Elixir Style and Conventions
This skill complements elixir:anti-patterns — that skill covers what to avoid; this one covers what to do instead.
Tagged Tuples and Return Conventions
Elixir functions signal success or failure through return values, not exceptions.
Standard return shapes:
# Two-element ok/error tuples (most common)
{:ok, result}
{:error, reason}
# Bare atoms for side-effect operations
:ok
:error
# Richer error tuples for typed failures
{:error, :not_found}
{:error, :unauthorized}
{:error, %Ecto.Changeset{}}
Why this convention matters:
Pattern matching on tagged tuples is the foundation of Elixir error handling. When every function in a call chain returns {:ok, _} or {:error, _}, with expressions can thread success values through and exit early on the first failure — without nested if or try/rescue.
# Callers can match exhaustively
case fetch_user(id) do
{:ok, user} -> render_profile(user)
{:error, :not_found} -> send_resp(conn, 404, "Not found")
{:error, reason} -> send_resp(conn, 500, inspect(reason))
end
Logger over IO.puts
All application output goes through Logger. Do NOT use IO.puts/1, IO.write/1, or :io.format/2 from application code. Logger respects log levels, supports metadata, and routes through the configured backends (console, file, structured log shippers). IO.puts writes directly to stdout regardless of log level and bypasses backend configuration.
# WRONG — IO.puts("worker started")
# CORRECT
Logger.info("worker started")
Logger.info("worker started", worker_id: id, module: __MODULE__)
Flush concerns at shutdown go through Logger configuration (Logger.flush/0 in an at_exit, or the :logger_std_h flush settings), not by bypassing Logger to write directly. The only legitimate use of IO in app code is reading from / writing to a specific IO device the user requested (e.g., a CLI tool's stdout output, where the OUTPUT IS the contract).
Bang Functions: When to Avoid
The Convention
Every standard library function with a ! variant follows this contract:
| Non-bang | Bang |
|---|---|
File.read/1 → {:ok, content} or {:error, reason} | File.read!/1 → content or raises |
Map.fetch/2 → {:ok, value} or :error | Map.fetch!/2 → value or raises KeyError |
Repo.insert/1 → {:ok, struct} or {:error, changeset} | Repo.insert!/1 → struct or raises |
Repo.get/2 → struct or nil | Repo.get!/2 → struct or raises Ecto.NoResultsError |
When Bangs Are Appropriate
Use bang functions when failure represents a programming error or an invalid system state that should crash loudly:
# Application startup — missing config is a bug, not a user error
def start(_type, _args) do
api_key = Application.fetch_env!(:my_app, :stripe_api_key)
# ...
end
# Seeds and migrations — invalid data is a developer error
Repo.insert!(%User{email: "admin@example.com", role: :admin})
# Pipelines operating on already-validated, known-good data
"hello world"
|> String.split()
|> Enum.map(&String.capitalize/1)
|> Enum.join(" ")
# Tests asserting expected state
user = Repo.get!(User, user_id)
When to Avoid Bangs
Avoid bang functions wherever failure is a normal, expected outcome:
# BAD: user input can always fail validation
def create_user(conn, %{"user" => params}) do
user = Repo.insert!(%User{email: params["email"]}) # raises on validation failure
json(conn, %{id: user.id})
end
# GOOD: handle the error path explicitly
def create_user(conn, %{"user" => params}) do
case %User{} |> User.changeset(params) |> Repo.insert() do
{:ok, user} -> json(conn, %{id: user.id})
{:error, changeset} -> conn |> put_status(422) |> json(changeset_errors(changeset))
end
end
# BAD: external APIs can return 404, 500, network errors
def fetch_payment(payment_id) do
Stripe.PaymentIntent.retrieve!(payment_id) # raises on API error
end
# GOOD: return a tagged tuple, let the caller decide
def fetch_payment(payment_id) do
case Stripe.PaymentIntent.retrieve(payment_id) do
{:ok, payment} -> {:ok, payment}
{:error, %{code: "resource_missing"}} -> {:error, :not_found}
{:error, reason} -> {:error, reason}
end
end
Rule of thumb: if a user action, external service, or DB constraint could cause the failure, use the non-bang variant and handle it.
Pattern Matching for Error Handling
with for Chaining Dependent Operations
Use with when multiple steps must all succeed, and any failure should short-circuit to an error response:
def register_user(params) do
with {:ok, validated} <- validate_registration_params(params),
{:ok, user} <- create_user(validated),
{:ok, _profile} <- create_default_profile(user),
{:ok, _email} <- send_welcome_email(user) do
{:ok, user}
else
{:error, %Ecto.Changeset{} = cs} -> {:error, {:validation_failed, cs}}
{:error, :email_unavailable} -> {:error, :email_taken}
{:error, reason} -> {:error, reason}
end
end
The else block is optional. Without it, unmatched patterns in with clauses propagate the first failing value as the return value of the entire expression.
Keep with flat. Nesting with inside with is a sign the function is doing too much:
# BAD: nested with — hard to follow
with {:ok, user} <- fetch_user(id) do
with {:ok, order} <- fetch_order(user, order_id) do
{:ok, {user, order}}
end
end
# GOOD: flat with
with {:ok, user} <- fetch_user(id),
{:ok, order} <- fetch_order(user, order_id) do
{:ok, {user, order}}
end
case for Single-Expression Branching
Use case when branching on one expression with multiple outcomes:
def handle_webhook(event_type, payload) do
case event_type do
"payment.succeeded" -> handle_payment_succeeded(payload)
"payment.failed" -> handle_payment_failed(payload)
"customer.created" -> handle_customer_created(payload)
unknown -> Logger.warning("Unhandled webhook: #{unknown}")
end
end
Multi-Clause Function Heads
Use multi-clause functions for structural dispatch — matching on the shape or value of arguments:
defmodule MyApp.Notifier do
def notify(%User{email: nil} = user, _message) do
Logger.warning("No email for user #{user.id}, skipping notification")
{:error, :no_email}
end
def notify(%User{} = user, message) do
Mailer.deliver(to: user.email, body: message)
end
def notify({:admin, email}, message) do
Mailer.deliver(to: email, subject: "[ADMIN] " <> message.subject, body: message)
end
end
Avoid try/rescue for Expected Errors
try/rescue is reserved for exceptions from code outside your control (third-party libraries that raise instead of returning error tuples). It is not idiomatic for expected application errors:
# BAD: using rescue for control flow
def parse_integer(str) do
try do
{:ok, String.to_integer(str)}
rescue
ArgumentError -> {:error, :invalid_integer}
end
end
# GOOD: use functions that return ok/error tuples
def parse_integer(str) do
case Integer.parse(str) do
{value, ""} -> {:ok, value}
_ -> {:error, :invalid_integer}
end
end
Ecto as Data Shape Gatekeeper
Validate data once, at the changeset layer — schema defines shape, changeset validates, the
context/controller route on {:ok, _} / {:error, changeset}, and the form template renders
changeset errors directly. Includes the duplicated-validation anti-pattern and cast vs
change. This is the duplicated surface the dedicated /elixir:ecto skill already owns in
depth; see references/ecto-data-shapes.md.
Embedded Schemas for Non-DB Data
Non-DB data (search forms, filter panels, API query params) still gets full changeset
validation via embedded_schema or a schemaless changeset — a continuation of the gatekeeper
principle above: see references/ecto-data-shapes.md.
Pipe Operator Conventions
When to Pipe
Pipe when chaining data transformations where each step passes its result to the next:
# Good use of pipe: transforming a value through a sequence of steps
def normalize_email(email) do
email
|> String.trim()
|> String.downcase()
|> String.replace(~r/\+.*@/, "@")
end
When Not to Pipe
Avoid piping a single function call — it adds visual noise without clarity benefit:
# BAD: unnecessary pipe
result = value |> some_function()
# GOOD: direct call
result = some_function(value)
Avoid piping side effects that don't transform data:
# BAD: pipe into a side effect
user |> send_welcome_email()
# GOOD: explicit call
send_welcome_email(user)
Map and Struct Access
Elixir provides two access patterns with different semantics:
# Dot access — raises KeyError if key missing
# Use for required fields on known structs
user.email # raises if :email key not present
config.timeout # use when the field must exist
# Bracket access — returns nil if key missing
# Use for optional fields on dynamic maps
params[:email] # returns nil if missing, no crash
opts[:timeout] # safe for optional config keys
Struct fields always use dot access — structs enforce their shape at compile time, so a missing key is a programming error:
# Always use dot access for structs
%User{} = user
user.email # correct
user[:email] # valid but unusual — prefer dot for structs
Dynamic maps from external sources use bracket access for optional fields:
def build_query(filters) do
base_query = from(u in User)
base_query
|> maybe_filter_role(filters[:role])
|> maybe_filter_after(filters[:created_after])
end
Anti-Fabrication
Apply core:anti-fabrication when generating code examples or making claims about library behavior. Verify function signatures and return types against actual documentation. Do not fabricate error codes, changeset validator names, or Ecto API details.
Key Principles
- Return
{:ok, result}/{:error, reason}tuples to enable exhaustive pattern matching - Use bang functions only when failure indicates a programming error or invalid system state
- Use
withfor multi-step operations where each step depends on the previous - Let the Ecto changeset own all data validation — do not duplicate it in controllers or LiveView
- Use
embedded_schemaor schemaless changesets for non-DB data that still needs validation - Pipe for transformation chains; call directly for single operations and side effects
- Reserve
try/rescuefor third-party code that raises; use tagged tuples for your own error paths
Elixir Testing with ExUnit
This skill activates when writing, organizing, or improving tests for Elixir applications using ExUnit and related testing tools.
ExUnit Basics
Test Module Structure
defmodule MyApp.MathTest do
use ExUnit.Case, async: true
describe "add/2" do
test "adds two positive numbers" do
assert Math.add(2, 3) == 5
end
test "adds negative numbers" do
assert Math.add(-1, -1) == -2
end
test "adds zero" do
assert Math.add(5, 0) == 5
end
end
describe "divide/2" do
test "divides two numbers" do
assert Math.divide(10, 2) == 5.0
end
test "returns error for division by zero" do
assert Math.divide(10, 0) == {:error, :division_by_zero}
end
end
end
Assertion patterns and the full setup/setup_all/conditional-setup catalog live in references/exunit-reference.md.
Test Organization
Using describe blocks
Group related tests:
defmodule MyApp.UserTest do
use ExUnit.Case
describe "create_user/1" do
test "creates user with valid attributes" do
# ...
end
test "returns error with invalid email" do
# ...
end
end
describe "update_user/2" do
test "updates user attributes" do
# ...
end
end
end
Test tags
Categorize and filter tests:
@moduletag :integration
@tag :slow
test "expensive operation" do
# ...
end
@tag :external
test "calls external API" do
# ...
end
# Run only tagged tests
# mix test --only slow
# mix test --exclude external
Setup and teardown forms (setup, setup_all, describe-scoped setup, conditional setup) live in references/exunit-reference.md. Every setup that starts an owned resource or mutates shared state pairs it with on_exit(fn -> ... end) to restore it — the mechanism behind this workspace's binding test-isolation rules (restore Application.put_env, clean up Process.put keys, remove temp dirs).
Database Testing
Sandbox Mode
Configure for concurrent tests:
# config/test.exs
config :my_app, MyApp.Repo,
pool: Ecto.Adapters.SQL.Sandbox
# test/test_helper.exs
Ecto.Adapters.SQL.Sandbox.mode(MyApp.Repo, :manual)
# test/support/data_case.ex
defmodule MyApp.DataCase do
use ExUnit.CaseTemplate
using do
quote do
alias MyApp.Repo
import Ecto
import Ecto.Changeset
import Ecto.Query
import MyApp.DataCase
end
end
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
end
Test factories (ExMachina) and changeset test patterns live in references/database-testing.md.
Phoenix Testing
Controller, LiveView, and Channel test examples live in references/phoenix-testing.md.
Mocking and Stubbing
Using Mox
Define behaviors and mocks:
# Define behaviour
defmodule MyApp.HTTPClient do
@callback get(String.t()) :: {:ok, map()} | {:error, term()}
end
# In config/test.exs
config :my_app, :http_client, MyApp.HTTPClientMock
# In test/test_helper.exs
Mox.defmock(MyApp.HTTPClientMock, for: MyApp.HTTPClient)
# In application code
defmodule MyApp.UserFetcher do
@http_client Application.compile_env(:my_app, :http_client)
def fetch_user(id) do
@http_client.get("/users/#{id}")
end
end
# In tests
defmodule MyApp.UserFetcherTest do
use ExUnit.Case, async: true
import Mox
setup :verify_on_exit!
test "fetches user successfully" do
expect(MyApp.HTTPClientMock, :get, fn "/users/1" ->
{:ok, %{"name" => "Alice"}}
end)
assert {:ok, %{"name" => "Alice"}} = MyApp.UserFetcher.fetch_user(1)
end
test "handles error" do
expect(MyApp.HTTPClientMock, :get, fn _ ->
{:error, :network_error}
end)
assert {:error, :network_error} = MyApp.UserFetcher.fetch_user(1)
end
end
Stubbing Multiple Calls
test "calls API multiple times" do
MyApp.HTTPClientMock
|> expect(:get, 3, fn url ->
{:ok, %{"url" => url}}
end)
MyApp.batch_fetch([1, 2, 3])
end
Global Stubs
setup do
stub(MyApp.HTTPClientMock, :get, fn _ -> {:ok, %{}} end)
:ok
end
test "can override stub" do
expect(MyApp.HTTPClientMock, :get, fn _ ->
{:error, :timeout}
end)
# ...
end
Property-Based Testing
Property-based tests with StreamData, including custom generators, live in references/property-based-testing.md.
Testing Async and Concurrent Code
Testing Processes
test "GenServer handles messages" do
{:ok, pid} = MyApp.Worker.start_link()
MyApp.Worker.process(pid, :work)
assert_receive {:done, :work}, 1000
end
Testing Tasks
test "async task completes" do
parent = self()
Task.start(fn ->
result = expensive_computation()
send(parent, {:result, result})
end)
assert_receive {:result, value}, 5000
assert value == expected
end
Testing Race Conditions
test "concurrent updates are handled correctly" do
{:ok, counter} = Counter.start_link(0)
tasks = for _ <- 1..100 do
Task.async(fn -> Counter.increment(counter) end)
end
Task.await_many(tasks)
assert Counter.get(counter) == 100
end
Test Coverage
Generating coverage reports and configuring thresholds lives in references/exunit-reference.md.
Best Practices
Test Organization
- One test file per module:
lib/my_app/user.ex→test/my_app/user_test.exs - Use
describeblocks to group related tests - Use
test/supportfor shared test helpers - Keep tests focused on one behavior per test
Naming
- Use descriptive test names that explain what is being tested
- Start with the action being tested
- Include the expected outcome
# Good
test "create_user/1 returns error with invalid email"
test "add/2 returns sum of two positive integers"
# Avoid
test "it works"
test "test1"
Setup
- Use
setupfor common test data - Keep setup focused - don't create unnecessary data
- Use context to pass data between setup and tests
- Use factories for complex data structures
Assertions
- Prefer pattern matching over multiple assertions
- Use specific assertions (
assert_receivevsassert Process.info(...)) - Test one logical assertion per test when possible
Async Tests
# Mark tests as async when they don't share state
use ExUnit.Case, async: true
# A test that touches shared state (global config, a shared key, the
# filesystem) is not automatically an async: false candidate — isolate
# the state first (see Test Isolation below); reach for async: false
# only when isolation genuinely is not possible, e.g. real unsandboxed
# database access.
Test Data
- Use factories (ExMachina) for consistent test data
- Avoid hardcoded IDs - use factories and references
- Keep test data minimal - only what's needed for the test
- Use descriptive data that makes tests readable
External Dependencies
- Mock external APIs and services
- Use Mox for behavior-based mocking
- Stub at the boundary - don't mock internal modules
- Tag tests that require external services
Test Isolation
Non-deterministic test failures (SQLite "database busy", env-dependent, fails-locally-passes-in-CI) are broken test isolation, not runtime flakiness. Default diagnosis: shared mutable state leaking across tests, not the runtime being unreliable.
- Every test that mutates
Application.put_env/3saves and restores it insetup+on_exit. - Every test that uses
Process.put/2on a shared key cleans up inon_exit. - Every test that writes files uses a unique temp dir (
System.unique_integer([:positive])) and removes it viaon_exit. async: falseis a LAST RESORT, with a comment naming the shared state that forces it.- The determinism check varies the CONCURRENCY SHAPE, not the repetition count: run the suite normally, then again at a 2-vCPU CI runner's shape via
mix test --max-cases 4. Repeating identical runs samples the same shape N times and proves nothing. - Never rerun CI to turn a failure green. A remote-only failure is a reproduction recipe: reproduce locally at the runner's concurrency shape, fix the isolation bug, push the fix.
Debugging Tests
Running Specific Tests
# Run single test file
mix test test/my_app/user_test.exs
# Run specific line
mix test test/my_app/user_test.exs:42
# Run tests matching pattern
mix test --only integration
# Run tests excluding pattern
mix test --exclude slow
Test Output
# Add IEx.pry breakpoint
import IEx
test "debugging" do
user = build(:user)
IEx.pry() # Stops here
# ...
end
# Print during tests
IO.inspect(value, label: "DEBUG")
Failed Test Debugging
# Re-run only failed tests
mix test --failed
# Show detailed error traces
mix test --trace
# Run tests one at a time
mix test --max-cases 1
Key Principles
- Test behavior, not implementation: Test what the code does, not how it does it
- Keep tests fast: Use async tests, avoid unnecessary setup, mock slow dependencies
- Make tests readable: Use descriptive names, clear assertions, minimal setup
- Test at the right level: Unit tests for logic, integration tests for interactions
- Use factories: Consistent, reusable test data with ExMachina
- Mock at boundaries: Mock external services, not internal modules
- Property-based testing: Use StreamData for algorithmic code
- Embrace the database: Use Ecto sandbox for fast, isolated database tests
References
references/exunit-reference.md— Assertion patterns, setup/teardown forms, and coverage toolingreferences/database-testing.md— Test factories (ExMachina) and changeset test patternsreferences/phoenix-testing.md— Controller, LiveView, and Channel test examplesreferences/property-based-testing.md— StreamData property tests and custom generatorsreferences/os-subprocess-adapter.md— Elixir @callback + Mox shape for wrappingSystem.cmd/Port.opencalls behind a mockable seam; config wiring per environmentreferences/elixir-tdd-discipline.md— Elixir-specific TDD defaults:@cmd_modcompile-time seam,async: trueeverywhere, mock external boundaries (HTTP / OS / time / third-party APIs), no:integrationtags, no log noise, no error-swallowingelse _ -> :ok
Tidewave MCP Dev Tools
Tidewave is a dev tool by Dashbit that connects AI coding assistants to running Phoenix applications via the Model Context Protocol (MCP). It exposes runtime introspection tools: Ecto schemas, code execution, documentation lookup, log inspection, and SQL queries.
Current version: ~> 0.5 (v0.5.6 released 2026-03-13 — adds :extra_apps plug option)
When connected, prefer MCP tools over web fetches
When Tidewave MCP is connected to an Elixir/Phoenix project, route documentation, source, and runtime queries through the MCP tools — not WebFetch or hexdocs.pm.
get_docsinstead of WebFetch onhexdocs.pm/<package>/<Module>.htmlsearch_package_docsinstead of broader hex-doc searchesget_source_locationinstead of readingdeps/<package>/lib/...with Readexecute_sql_queryinstead of shelling intopsqlproject_evalinstead of runningiex -S mixsnippets
Why: MCP tool calls return results pinned to the exact versions in the project's mix.lock, complete in a single round-trip, and skip HTML→markdown conversion and page chrome — significantly fewer tokens per lookup than WebFetch, and the answer is guaranteed to match the running app rather than whatever version is on hexdocs.pm today.
Using tidewave in tier prompts
When a worker in a staged pipeline interacts with unfamiliar dependencies, the lead's prompt to that worker MUST explicitly direct the worker to verify dep APIs via tidewave MCP tools before stubbing or implementing.
Add this block to Tier 2 (test author) and Tier 3 (implementer) prompts when the work touches a dep not already exercised in the codebase:
## Module docs via tidewave (PREFERRED over WebFetch or guessing)
For unfamiliar deps, verify the actual API surface via tidewave MCP before stubbing or implementing:
- `mcp__tidewave-<app>__search_package_docs` (q: "<ModuleName>") — keyword search across installed package docs
- `mcp__tidewave-<app>__get_docs` (module: "<Module>", function: "<func>") — full docstrings for a specific function
Particularly important for: <list the specific deps this tier touches>.
Tidewave hits the running BEAM's loaded modules — it returns what is ACTUALLY in the dep, not what the model remembers from training data. Guessing produces code that does not compile or behaves wrong; tidewave produces code matching the real API surface.
The lead lists the SPECIFIC dep names in the prompt — abstract "use tidewave" instructions are ignored. Naming the dep (Cloak, Slipstream, Phoenix.Token, Mox, etc.) and the exact MCP tool names triggers the worker to call them.
This applies whenever a tier worker touches a dependency that:
- Is new to the codebase (not already imported / used in
lib/). - Has changed API across a recent major version.
- The worker would otherwise stub from training-data memory.
Installation
New Projects (via Igniter)
mix archive.install hex igniter_new
mix igniter.install tidewave
Existing Projects (Manual)
- Add to
mix.exs:
defp deps do
[
{:tidewave, "~> 0.5", only: :dev}
]
end
- Add plug to
lib/my_app_web/endpoint.exbefore thecode_reloading?block:
if Mix.env() == :dev do
plug Tidewave
end
if code_reloading? do
# ...existing code reload plugs...
end
- Fetch dependencies:
mix deps.get
Umbrella Projects
Apply the manual steps to the application defining the Phoenix endpoint (typically apps/your_app_web).
MCP Server Configuration
Tidewave exposes an MCP server at /tidewave/mcp on the Phoenix app's port. The transport type is HTTP (streamable) — SSE was removed in v0.4.0. Tidewave is unauthenticated; decline any "Authenticate" prompt the editor offers.
Default URL: http://localhost:4000/tidewave/mcp
See references/mcp-setup.md for verbatim setup commands and JSON config for Claude Code, Codex CLI, Gemini CLI, and opencode, an unverified Cursor/VS Code/Zed config table, plus a curl ping for raw verification and a troubleshooting table.
MCP Tools Reference
| Tool | Description |
|---|---|
project_eval | Execute Elixir code within the running application runtime |
execute_sql_query | Run SQL queries against the application database |
get_ecto_schemas | List all Ecto schema modules with their fields and associations |
get_ash_resources | List all Ash resources (when using the Ash framework) |
get_docs | Retrieve documentation for modules/functions using exact project versions |
search_package_docs | Query hexdocs.pm filtered to project dependencies (availability varies by framework) |
get_source_location | Find module/function source code file paths and line numbers |
get_models | List all application modules with their file locations |
get_logs | Access server logs; supports log level filtering (added v0.5.5) |
Note: search_package_docs may not be available in all frameworks. Verify availability for your setup.
Usage Patterns
See "When connected, prefer MCP tools over web fetches" at the top of this skill for the routing rule.
Introspect schemas before writing queries:
get_ecto_schemas → discover schema structure → execute_sql_query
Look up documentation for project dependencies:
get_docs for specific modules, search_package_docs for broader hex dependency searches
Execute and test code in the running app:
project_eval → run Elixir expressions against live application state
Plug Configuration Options
if Mix.env() == :dev do
plug Tidewave,
allow_remote_access: false,
inspect_opts: [pretty: true, limit: 50]
end
| Option | Default | Description |
|---|---|---|
allow_remote_access | false | Allow connections from non-localhost |
inspect_opts | [] | Options passed to Kernel.inspect/2 for output formatting |
team | nil | Team configuration (e.g., [id: "my-company"]) |
extra_apps | [] | Additional OTP apps to include in source/module discovery (v0.5.6+) |
CLI App (Standalone MCP Server)
The Tidewave desktop/CLI app (tidewave_app) runs a standalone MCP server without requiring a Phoenix application. Useful for containers, remote dev environments, or non-Phoenix Elixir projects.
- Default server:
http://localhost:9832 - Only allows access from the same machine by default
Installation
- Desktop app (macOS, Windows, Linux): https://tidewave.ai/install
- Development CLI:
cargo run -p tidewave-cli [-- --help]
When to Use CLI vs Phoenix Plug
| Scenario | Use |
|---|---|
| Phoenix application | plug Tidewave in endpoint.ex |
| Container/remote dev | CLI app or plug with allow_remote_access: true |
| Non-Phoenix Elixir | CLI app |
| Standalone MCP server | CLI app on port 9832 |
LiveView Debug Annotations
Enable in config/dev.exs to help Tidewave map rendered HTML back to source HEEx templates:
config :phoenix_live_view,
debug_heex_annotations: true
config :phoenix,
debug_attributes: true
Requires Phoenix LiveView v1.1+.
Security
- Dev-only: Always guard with
Mix.env() == :devoronly: :devin deps - Localhost-only: Tidewave only accepts localhost requests by default
- No production use: Tidewave exposes code execution and database access — never deploy to production
- Docker/remote dev: Set
allow_remote_access: trueonly on trusted networks - CSP: Tidewave injects
unsafe-evalinscript-srcdirectives and disablesframe-ancestorsrestrictions
Troubleshooting
MCP connection fails
- Verify Phoenix server is running:
mix phx.server - Check the port matches your configuration (default 4000)
- Try
http://127.0.0.1:4000/tidewave/mcpif IPv6 causes issues
Tools not appearing
- Confirm
plug Tidewaveis placed beforeif code_reloading?inendpoint.ex - Restart the Phoenix server after adding the plug
- Verify the dependency is installed:
mix deps.get
Claude Code authentication error
- Run
claudein your terminal and confirm authentication - Verify CLI availability:
which claude
Umbrella project issues
- Add the plug only in the endpoint of the web application
- Ensure
:tidewaveis added to the correctmix.exsin the umbrella
Agents 1
You are a Phoenix runtime introspection agent. Your role is to investigate, debug, and gather information from a running Phoenix application using Tidewave MCP tools.
Workflow
- Discover: Use
get_ecto_schemasorget_modelsto understand application structure - Locate: Use
get_source_locationto find module/function source paths - Inspect: Use
get_docsorsearch_package_docsfor documentation lookup - Evaluate: Use
project_evalto execute Elixir code in the running app - Query: Use
execute_sql_queryto inspect database state - Debug: Use
get_logsto review server output (supports log level filtering) - Cross-reference: Use Read, Glob, Grep to examine source code alongside runtime state
Guidelines
- Runtime-first: Prefer Tidewave tools over static code analysis when the app is running
- Non-destructive: Use read-only queries and safe evaluations by default
- Contextual: Combine runtime introspection with source code reading for full picture
- Specific: Report exact module names, schema fields, and query results
- Concise: Summarize findings with relevant data, not verbose explanations
Tool Selection
| Need | Tool | Notes |
|---|---|---|
| List schemas and fields | get_ecto_schemas | Phoenix-specific |
| List Ash resources | get_ash_resources | Ash framework only |
| Find module source file | get_source_location | |
| List all modules | get_models | |
| Read module/function docs | get_docs | Uses project dependency versions |
| Search hex dependency docs | search_package_docs | May not be available in all frameworks |
| Run Elixir code in app | project_eval | |
| Run SQL against database | execute_sql_query | |
| Check server logs | get_logs | Supports log level filtering (added v0.5.5) |
| Read source files | Read, Glob, Grep |
Sponsors
Details
- Marketplace
- vinnie357/claude-skills
- Source
- plugins/languages/elixir
- Category
- Language
- Keywords
- elixir, phoenix, otp, ports, ecto, style, beam, erlang
More from vinnie357/claude-skills
All 33- extras-claude-codev0.3.1
- githubv0.3.17
- graphifyv0.1.4
- linearv0.1.10
- playwrightv0.1.3
- pmv0.1.6
- proxmoxv0.1.1
- qav0.1.7
- rigv0.1.2
- runexv0.1.11
- rustv0.1.13
- sbxv0.1.3
- slidevv0.2.11
- tweagv0.1.5
- typescriptv0.1.1
- uiv0.1.7
- valev0.1.0
- wasmv0.1.11
- whammv0.1.4
- zigv0.1.11
- agent-sandboxingv0.2.15
- all-skillsv0.4.187
- alliumv0.1.3
- altanav0.1.3