Add examples of migrations to Ecto Association cheatsheets

Author: josevalim

guides/cheatsheets/associations.cheatmd

@@ -1,6 +1,6 @@
 # Associations
 
-In this document, "Internal data" represents data or logic hardcoded into your Elixir code. "External data" means data that comes from the user via forms, APIs, and often need to be normalized, pruned, and validated via `Ecto.Changeset`.
+In this document, "Internal data" represents data or logic hardcoded into your Elixir code. "External data" means data that comes from the user via forms, APIs, and often need to be normalized, pruned, and validated via `Ecto.Changeset`. We also include examples of migrations, according to [`EctoSQL`](https://hexdocs.pm/ecto_sql).
 
 ## Has many / belongs to
 {: .col-2}
@@ -33,6 +33,33 @@ defmodule Character do
 end
 ```
 
+### The migration
+
+```elixir
+defmodule MyApp.Migrations.CreateMoviesAndCharacters do
+  use Ecto.Migration
+
+  def change do
+    create table("movies") do
+      add :title, :string, null: false
+      add :release_date, :date
+      timestamps()
+    end
+
+    # The foreign key is in the belongs_to schema
+    create table("characters") do
+      add :name, :string, null: false
+      add :age, :integer
+      add :movie_id,
+          references(:movies, on_delete: :delete_all),
+          null: false
+
+      timestamps()
+    end
+  end
+end
+```
+
 ## Has one / belongs to
 {: .col-2}
 
@@ -63,6 +90,32 @@ defmodule Screenplay do
 end
 ```
 
+### The migration
+
+```elixir
+defmodule MyApp.Migrations.CreateMoviesAndPlays do
+  use Ecto.Migration
+
+  def change do
+    create table("movies") do
+      add :title, :string, null: false
+      add :release_date, :date
+      timestamps()
+    end
+
+    # The foreign key is in the belongs_to schema
+    create table("screenplays") do
+      add :lead_writer, :string, null: false
+      add :movie_id,
+          references(:movies, on_delete: :delete_all),
+          null: false
+
+      timestamps()
+    end
+  end
+end
+```
+
 ## Many to many
 {: .col-2}
 
@@ -141,6 +194,40 @@ end
 ```
 {: .wrap}
 
+### The migration
+
+It applies to both join tables and schemas.
+
+```elixir
+defmodule MyApp.Migrations.CreateUsersAndOrgs do
+  use Ecto.Migration
+
+  def change do
+    create table("users") do
+      timestamps()
+    end
+
+    create table("organizations") do
+      timestamps()
+    end
+
+    create table("users_organizations", primary_key: false) do
+      add :user_id,
+          references(:users, on_delete: :delete_all),
+          null: false
+
+      add :organization_id,
+          references(:organizations, on_delete: :delete_all),
+          null: false
+
+      timestamps()
+    end
+
+    create unique_index(:users_organizations, [:user_id, :organization_id])
+  end
+end
+```
+
 ## Querying associated records
 {: .col-2}
 

guides/introduction/Embedded Schemas.md

@@ -2,10 +2,9 @@
 
 Embedded schemas allow you to define and validate structured data. This data can live in memory, or can be stored in the database. Some use cases for embedded schemas include:
 
-- You are maintaining intermediate-state data, like when UI form fields map onto multiple tables in a database.
+- You are maintaining intermediate-state data, like when UI form fields map onto multiple tables in a database, or to model entities which are not backed by a database, such as a contact form
 
 - You are working within a persisted parent schema and you want to embed data that is...
-
   - simple, like a map of user preferences inside a User schema.
   - changes often, like a list of product images with associated structured data inside a Product schema.
   - requires complex tracking and validation, like an Address schema inside a User schema.

lib/ecto/schema.ex

@@ -6,21 +6,25 @@ defmodule Ecto.Schema do
   `schema/2` and `embedded_schema/1`.
 
   `schema/2` is typically used to map data from a persisted source,
-  usually a database table, into Elixir structs and vice-versa. For
-  this reason, the first argument of `schema/2` is the source (table)
-  name. Structs defined with `schema/2` also contain a `__meta__` field
-  with metadata holding the status of the struct, for example, if it
-  has been built, loaded or deleted.
+  usually a database table, into Elixir structs and vice-versa via
+  the `Ecto.Repo` module. For this reason, the first argument of `schema/2`
+  is the source (table) name. Structs defined with `schema/2` also contain
+  a `__meta__` field with metadata holding the status of the struct,
+  for example, if it has been built, loaded or deleted. Schemas also support
+  associations, through APIs such as `has_one/3` and `belongs_to/3`.
+  Check out the [Associations cheatsheet](associations.cheatmd) for a reference
+  on the different associations types and their migrations.
 
   On the other hand, `embedded_schema/1` is used for defining schemas
   that are embedded in other schemas or only exist in-memory. For example,
   you can use such schemas to receive data from a command line interface
-  and validate it, without ever persisting it elsewhere. Such structs
-  do not contain a `__meta__` field, as they are never persisted.
+  or a contact form, and validate it, without ever persisting it elsewhere.
+  Such structs do not contain a `__meta__` field, as they are never persisted.
 
-  Besides working as data mappers, `embedded_schema/1` and `schema/2` can
-  also be used together to decouple how the data is represented in your
-  applications from the database. Let's see some examples.
+  Both schemas can be used alongside changesets to filter, cast, and validate
+  data. Besides working as data mappers, `embedded_schema/1` and `schema/2`
+  can also be used together to decouple how the data is represented in your
+  applications from the database.
 
   ## Example
 
@@ -793,6 +797,11 @@ defmodule Ecto.Schema do
       [post] = Repo.all(from(p in Post, where: p.id == 42, preload: :comments))
       post.comments #=> [%Comment{...}, ...]
 
+  If using [EctoSQL](https://hexdocs.pm/ecto_sql), the foreign key should be
+  defined in the `comments` table, as shown in `belongs_to/3` examples.
+  You may also see the [Associations cheatsheet](associations.cheatmd)
+  for more examples.
+
   `has_many` can be used to define hierarchical relationships within a single
   schema, for example threaded comments.
 
@@ -1022,6 +1031,11 @@ defmodule Ecto.Schema do
       # The permalink can come preloaded on the post struct
       [post] = Repo.all(from(p in Post, where: p.id == 42, preload: :permalink))
       post.permalink #=> %Permalink{...}
+
+  If using [EctoSQL](https://hexdocs.pm/ecto_sql), a foreign key must be defined
+  in the `permalinks` and `categories` tables, as shown in `belongs_to/3`
+  examples. You may also see the [Associations cheatsheet](associations.cheatmd)
+  for more examples.
   """
   defmacro has_one(name, schema, opts \\ []) do
     schema = expand_literals(schema, __CALLER__)
@@ -1110,6 +1124,16 @@ defmodule Ecto.Schema do
         end
       end
 
+  If using [EctoSQL](https://hexdocs.pm/ecto_sql), the `comments` table
+  should have a `post_id` column that references the `posts` table.
+  In your migrations, this can be done as:
+
+      add :post_id,
+          references(:posts, on_delete: :delete_all),
+          null: false
+
+  See the [Associations cheatsheet](associations.cheatmd) for more examples.
+
   ## Polymorphic associations
 
   One common use case for belongs to associations is to handle
@@ -1200,7 +1224,7 @@ defmodule Ecto.Schema do
 
   The third and final option is to use `many_to_many/3` to
   define the relationships between the resources. In this case,
-  the comments table won't have the foreign key, instead there
+  the `comments` table won't have the foreign key, instead there
   is an intermediary table responsible for associating the entries:
 
       defmodule Comment do
@@ -1376,17 +1400,17 @@ defmodule Ecto.Schema do
   include any further columns, as those values won't be set by Ecto:
 
       create table(:posts_tags, primary_key: false) do
-        add :post_id, references(:posts)
-        add :tag_id, references(:tags)
+        add :post_id, references(:posts, on_delete: :delete_all), null: false
+        add :tag_id, references(:tags, on_delete: :delete_all), null: false
       end
 
   However, if your `:join_through` is a schema, like `MyApp.PostTag`, your
   join table may be structured as any other table in your codebase,
   including timestamps:
 
       create table(:posts_tags) do
-        add :post_id, references(:posts)
-        add :tag_id, references(:tags)
+        add :post_id, references(:posts, on_delete: :delete_all), null: false
+        add :tag_id, references(:tags, on_delete: :delete_all), null: false
         timestamps()
       end