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@vinnie357

Run it inside Claude Code after adding the marketplace with /plugin marketplace add vinnie357/claude-skills.

Contents

Discovered from source

Skills 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 @doc and @moduledoc for 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 else blocks 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 with focus 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/1 with 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/1 with 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, not for 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:

  1. Scan for anti-patterns - Check code against the patterns listed above
  2. Explain the problem - Help the developer understand why it's an issue
  3. Suggest refactoring - Provide concrete, idiomatic alternatives
  4. Consider context - Sometimes anti-patterns are acceptable for specific use cases
  5. 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 (not use Mix.Config)
  • Can use config_env() and config_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_env and System.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

FunctionDescriptionWhere to Use
config/2Configure app with keyword listAll config files
config/3Configure app key with valueAll config files
config_env/0Get current environment (:dev, :test, :prod)All config files
config_target/0Get build targetAll config files
import_config/1Import other config filesNot in runtime.exs

In Application Code

FunctionReturn TypeUse Case
Application.get_env/3value | defaultRuntime with default
Application.fetch_env/2{:ok, value} | :errorRuntime with pattern matching
Application.fetch_env!/2value (raises if missing)Required runtime config
Application.compile_env/3valueCompile-time with default
Application.compile_env!/2value (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

  1. Default to Runtime Configuration: Use Application.get_env/3 in function bodies
  2. Use runtime.exs for Environment Variables: Never read env vars in config.exs
  3. Use compile_env Only When Necessary: Only when config affects compilation
  4. Libraries Should Not Use Application Config: Accept options as function arguments
  5. Never Use Mix in Application Code: Use config_env() in config files, store result
  6. Validate Required Config Early: Use fetch_env!/2 in application start for required values
  7. Provide Sensible Defaults: Use get_env/3 with defaults for optional config
  8. Document Configuration: Add comments explaining what each config key does
  9. Use runtime.exs for Releases: Essential for Elixir releases and deployments
  10. 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

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:

  1. Never alias the live application schema. The live schema evolves; a migration written against MyApp.Epics.Epic today breaks when fields get renamed or removed in a future migration. Replay from scratch fails.
  2. 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: CONCURRENTLY requires @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_transaction rules
  • references/migrations-audit.md — repeatable two-phase (haiku indexer + opus reviewer) template for auditing a repo's migrations for /elixir:ecto compliance; reuses across repos by swapping the app namespace
  • references/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 via mcp__tidewave__get_ecto_schemas and 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_docs or the installed dep source — not memory.
  • Mark any unverified function as "requires investigation".
  • See /core:anti-fabrication for 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_one restarts only the crashed child; :one_for_all restarts every child; :rest_for_one restarts 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: true for read-heavy workloads
  • Use write_concurrency: true for write-heavy workloads
  • Prefer :set (default) for unique keys
  • Use :bag or :duplicate_bag for 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_concurrency for 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 catalog
  • references/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 modules
  • mix.exs or any dependency change
  • config/*.exs, especially runtime.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/3 for initial data loading
  • Handle route changes in handle_params/3
  • Keep renders fast - compute in event handlers, not render
  • Use assign_new/3 for expensive computations
  • Prefer LiveView over JavaScript for interactive UIs
  • Use phx-debounce and phx-throttle for 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/2 to avoid N+1 queries
  • Add database indexes for frequently queried fields
  • Use select/3 to load only needed fields
  • Consider using Repo.stream/2 for large datasets

LiveView Performance

  • Move expensive computations to handle_event or background jobs
  • Use assign_new/3 for computed values
  • Implement handle_continue/2 for 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_headers plug
  • 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

OptionDescription
:binaryDeliver 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
:streamNo framing — raw bytes delivered as received (default)
:exit_statusSend {port, {:exit_status, code}} when the program exits
:use_stdioUse stdin/stdout for communication (default)
:stderr_to_stdoutMerge 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
:parallelismHint 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/1 to receive :DOWN messages
  • Use {:packet, N} for reliable message framing
  • Store the calling from pid when waiting for a response
  • Reply via GenServer.reply/2 from handle_info when data arrives
  • Always check Port.info(port) before closing in terminate/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_status was set) and closes.
  • Ports are linked to their owning process by default.

Decision Guide: Port vs NIF vs C Node vs System.cmd

AspectPortNIFC NodeSystem.cmd
Crash isolationYes — OS processNo — crashes the VMYes — OS processYes — subprocess
LatencyIPC overheadNear zeroMessage passingBlocking, high
ComplexityLow–MediumHighVery highVery low
Scheduler impactNoneBlocks (use dirty NIFs for >1ms)NoneBlocks caller only
Security boundaryOS process isolationFull VM accessOS process isolationOS process isolation
Best forLong-running, streamingSub-millisecond sync callsLegacy C integrationOne-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/2 Erlang option reference
  • Binary protocol wire format and byte calculations
  • erl_interface / ei C 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/1 to 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 bare receive in 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-bangBang
File.read/1 → {:ok, content} or {:error, reason}File.read!/1 → content or raises
Map.fetch/2 → {:ok, value} or :errorMap.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 nilRepo.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 with for 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_schema or schemaless changesets for non-DB data that still needs validation
  • Pipe for transformation chains; call directly for single operations and side effects
  • Reserve try/rescue for 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 describe blocks to group related tests
  • Use test/support for 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 setup for 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_receive vs assert 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/3 saves and restores it in setup + on_exit.
  • Every test that uses Process.put/2 on a shared key cleans up in on_exit.
  • Every test that writes files uses a unique temp dir (System.unique_integer([:positive])) and removes it via on_exit.
  • async: false is 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 tooling
  • references/database-testing.md — Test factories (ExMachina) and changeset test patterns
  • references/phoenix-testing.md — Controller, LiveView, and Channel test examples
  • references/property-based-testing.md — StreamData property tests and custom generators
  • references/os-subprocess-adapter.md — Elixir @callback + Mox shape for wrapping System.cmd / Port.open calls behind a mockable seam; config wiring per environment
  • references/elixir-tdd-discipline.md — Elixir-specific TDD defaults: @cmd_mod compile-time seam, async: true everywhere, mock external boundaries (HTTP / OS / time / third-party APIs), no :integration tags, no log noise, no error-swallowing else _ -> :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_docs instead of WebFetch on hexdocs.pm/<package>/<Module>.html
  • search_package_docs instead of broader hex-doc searches
  • get_source_location instead of reading deps/<package>/lib/... with Read
  • execute_sql_query instead of shelling into psql
  • project_eval instead of running iex -S mix snippets

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)

  1. Add to mix.exs:
defp deps do
  [
    {:tidewave, "~> 0.5", only: :dev}
  ]
end
  1. Add plug to lib/my_app_web/endpoint.ex before the code_reloading? block:
if Mix.env() == :dev do
  plug Tidewave
end

if code_reloading? do
  # ...existing code reload plugs...
end
  1. 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

ToolDescription
project_evalExecute Elixir code within the running application runtime
execute_sql_queryRun SQL queries against the application database
get_ecto_schemasList all Ecto schema modules with their fields and associations
get_ash_resourcesList all Ash resources (when using the Ash framework)
get_docsRetrieve documentation for modules/functions using exact project versions
search_package_docsQuery hexdocs.pm filtered to project dependencies (availability varies by framework)
get_source_locationFind module/function source code file paths and line numbers
get_modelsList all application modules with their file locations
get_logsAccess 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
OptionDefaultDescription
allow_remote_accessfalseAllow connections from non-localhost
inspect_opts[]Options passed to Kernel.inspect/2 for output formatting
teamnilTeam 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

When to Use CLI vs Phoenix Plug

ScenarioUse
Phoenix applicationplug Tidewave in endpoint.ex
Container/remote devCLI app or plug with allow_remote_access: true
Non-Phoenix ElixirCLI app
Standalone MCP serverCLI 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() == :dev or only: :dev in 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: true only on trusted networks
  • CSP: Tidewave injects unsafe-eval in script-src directives and disables frame-ancestors restrictions

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/mcp if IPv6 causes issues

Tools not appearing

  • Confirm plug Tidewave is placed before if code_reloading? in endpoint.ex
  • Restart the Phoenix server after adding the plug
  • Verify the dependency is installed: mix deps.get

Claude Code authentication error

  • Run claude in 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 :tidewave is added to the correct mix.exs in 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

  1. Discover: Use get_ecto_schemas or get_models to understand application structure
  2. Locate: Use get_source_location to find module/function source paths
  3. Inspect: Use get_docs or search_package_docs for documentation lookup
  4. Evaluate: Use project_eval to execute Elixir code in the running app
  5. Query: Use execute_sql_query to inspect database state
  6. Debug: Use get_logs to review server output (supports log level filtering)
  7. 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

NeedToolNotes
List schemas and fieldsget_ecto_schemasPhoenix-specific
List Ash resourcesget_ash_resourcesAsh framework only
Find module source fileget_source_location
List all modulesget_models
Read module/function docsget_docsUses project dependency versions
Search hex dependency docssearch_package_docsMay not be available in all frameworks
Run Elixir code in appproject_eval
Run SQL against databaseexecute_sql_query
Check server logsget_logsSupports log level filtering (added v0.5.5)
Read source filesRead, 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