Choreo.ERD (Choreo v0.9.0)

Entity-Relationship Diagram (ERD) builder on top of Yog.

Choreo.ERD models database schemas, including tables, primary/foreign keys, column definitions, and relations with standard cardinalities.

Node types

:table — represents a database table with structured columns.

Edge types

Relationships model foreign key links with standard multiplicities:
- :one_to_one (exactly-one to exactly-one)
- :one_to_many (exactly-one to zero-or-more)
- :zero_or_one_to_many (zero-or-one to zero-or-more)
- :exactly_one_to_many (exactly-one to one-or-more)
- :many_to_many (zero-or-more to zero-or-more)

Quick Start

erd =
  Choreo.ERD.new()
  |> Choreo.ERD.add_table(:users, columns: [
    %{name: :id, type: :integer, key: :pk},
    %{name: :email, type: :varchar}
  ])
  |> Choreo.ERD.add_table(:posts, columns: [
    %{name: :id, type: :integer, key: :pk},
    %{name: :user_id, type: :integer, key: :fk},
    %{name: :title, type: :varchar}
  ])
  |> Choreo.ERD.add_relationship(:users, :posts, cardinality: :one_to_many, label: "writes")

dot = Choreo.ERD.to_dot(erd)
mermaid = Choreo.ERD.to_mermaid(erd)

Diagram

digraph G { graph [rankdir=LR, splines=spline, nodesep=1.2, ranksep=1.2]; node [shape=plain, style=filled, fillcolor="transparent", fontname="Helvetica", fontsize=12, fontcolor="#1e293b"]; edge [color="#64748b", style=solid, fontname="Helvetica", fontsize=10, penwidth=1.0]; users [label=<

users
id	integer	[PK]
email	varchar

>]; posts [label=<

posts
id	integer	[PK]
user_id	integer	[FK]
title	varchar

>]; users -> posts [penwidth="1.0", color="#64748b", dir="both", arrowhead="crowodot", arrowtail="teetee", label="writes"]; }

Summary

Types

t()

table_id()

Functions

add_relationship(erd, from, to, opts \\ [])

Adds a directed relationship/foreign key edge between two tables in the ERD.

add_table(erd, id, opts \\ [])

Adds a table to the ERD diagram with structured columns.

new(opts \\ [])

Initializes a new, empty ERD.

theme(name \\ :default, overrides \\ [])

Returns a theme for the ERD diagram.

to_dot(erd, opts \\ [])

Renders the ERD to Graphviz DOT syntax.

to_mermaid(erd, opts \\ [])

Renders the ERD to Mermaid.js native erDiagram syntax.

Types

t()

@type t() :: %Choreo.ERD{
  edge_meta: %{optional(Yog.Multi.Graph.edge_id()) => map()},
  graph: Yog.Multi.Graph.t(),
  strict: boolean(),
  strict_column_matching: boolean()
}

table_id()

@type table_id() :: Yog.node_id()

Functions

add_relationship(erd, from, to, opts \\ [])

@spec add_relationship(t(), table_id(), table_id(), keyword()) :: t()

Adds a directed relationship/foreign key edge between two tables in the ERD.

Options

:label (String.t/0) - Visual label/description of the relationship (e.g. 'writes').
:cardinality - Required. Multiplicity constraint: :one_to_one, :one_to_many, :zero_or_one_to_many, :exactly_one_to_many, or :many_to_many.
:from_column (term/0) - The name of the column in the source table (atom or string).
:to_column (term/0) - The name of the column in the destination table (atom or string).

Examples

iex> erd = Choreo.ERD.new()
...> |> Choreo.ERD.add_table(:users, columns: [%{name: :id, type: :integer}])
...> |> Choreo.ERD.add_table(:posts, columns: [%{name: :user_id, type: :integer}])
...> |> Choreo.ERD.add_relationship(:users, :posts, cardinality: :one_to_many)
iex> %Choreo.ERD{} = erd
iex> map_size(erd.graph.edges)
1

add_table(erd, id, opts \\ [])

@spec add_table(t(), table_id(), keyword()) :: t()

Adds a table to the ERD diagram with structured columns.

Options

:label (String.t/0) - Visual label for the table. Defaults to stringified table ID.
:columns (term/0) - Required. List of structured columns.

Examples

iex> erd = Choreo.ERD.new()
...> |> Choreo.ERD.add_table(:users, columns: [%{name: :id, type: :integer, key: :pk}])
iex> %Choreo.ERD{} = erd
iex> Map.has_key?(erd.graph.nodes, :users)
true

new(opts \\ [])

@spec new(keyword()) :: t()

Initializes a new, empty ERD.

Options

:strict_column_matching - if true, validates that any foreign key columns mapped between tables exist and have matching types (default: false).
:strict - if true, add_relationship/4 raises when an endpoint does not already exist (default: false).

Examples

iex> erd = Choreo.ERD.new()
iex> %Choreo.ERD{} = erd
iex> erd.strict_column_matching
false

theme(name \\ :default, overrides \\ [])

@spec theme(
  atom(),
  keyword()
) :: Choreo.Theme.t()

Returns a theme for the ERD diagram.

Examples

iex> theme = Choreo.ERD.theme(:dark)
iex> theme.graph_bgcolor
"#0f172a"

to_dot(erd, opts \\ [])

@spec to_dot(
  t(),
  keyword()
) :: String.t()

Renders the ERD to Graphviz DOT syntax.

Examples

iex> erd = Choreo.ERD.new() |> Choreo.ERD.add_table(:users, columns: [%{name: :id, type: :integer}])
iex> dot = Choreo.ERD.to_dot(erd)
iex> dot =~ "digraph"
true

to_mermaid(erd, opts \\ [])

@spec to_mermaid(
  t(),
  keyword()
) :: String.t()

Renders the ERD to Mermaid.js native erDiagram syntax.

Examples

iex> erd = Choreo.ERD.new() |> Choreo.ERD.add_table(:users, columns: [%{name: :id, type: :integer}])
iex> Choreo.ERD.to_mermaid(erd) =~ "erDiagram"
true