Ecto Schema Patterns

Master Ecto schemas to define robust data structures for your Elixir applications. This skill covers schema definitions, field types, associations, embedded schemas, and advanced patterns for modeling complex domain data.

Basic Schema Definition

defmodule MyApp.User do use Ecto.Schema

schema "users" do field :name, :string field :email, :string field :age, :integer field :confirmed_at, :naive_datetime

timestamps()

end end

Schemas map to database tables and define the structure of your data. Each schema has a source name (table name) and a list of fields with their types. The timestamps()

macro automatically adds inserted_at and updated_at fields.

Field Types and Options

defmodule MyApp.Product do use Ecto.Schema

schema "products" do # Standard field types field :title, :string field :description, :string field :price, :decimal field :quantity, :integer field :is_active, :boolean, default: true field :published_at, :utc_datetime

# Enum type
field :status, Ecto.Enum, values: [:draft, :published, :archived]

# Map type for unstructured data
field :metadata, :map

# Array type
field :tags, {:array, :string}

# Binary type for binary data
field :image_data, :binary

# Virtual field (not persisted to database)
field :display_price, :string, virtual: true

timestamps()

end end

Ecto supports a wide range of field types including strings, integers, decimals, booleans, datetime types, enums, maps, arrays, and binary data. Virtual fields exist only in memory and are useful for computed values.

Using Map Type for Flexible Data

defmodule MyApp.User do use Ecto.Schema

schema "users" do field :name, :string field :email, :string field :data, :map

timestamps()

end end

Usage

user = %MyApp.User{ name: "John Doe", email: "john@example.com", data: %{ preferences: %{ theme: "dark", notifications: true }, settings: %{ language: "en" } } }

The :map type allows storing arbitrary Elixir maps in the database, providing flexibility for unstructured or semi-structured data without requiring schema changes.

Embedded Schemas

defmodule MyApp.Address do use Ecto.Schema

embedded_schema do field :street, :string field :city, :string field :state, :string field :zip_code, :string field :country, :string, default: "US" end end

Embedded schemas define data structures that are not tied to a database table. They can be embedded within other schemas or used independently in memory for data validation and casting.

Embedding One Association

defmodule MyApp.Order do use Ecto.Schema

schema "orders" do field :total, :decimal field :status, :string

embeds_one :item, Item

timestamps()

end end

defmodule MyApp.Item do use Ecto.Schema

embedded_schema do field :title, :string field :price, :decimal field :quantity, :integer end end

The embeds_one macro defines a one-to-one relationship with an embedded schema. The embedded data is stored as a JSON or map column in the parent table, not in a separate table.

Inline Embedded Schema Definition

defmodule MyApp.Parent do use Ecto.Schema

schema "parents" do field :name, :string

embeds_one :child, Child do
  field :name, :string
  field :age, :integer
end

timestamps()

end end

Schemas can be embedded inline using a do block, which creates a nested module (e.g., MyApp.Parent.Child ). This is useful for simpler embedded structures that don't need to be defined separately.

Embedding Many Association

defmodule MyApp.Order do use Ecto.Schema

schema "orders" do field :customer_name, :string field :total, :decimal

embeds_many :items, OrderItem do
  field :product_name, :string
  field :quantity, :integer
  field :price, :decimal
end

timestamps()

end end

The embeds_many macro defines a one-to-many relationship with embedded schemas. Multiple embedded records are stored as a JSON array in the parent table.

Complex Embedded Schema with Custom Changeset

defmodule MyApp.User do use Ecto.Schema

schema "users" do field :full_name, :string field :email, :string field :avatar_url, :string field :confirmed_at, :naive_datetime

embeds_one :profile, Profile do
  field :online, :boolean
  field :dark_mode, :boolean
  field :visibility, Ecto.Enum, values: [:public, :private, :friends_only]
end

timestamps()

end

def changeset(%MODULE{} = user, attrs \ %{}) do user |> Ecto.Changeset.cast(attrs, [:full_name, :email]) |> Ecto.Changeset.cast_embed(:profile, required: true, with: &profile_changeset/2) end

def profile_changeset(profile, attrs \ %{}) do profile |> Ecto.Changeset.cast(attrs, [:online, :dark_mode, :visibility]) |> Ecto.Changeset.validate_required([:online, :visibility]) end end

Custom changeset functions can be defined for embedded schemas using the :with

option in cast_embed/3 . This allows for specific validation logic on nested data.

Extracted Embedded Schema Module

user/user.ex

defmodule MyApp.User do use Ecto.Schema

schema "users" do field :full_name, :string field :email, :string field :avatar_url, :string field :confirmed_at, :naive_datetime

embeds_one :profile, MyApp.UserProfile

timestamps()

end end

user/user_profile.ex

defmodule MyApp.UserProfile do use Ecto.Schema

embedded_schema do field :online, :boolean field :dark_mode, :boolean field :visibility, Ecto.Enum, values: [:public, :private, :friends_only] end

def changeset(%MODULE{} = profile, attrs \ %{}) do profile |> Ecto.Changeset.cast(attrs, [:online, :dark_mode, :visibility]) |> Ecto.Changeset.validate_required([:online, :visibility]) end end

Extracting embedded schemas into dedicated modules improves organization and allows the embedded schema to have its own changeset functions, validations, and behavior.

Belongs To Association

defmodule MyApp.Comment do use Ecto.Schema

schema "comments" do field :body, :string field :author, :string

belongs_to :post, MyApp.Post

timestamps()

end end

defmodule MyApp.Post do use Ecto.Schema

schema "posts" do field :title, :string field :body, :string

has_many :comments, MyApp.Comment

timestamps()

end end

The belongs_to macro defines a foreign key relationship. By default, it creates a post_id field in the comments table. The parent schema typically defines the inverse relationship with has_many .

Custom Belongs To Field

defmodule MyApp.Comment do use Ecto.Schema

schema "comments" do field :post_id, :integer belongs_to :post, MyApp.Post, define_field: false end end

You can customize the foreign key field definition by setting define_field: false

and manually defining the field. This is useful when you need special options on the foreign key field.

Has One Association

defmodule MyApp.Account do use Ecto.Schema

schema "accounts" do field :email, :string

has_one :profile, MyApp.Profile

timestamps()

end end

defmodule MyApp.Profile do use Ecto.Schema

schema "profiles" do field :name, :string field :age, :integer

belongs_to :account, MyApp.Account

timestamps()

end end

The has_one macro defines a one-to-one relationship where the foreign key is stored in the associated schema. The associated schema must have a corresponding belongs_to relationship.

Has Many Association

defmodule MyApp.User do use Ecto.Schema

schema "users" do field :name, :string field :email, :string

has_many :posts, MyApp.Post, foreign_key: :author_id

timestamps()

end end

The has_many macro defines a one-to-many relationship. You can customize the foreign key name using the foreign_key option if it differs from the default convention.

Many to Many Association with Join Table

defmodule MyApp.Post do use Ecto.Schema

schema "posts" do field :title, :string field :body, :string

many_to_many :tags, MyApp.Tag,
  join_through: "posts_tags",
  on_replace: :delete

timestamps()

end end

defmodule MyApp.Tag do use Ecto.Schema

schema "tags" do field :name, :string

many_to_many :posts, MyApp.Post,
  join_through: "posts_tags"

timestamps()

end end

The many_to_many macro defines a many-to-many relationship through a join table. The join_through option specifies the table name, and on_replace: :delete

controls how the association is updated.

Many to Many with Join Schema

defmodule MyApp.User do use Ecto.Schema

schema "users" do field :name, :string

many_to_many :organizations, MyApp.Organization,
  join_through: MyApp.UserOrganization

timestamps()

end end

defmodule MyApp.Organization do use Ecto.Schema

schema "organizations" do field :name, :string

many_to_many :users, MyApp.User,
  join_through: MyApp.UserOrganization

timestamps()

end end

defmodule MyApp.UserOrganization do use Ecto.Schema

@primary_key false schema "users_organizations" do belongs_to :user, MyApp.User belongs_to :organization, MyApp.Organization field :role, :string field :joined_at, :utc_datetime

timestamps()

end end

Using a dedicated join schema (instead of just a table name) allows you to add additional fields to the join table, such as role or timestamp information.

Schema with Composite Primary Key

defmodule MyApp.UserOrganization do use Ecto.Schema

@primary_key false schema "users_organizations" do belongs_to :user, MyApp.User, primary_key: true belongs_to :organization, MyApp.Organization, primary_key: true field :role, :string

timestamps()

end end

Composite primary keys can be created by setting @primary_key false and marking the relevant belongs_to associations with primary_key: true .

Custom Primary Key

defmodule MyApp.Product do use Ecto.Schema

@primary_key {:sku, :string, autogenerate: false} schema "products" do field :name, :string field :price, :decimal

timestamps()

end end

You can customize the primary key field name, type, and autogeneration behavior using the @primary_key module attribute.

Schema Metadata Access

defmodule MyApp.User do use Ecto.Schema

schema "users" do field :name, :string field :email, :string

has_many :posts, MyApp.Post
belongs_to :organization, MyApp.Organization

timestamps()

end end

Access schema metadata

MyApp.User.schema(:source) # "users" MyApp.User.schema(:fields) # [:id, :name, :email, :organization_id, :inserted_at, :updated_at] MyApp.User.schema(:primary_key) # [:id] MyApp.User.schema(:associations) # [:posts, :organization] MyApp.User.schema(:type, :name) # :string

The schema/1 and schema/2 functions provide access to schema metadata at runtime, useful for metaprogramming and dynamic query building.

Self-Referencing Association

defmodule MyApp.Person do use Ecto.Schema

schema "people" do field :name, :string

many_to_many :relations, MyApp.Person,
  join_through: MyApp.Relationship,
  join_keys: [person_id: :id, relation_id: :id]

timestamps()

end end

defmodule MyApp.Relationship do use Ecto.Schema

@primary_key false schema "relationships" do belongs_to :person, MyApp.Person belongs_to :relation, MyApp.Person field :relationship_type, :string

timestamps()

end end

Self-referencing associations allow a schema to reference itself, useful for hierarchical data or relationships between entities of the same type.

Polymorphic Association Pattern

defmodule MyApp.TodoItem do use Ecto.Schema

schema "todo_items" do field :description, :string

timestamps()

end end

defmodule MyApp.Comment do use Ecto.Schema

schema "comments" do field :body, :string field :commentable_id, :integer field :commentable_type, :string

timestamps()

end end

Create a comment for a TodoItem

comment = %MyApp.Comment{ body: "This needs to be done ASAP", commentable_id: todo_item.id, commentable_type: "todo_item" }

Polymorphic associations can be implemented using a combination of ID and type fields. While Ecto doesn't have built-in polymorphic associations like some ORMs, this pattern provides similar functionality.

Schema with Virtual Fields

defmodule MyApp.User do use Ecto.Schema

schema "users" do field :first_name, :string field :last_name, :string field :email, :string

# Virtual fields
field :full_name, :string, virtual: true
field :password, :string, virtual: true
field :password_hash, :string

timestamps()

end

def build_full_name(%MODULE{} = user) do %{user | full_name: "#{user.first_name} #{user.last_name}"} end end

Virtual fields are not persisted to the database but can be useful for temporary data like unhashed passwords or computed values like full names.

Schema with Custom Source

defmodule MyApp.LegacyUser do use Ecto.Schema

@schema_prefix "legacy" schema "tbl_users" do field :user_name, :string, source: :username field :user_email, :string, source: :email field :create_date, :utc_datetime, source: :created_at

timestamps()

end end

You can map schema fields to different column names using the :source option, useful when working with legacy databases or following different naming conventions.

Schema Prefix for Multi-Tenant Applications

defmodule MyApp.Organization do use Ecto.Schema

@schema_prefix "public" schema "organizations" do field :name, :string field :slug, :string

timestamps()

end end

defmodule MyApp.Tenant.User do use Ecto.Schema

schema "users" do field :name, :string field :email, :string

timestamps()

end end

Query with dynamic prefix

MyApp.Repo.all(MyApp.Tenant.User, prefix: "tenant_#{tenant_id}")

The @schema_prefix attribute and the prefix option enable multi-tenant applications where each tenant has its own database schema or prefix.

When to Use This Skill

Use ecto-schema-patterns when you need to:

• Define database-backed schemas for your application's domain models

• Create embedded schemas for nested or complex data structures

• Set up associations between different schemas (belongs_to, has_many, many_to_many)

• Model hierarchical or self-referential data

• Work with legacy databases using custom field mappings

• Implement multi-tenant applications with schema prefixes

• Define virtual fields for computed or temporary data

• Use custom primary keys or composite keys

• Store unstructured data using map or array fields

• Create polymorphic association patterns

Best Practices

• Use descriptive schema and field names that reflect your domain

• Always define timestamps() for audit trails unless there's a specific reason not to

• Prefer embedded schemas over JSON columns when the structure is known

• Use Ecto.Enum for fields with a fixed set of values

• Keep schemas focused on data structure, put business logic elsewhere

• Use virtual fields for data that shouldn't be persisted

• Define proper associations to leverage Ecto's preloading capabilities

• Use on_replace: :delete for many_to_many associations that should cascade

• Extract complex embedded schemas into separate modules for reusability

• Use belongs_to with define_field: false when you need custom foreign key options

• Leverage schema metadata functions for metaprogramming sparingly

• Use :source option to bridge schema and database naming differences

• Set appropriate @primary_key for non-standard primary keys

• Use join schemas instead of join tables when you need extra attributes

• Document schema relationships and constraints in module documentation

Common Pitfalls

• Forgetting to add timestamps() and losing audit information

• Not setting on_replace option for associations, causing unexpected behavior

• Confusing embeds_one /embeds_many with has_one /has_many

• Using :map type when an embedded schema would provide better structure

• Defining associations without corresponding database constraints

• Not marking virtual fields with virtual: true , causing database errors

• Mixing business logic with schema definitions

• Creating circular dependencies between schema modules

• Forgetting to set @primary_key false for join schemas

• Not using proper foreign key options in belongs_to

• Accessing associations without preloading them first

• Over-nesting embedded schemas, making them hard to maintain

• Not considering the difference between has_one and belongs_to

• Using polymorphic patterns without proper indexing

• Forgetting that embedded data is stored as JSON/map in a single column

• Not handling nil values properly in custom source mappings

• Creating too many associations, leading to N+1 query problems

• Not using join schemas when additional join table attributes are needed

• Hardcoding schema prefixes instead of making them configurable

• Not validating embedded schemas separately from parent schemas

Resources

Official Ecto Documentation

• Ecto.Schema Module

• Schema Definition

• Field Types

• Associations

• Embedded Schemas

• Polymorphic Associations

• Self-Referencing Many to Many

Guides and Patterns

• Getting Started with Ecto

• Schema Metadata

• Multi-Tenancy Guide

• Ecto Best Practices

Community Resources

• Elixir School - Ecto

• Elixir Forum - Ecto Category

• Programming Ecto Book