schema.ex (87555B)
1 defmodule Ecto.Schema do 2 @moduledoc ~S""" 3 An Ecto schema maps external data into Elixir structs. 4 5 The definition of the schema is possible through two main APIs: 6 `schema/2` and `embedded_schema/1`. 7 8 `schema/2` is typically used to map data from a persisted source, 9 usually a database table, into Elixir structs and vice-versa. For 10 this reason, the first argument of `schema/2` is the source (table) 11 name. Structs defined with `schema/2` also contain a `__meta__` field 12 with metadata holding the status of the struct, for example, if it 13 has been built, loaded or deleted. 14 15 On the other hand, `embedded_schema/1` is used for defining schemas 16 that are embedded in other schemas or only exist in-memory. For example, 17 you can use such schemas to receive data from a command line interface 18 and validate it, without ever persisting it elsewhere. Such structs 19 do not contain a `__meta__` field, as they are never persisted. 20 21 Besides working as data mappers, `embedded_schema/1` and `schema/2` can 22 also be used together to decouple how the data is represented in your 23 applications from the database. Let's see some examples. 24 25 ## Example 26 27 defmodule User do 28 use Ecto.Schema 29 30 schema "users" do 31 field :name, :string 32 field :age, :integer, default: 0 33 field :password, :string, redact: true 34 has_many :posts, Post 35 end 36 end 37 38 By default, a schema will automatically generate a primary key which is named 39 `id` and of type `:integer`. The `field` macro defines a field in the schema 40 with given name and type. `has_many` associates many posts with the user 41 schema. Schemas are regular structs and can be created and manipulated directly 42 using Elixir's struct API: 43 44 iex> user = %User{name: "jane"} 45 iex> %{user | age: 30} 46 47 However, most commonly, structs are cast, validated and manipulated with the 48 `Ecto.Changeset` module. 49 50 Note that the name of the database table does not need to correlate to your 51 module name. For example, if you are working with a legacy database, you can 52 reference the table name when you define your schema: 53 54 defmodule User do 55 use Ecto.Schema 56 57 schema "legacy_users" do 58 # ... fields ... 59 end 60 end 61 62 Embedded schemas are defined similarly to source-based schemas. For example, 63 you can use an embedded schema to represent your UI, mapping and validating 64 its inputs, and then you convert such embedded schema to other schemas that 65 are persisted to the database: 66 67 defmodule SignUp do 68 use Ecto.Schema 69 70 embedded_schema do 71 field :name, :string 72 field :age, :integer 73 field :email, :string 74 field :accepts_conditions, :boolean 75 end 76 end 77 78 defmodule Profile do 79 use Ecto.Schema 80 81 schema "profiles" do 82 field :name 83 field :age 84 belongs_to :account, Account 85 end 86 end 87 88 defmodule Account do 89 use Ecto.Schema 90 91 schema "accounts" do 92 field :email 93 end 94 end 95 96 The `SignUp` schema can be cast and validated with the help of the 97 `Ecto.Changeset` module, and afterwards, you can copy its data to 98 the `Profile` and `Account` structs that will be persisted to the 99 database with the help of `Ecto.Repo`. 100 101 ## Redacting fields 102 103 A field marked with `redact: true` will display a value of `**redacted**` 104 when inspected in changes inside a `Ecto.Changeset` and be excluded from 105 inspect on the schema unless the schema module is tagged with 106 the option `@ecto_derive_inspect_for_redacted_fields false`. 107 108 ## Schema attributes 109 110 Supported attributes for configuring the defined schema. They must 111 be set after the `use Ecto.Schema` call and before the `schema/2` 112 definition. 113 114 These attributes are: 115 116 * `@primary_key` - configures the schema primary key. It expects 117 a tuple `{field_name, type, options}` with the primary key field 118 name, type (typically `:id` or `:binary_id`, but can be any type) and 119 options. It also accepts `false` to disable the generation of a primary 120 key field. Defaults to `{:id, :id, autogenerate: true}`. 121 122 * `@schema_prefix` - configures the schema prefix. Defaults to `nil`, 123 which generates structs and queries without prefix. When set, the 124 prefix will be used by every built struct and on queries whenever 125 the schema is used in a `from` or a `join`. In PostgreSQL, the prefix 126 is called "SCHEMA" (typically set via Postgres' `search_path`). 127 In MySQL the prefix points to databases. 128 129 * `@schema_context` - configures the schema context. Defaults to `nil`, 130 which generates structs and queries without context. Context are not used 131 by the built-in SQL adapters. 132 133 * `@foreign_key_type` - configures the default foreign key type 134 used by `belongs_to` associations. It must be set in the same 135 module that defines the `belongs_to`. Defaults to `:id`; 136 137 * `@timestamps_opts` - configures the default timestamps type 138 used by `timestamps`. Defaults to `[type: :naive_datetime]`; 139 140 * `@derive` - the same as `@derive` available in `Kernel.defstruct/1` 141 as the schema defines a struct behind the scenes; 142 143 * `@field_source_mapper` - a function that receives the current field name 144 and returns the mapping of this field name in the underlying source. 145 In other words, it is a mechanism to automatically generate the `:source` 146 option for the `field` macro. It defaults to `fn x -> x end`, where no 147 field transformation is done; 148 149 The advantage of configuring the schema via those attributes is 150 that they can be set with a macro to configure application wide 151 defaults. 152 153 For example, if your database does not support autoincrementing 154 primary keys and requires something like UUID or a RecordID, you 155 can configure and use `:binary_id` as your primary key type as follows: 156 157 # Define a module to be used as base 158 defmodule MyApp.Schema do 159 defmacro __using__(_) do 160 quote do 161 use Ecto.Schema 162 @primary_key {:id, :binary_id, autogenerate: true} 163 @foreign_key_type :binary_id 164 end 165 end 166 end 167 168 # Now use MyApp.Schema to define new schemas 169 defmodule MyApp.Comment do 170 use MyApp.Schema 171 172 schema "comments" do 173 belongs_to :post, MyApp.Post 174 end 175 end 176 177 Any schemas using `MyApp.Schema` will get the `:id` field with type 178 `:binary_id` as the primary key. We explain what the `:binary_id` type 179 entails in the next section. 180 181 The `belongs_to` association on `MyApp.Comment` will also define 182 a `:post_id` field with `:binary_id` type that references the `:id` 183 field of the `MyApp.Post` schema. 184 185 ## Primary keys 186 187 Ecto supports two ID types, called `:id` and `:binary_id`, which are 188 often used as the type for primary keys and associations. 189 190 The `:id` type is used when the primary key is an integer while the 191 `:binary_id` is used for primary keys in particular binary formats, 192 which may be `Ecto.UUID` for databases like PostgreSQL and MySQL, 193 or some specific ObjectID or RecordID often imposed by NoSQL databases. 194 195 In both cases, both types have their semantics specified by the 196 underlying adapter/database. If you use the `:id` type with 197 `:autogenerate`, it means the database will be responsible for 198 auto-generation of the id. This is often the case for primary keys 199 in relational databases which are auto-incremented. 200 201 There are two ways to define primary keys in Ecto: using the `@primary_key` 202 module attribute and using `primary_key: true` as option for `field/3` in 203 your schema definition. They are not mutually exclusive and can be used 204 together. 205 206 Using `@primary_key` should be preferred for single field primary keys and 207 sharing primary key definitions between multiple schemas using macros. 208 Setting `@primary_key` also automatically configures the reference types 209 for `has_one` and `has_many` associations. 210 211 Ecto also supports composite primary keys, which is where you need to use 212 `primary_key: true` for the fields in your schema. This usually goes along 213 with setting `@primary_key false` to disable generation of additional 214 primary key fields. 215 216 Besides `:id` and `:binary_id`, which are often used by primary 217 and foreign keys, Ecto provides a huge variety of types to be used 218 by any field. 219 220 ## Types and casting 221 222 When defining the schema, types need to be given. Types are split 223 into two categories, primitive types and custom types. 224 225 ### Primitive types 226 227 The primitive types are: 228 229 Ecto type | Elixir type | Literal syntax in query 230 :---------------------- | :---------------------- | :--------------------- 231 `:id` | `integer` | 1, 2, 3 232 `:binary_id` | `binary` | `<<int, int, int, ...>>` 233 `:integer` | `integer` | 1, 2, 3 234 `:float` | `float` | 1.0, 2.0, 3.0 235 `:boolean` | `boolean` | true, false 236 `:string` | UTF-8 encoded `string` | "hello" 237 `:binary` | `binary` | `<<int, int, int, ...>>` 238 `{:array, inner_type}` | `list` | `[value, value, value, ...]` 239 `:map` | `map` | 240 `{:map, inner_type}` | `map` | 241 `:decimal` | [`Decimal`](https://github.com/ericmj/decimal) | 242 `:date` | `Date` | 243 `:time` | `Time` | 244 `:time_usec` | `Time` | 245 `:naive_datetime` | `NaiveDateTime` | 246 `:naive_datetime_usec` | `NaiveDateTime` | 247 `:utc_datetime` | `DateTime` | 248 `:utc_datetime_usec` | `DateTime` | 249 250 **Notes:** 251 252 * When using database migrations provided by "Ecto SQL", you can pass 253 your Ecto type as the column type. However, note the same Ecto type 254 may support multiple database types. For example, all of `:varchar`, 255 `:text`, `:bytea`, etc. translate to Ecto's `:string`. Similarly, 256 Ecto's `:decimal` can be used for `:numeric` and other database 257 types. For more information, see [all migration types](https://hexdocs.pm/ecto_sql/Ecto.Migration.html#module-field-types). 258 259 * For the `{:array, inner_type}` and `{:map, inner_type}` type, 260 replace `inner_type` with one of the valid types, such as `:string`. 261 262 * For the `:decimal` type, `+Infinity`, `-Infinity`, and `NaN` values 263 are not supported, even though the `Decimal` library handles them. 264 To support them, you can create a custom type. 265 266 * For calendar types with and without microseconds, the precision is 267 enforced when persisting to the DB. For example, casting `~T[09:00:00]` 268 as `:time_usec` will succeed and result in `~T[09:00:00.000000]`, but 269 persisting a type without microseconds as `:time_usec` will fail. 270 Similarly, casting `~T[09:00:00.000000]` as `:time` will succeed, but 271 persisting will not. This is the same behaviour as seen in other types, 272 where casting has to be done explicitly and is never performed 273 implicitly when loading from or dumping to the database. 274 275 ### Custom types 276 277 Besides providing primitive types, Ecto allows custom types to be 278 implemented by developers, allowing Ecto behaviour to be extended. 279 280 A custom type is a module that implements one of the `Ecto.Type` 281 or `Ecto.ParameterizedType` behaviours. By default, Ecto provides 282 the following custom types: 283 284 Custom type | Database type | Elixir type 285 :---------------------- | :---------------------- | :--------------------- 286 `Ecto.UUID` | `:uuid` (as a binary) | `string()` (as a UUID) 287 `Ecto.Enum` | `:string` | `atom()` 288 289 Finally, schemas can also have virtual fields by passing the 290 `virtual: true` option. These fields are not persisted to the database 291 and can optionally not be type checked by declaring type `:any`. 292 293 ### The datetime types 294 295 Four different datetime primitive types are available: 296 297 * `naive_datetime` - has a precision of seconds and casts values 298 to Elixir's `NaiveDateTime` struct which has no timezone information. 299 300 * `naive_datetime_usec` - has a default precision of microseconds and 301 also casts values to `NaiveDateTime` with no timezone information. 302 303 * `utc_datetime` - has a precision of seconds and casts values to 304 Elixir's `DateTime` struct and expects the time zone to be set to UTC. 305 306 * `utc_datetime_usec` has a default precision of microseconds and also 307 casts values to `DateTime` expecting the time zone be set to UTC. 308 309 All of those types are represented by the same timestamp/datetime in the 310 underlying data storage, the difference are in their precision and how the 311 data is loaded into Elixir. 312 313 Having different precisions allows developers to choose a type that will 314 be compatible with the database and your project's precision requirements. 315 For example, some older versions of MySQL do not support microseconds in 316 datetime fields. 317 318 When choosing what datetime type to work with, keep in mind that Elixir 319 functions like `NaiveDateTime.utc_now/0` have a default precision of 6. 320 Casting a value with a precision greater than 0 to a non-`usec` type will 321 truncate all microseconds and set the precision to 0. 322 323 ### The map type 324 325 The map type allows developers to store an Elixir map directly 326 in the database: 327 328 # In your migration 329 create table(:users) do 330 add :data, :map 331 end 332 333 # In your schema 334 field :data, :map 335 336 # Now in your code 337 user = Repo.insert! %User{data: %{"foo" => "bar"}} 338 339 Keep in mind that we advise the map keys to be strings or integers 340 instead of atoms. Atoms may be accepted depending on how maps are 341 serialized but the database will always convert atom keys to strings 342 due to security reasons. 343 344 In order to support maps, different databases may employ different 345 techniques. For example, PostgreSQL will store those values in jsonb 346 fields, allowing you to just query parts of it. MSSQL, on 347 the other hand, does not yet provide a JSON type, so the value will be 348 stored in a text field. 349 350 For maps to work in such databases, Ecto will need a JSON library. 351 By default Ecto will use [Jason](https://github.com/michalmuskala/jason) 352 which needs to be added to your deps in `mix.exs`: 353 354 {:jason, "~> 1.0"} 355 356 You can however configure the adapter to use another library. For example, 357 if using Postgres: 358 359 config :postgrex, :json_library, YourLibraryOfChoice 360 361 Or if using MySQL: 362 363 config :mariaex, :json_library, YourLibraryOfChoice 364 365 If changing the JSON library, remember to recompile the adapter afterwards 366 by cleaning the current build: 367 368 mix deps.clean --build postgrex 369 370 ### Casting 371 372 When directly manipulating the struct, it is the responsibility of 373 the developer to ensure the field values have the proper type. For 374 example, you can create a user struct with an invalid value 375 for `age`: 376 377 iex> user = %User{age: "0"} 378 iex> user.age 379 "0" 380 381 However, if you attempt to persist the struct above, an error will 382 be raised since Ecto validates the types when sending them to the 383 adapter/database. 384 385 Therefore, when working with and manipulating external data, it is 386 recommended to use `Ecto.Changeset`'s that are able to filter 387 and properly cast external data: 388 389 changeset = Ecto.Changeset.cast(%User{}, %{"age" => "0"}, [:age]) 390 user = Repo.insert!(changeset) 391 392 **You can use Ecto schemas and changesets to cast and validate any kind 393 of data, regardless if the data will be persisted to an Ecto repository 394 or not**. 395 396 ## Reflection 397 398 Any schema module will generate the `__schema__` function that can be 399 used for runtime introspection of the schema: 400 401 * `__schema__(:source)` - Returns the source as given to `schema/2`; 402 * `__schema__(:prefix)` - Returns optional prefix for source provided by 403 `@schema_prefix` schema attribute; 404 * `__schema__(:primary_key)` - Returns a list of primary key fields (empty if there is none); 405 406 * `__schema__(:fields)` - Returns a list of all non-virtual field names; 407 * `__schema__(:virtual_fields)` - Returns a list of all virtual field names; 408 * `__schema__(:field_source, field)` - Returns the alias of the given field; 409 410 * `__schema__(:type, field)` - Returns the type of the given non-virtual field; 411 * `__schema__(:virtual_type, field)` - Returns the type of the given virtual field; 412 413 * `__schema__(:associations)` - Returns a list of all association field names; 414 * `__schema__(:association, assoc)` - Returns the association reflection of the given assoc; 415 416 * `__schema__(:embeds)` - Returns a list of all embedded field names; 417 * `__schema__(:embed, embed)` - Returns the embedding reflection of the given embed; 418 419 * `__schema__(:read_after_writes)` - Non-virtual fields that must be read back 420 from the database after every write (insert or update); 421 422 * `__schema__(:autogenerate_id)` - Primary key that is auto generated on insert; 423 424 * `__schema__(:redact_fields)` - Returns a list of redacted field names; 425 426 Furthermore, both `__struct__` and `__changeset__` functions are 427 defined so structs and changeset functionalities are available. 428 429 ## Working with typespecs 430 431 Generating typespecs for schemas is out of the scope of `Ecto.Schema`. 432 433 In order to be able to use types such as `User.t()`, `t/0` has to be defined manually: 434 435 defmodule User do 436 use Ecto.Schema 437 438 @type t :: %__MODULE__{ 439 name: String.t(), 440 age: non_neg_integer() 441 } 442 443 # ... schema ... 444 end 445 446 Defining the type of each field is not mandatory, but it is preferable. 447 """ 448 449 alias Ecto.Schema.Metadata 450 451 @type source :: String.t 452 @type prefix :: String.t | nil 453 @type schema :: %{optional(atom) => any, __struct__: atom, __meta__: Metadata.t} 454 @type embedded_schema :: %{optional(atom) => any, __struct__: atom} 455 @type t :: schema | embedded_schema 456 @type belongs_to(t) :: t | Ecto.Association.NotLoaded.t() 457 @type has_one(t) :: t | Ecto.Association.NotLoaded.t() 458 @type has_many(t) :: [t] | Ecto.Association.NotLoaded.t() 459 @type many_to_many(t) :: [t] | Ecto.Association.NotLoaded.t() 460 @type embeds_one(t) :: t 461 @type embeds_many(t) :: [t] 462 463 @doc false 464 defmacro __using__(_) do 465 quote do 466 import Ecto.Schema, only: [schema: 2, embedded_schema: 1] 467 468 @primary_key nil 469 @timestamps_opts [] 470 @foreign_key_type :id 471 @schema_prefix nil 472 @schema_context nil 473 @field_source_mapper fn x -> x end 474 475 Module.register_attribute(__MODULE__, :ecto_primary_keys, accumulate: true) 476 Module.register_attribute(__MODULE__, :ecto_fields, accumulate: true) 477 Module.register_attribute(__MODULE__, :ecto_virtual_fields, accumulate: true) 478 Module.register_attribute(__MODULE__, :ecto_query_fields, accumulate: true) 479 Module.register_attribute(__MODULE__, :ecto_field_sources, accumulate: true) 480 Module.register_attribute(__MODULE__, :ecto_assocs, accumulate: true) 481 Module.register_attribute(__MODULE__, :ecto_embeds, accumulate: true) 482 Module.register_attribute(__MODULE__, :ecto_raw, accumulate: true) 483 Module.register_attribute(__MODULE__, :ecto_autogenerate, accumulate: true) 484 Module.register_attribute(__MODULE__, :ecto_autoupdate, accumulate: true) 485 Module.register_attribute(__MODULE__, :ecto_redact_fields, accumulate: true) 486 Module.put_attribute(__MODULE__, :ecto_derive_inspect_for_redacted_fields, true) 487 Module.put_attribute(__MODULE__, :ecto_autogenerate_id, nil) 488 end 489 end 490 491 @field_opts [ 492 :default, 493 :source, 494 :autogenerate, 495 :read_after_writes, 496 :virtual, 497 :primary_key, 498 :load_in_query, 499 :redact, 500 :foreign_key, 501 :on_replace, 502 :defaults, 503 :type, 504 :where, 505 :references, 506 :skip_default_validation 507 ] 508 509 @doc """ 510 Defines an embedded schema with the given field definitions. 511 512 An embedded schema is either embedded into another 513 schema or kept exclusively in memory. For this reason, 514 an embedded schema does not require a source name and 515 it does not include a metadata field. 516 517 Embedded schemas by default set the primary key type 518 to `:binary_id` but such can be configured with the 519 `@primary_key` attribute. 520 """ 521 defmacro embedded_schema([do: block]) do 522 schema(__CALLER__, nil, false, :binary_id, block) 523 end 524 525 @doc """ 526 Defines a schema struct with a source name and field definitions. 527 528 An additional field called `__meta__` is added to the struct for storing 529 internal Ecto state. This field always has a `Ecto.Schema.Metadata` struct 530 as value and can be manipulated with the `Ecto.put_meta/2` function. 531 """ 532 defmacro schema(source, [do: block]) do 533 schema(__CALLER__, source, true, :id, block) 534 end 535 536 defp schema(caller, source, meta?, type, block) do 537 prelude = 538 quote do 539 if line = Module.get_attribute(__MODULE__, :ecto_schema_defined) do 540 raise "schema already defined for #{inspect(__MODULE__)} on line #{line}" 541 end 542 543 @ecto_schema_defined unquote(caller.line) 544 545 @after_compile Ecto.Schema 546 Module.register_attribute(__MODULE__, :ecto_changeset_fields, accumulate: true) 547 Module.register_attribute(__MODULE__, :ecto_struct_fields, accumulate: true) 548 549 meta? = unquote(meta?) 550 source = unquote(source) 551 prefix = @schema_prefix 552 context = @schema_context 553 554 # Those module attributes are accessed only dynamically 555 # so we explicitly reference them here to avoid warnings. 556 _ = @foreign_key_type 557 _ = @timestamps_opts 558 559 if meta? do 560 unless is_binary(source) do 561 raise ArgumentError, "schema source must be a string, got: #{inspect source}" 562 end 563 564 meta = %Metadata{ 565 state: :built, 566 source: source, 567 prefix: prefix, 568 context: context, 569 schema: __MODULE__ 570 } 571 572 Module.put_attribute(__MODULE__, :ecto_struct_fields, {:__meta__, meta}) 573 end 574 575 if @primary_key == nil do 576 @primary_key {:id, unquote(type), autogenerate: true} 577 end 578 579 primary_key_fields = 580 case @primary_key do 581 false -> 582 [] 583 {name, type, opts} -> 584 Ecto.Schema.__field__(__MODULE__, name, type, [primary_key: true] ++ opts) 585 [name] 586 other -> 587 raise ArgumentError, "@primary_key must be false or {name, type, opts}" 588 end 589 590 try do 591 import Ecto.Schema 592 unquote(block) 593 after 594 :ok 595 end 596 end 597 598 postlude = 599 quote unquote: false do 600 primary_key_fields = @ecto_primary_keys |> Enum.reverse 601 autogenerate = @ecto_autogenerate |> Enum.reverse 602 autoupdate = @ecto_autoupdate |> Enum.reverse 603 fields = @ecto_fields |> Enum.reverse 604 query_fields = @ecto_query_fields |> Enum.reverse 605 virtual_fields = @ecto_virtual_fields |> Enum.reverse 606 field_sources = @ecto_field_sources |> Enum.reverse 607 assocs = @ecto_assocs |> Enum.reverse 608 embeds = @ecto_embeds |> Enum.reverse 609 redacted_fields = @ecto_redact_fields 610 loaded = Ecto.Schema.__loaded__(__MODULE__, @ecto_struct_fields) 611 612 if redacted_fields != [] and not List.keymember?(@derive, Inspect, 0) and 613 @ecto_derive_inspect_for_redacted_fields do 614 @derive {Inspect, except: @ecto_redact_fields} 615 end 616 617 defstruct Enum.reverse(@ecto_struct_fields) 618 619 def __changeset__ do 620 %{unquote_splicing(Macro.escape(@ecto_changeset_fields))} 621 end 622 623 def __schema__(:prefix), do: unquote(prefix) 624 def __schema__(:source), do: unquote(source) 625 def __schema__(:fields), do: unquote(Enum.map(fields, &elem(&1, 0))) 626 def __schema__(:query_fields), do: unquote(Enum.map(query_fields, &elem(&1, 0))) 627 def __schema__(:primary_key), do: unquote(primary_key_fields) 628 def __schema__(:hash), do: unquote(:erlang.phash2({primary_key_fields, query_fields})) 629 def __schema__(:read_after_writes), do: unquote(Enum.reverse(@ecto_raw)) 630 def __schema__(:autogenerate_id), do: unquote(Macro.escape(@ecto_autogenerate_id)) 631 def __schema__(:autogenerate), do: unquote(Macro.escape(autogenerate)) 632 def __schema__(:autoupdate), do: unquote(Macro.escape(autoupdate)) 633 def __schema__(:loaded), do: unquote(Macro.escape(loaded)) 634 def __schema__(:redact_fields), do: unquote(redacted_fields) 635 def __schema__(:virtual_fields), do: unquote(Enum.map(virtual_fields, &elem(&1, 0))) 636 637 def __schema__(:query) do 638 %Ecto.Query{ 639 from: %Ecto.Query.FromExpr{ 640 source: {unquote(source), __MODULE__}, 641 prefix: unquote(prefix) 642 } 643 } 644 end 645 646 for clauses <- Ecto.Schema.__schema__(fields, field_sources, assocs, embeds, virtual_fields), 647 {args, body} <- clauses do 648 def __schema__(unquote_splicing(args)), do: unquote(body) 649 end 650 end 651 652 quote do 653 unquote(prelude) 654 unquote(postlude) 655 end 656 end 657 658 ## API 659 660 @doc """ 661 Defines a field on the schema with given name and type. 662 663 The field name will be used as is to read and write to the database 664 by all of the built-in adapters unless overridden with the `:source` 665 option. 666 667 ## Options 668 669 * `:default` - Sets the default value on the schema and the struct. 670 671 The default value is calculated at compilation time, so don't use 672 expressions like `DateTime.utc_now` or `Ecto.UUID.generate` as 673 they would then be the same for all records: in this scenario you can use 674 the `:autogenerate` option to generate at insertion time. 675 676 The default value is validated against the field's type at compilation time 677 and it will raise an ArgumentError if there is a type mismatch. If you cannot 678 infer the field's type at compilation time, you can use the 679 `:skip_default_validation` option on the field to skip validations. 680 681 Once a default value is set, if you send changes to the changeset that 682 contains the same value defined as default, validations will not be performed 683 since there are no changes after all. 684 685 * `:source` - Defines the name that is to be used in database for this field. 686 This is useful when attaching to an existing database. The value should be 687 an atom. 688 689 * `:autogenerate` - a `{module, function, args}` tuple for a function 690 to call to generate the field value before insertion if value is not set. 691 A shorthand value of `true` is equivalent to `{type, :autogenerate, []}`. 692 693 * `:read_after_writes` - When true, the field is always read back 694 from the database after insert and updates. 695 696 For relational databases, this means the RETURNING option of those 697 statements is used. For this reason, MySQL does not support this 698 option and will raise an error if a schema is inserted/updated with 699 read after writes fields. 700 701 * `:virtual` - When true, the field is not persisted to the database. 702 Notice virtual fields do not support `:autogenerate` nor 703 `:read_after_writes`. 704 705 * `:primary_key` - When true, the field is used as part of the 706 composite primary key. 707 708 * `:load_in_query` - When false, the field will not be loaded when 709 selecting the whole struct in a query, such as `from p in Post, select: p`. 710 Defaults to `true`. 711 712 * `:redact` - When true, it will display a value of `**redacted**` 713 when inspected in changes inside a `Ecto.Changeset` and be excluded 714 from inspect on the schema. Defaults to `false`. 715 716 * `:skip_default_validation` - When true, it will skip the type validation 717 step at compile time. 718 719 """ 720 defmacro field(name, type \\ :string, opts \\ []) do 721 quote do 722 Ecto.Schema.__field__(__MODULE__, unquote(name), unquote(type), unquote(opts)) 723 end 724 end 725 726 @doc """ 727 Generates `:inserted_at` and `:updated_at` timestamp fields. 728 729 The fields generated by this macro will automatically be set to 730 the current time when inserting and updating values in a repository. 731 732 ## Options 733 734 * `:inserted_at` - the Ecto schema name of the field for insertion times or `false` 735 * `:updated_at` - the Ecto schema name of the field for update times or `false` 736 * `:inserted_at_source` - the name of the database column for insertion times or `false` 737 * `:updated_at_source` - the name of the database column for update times or `false` 738 * `:type` - the timestamps type, defaults to `:naive_datetime`. 739 * `:autogenerate` - a module-function-args tuple used for generating 740 both `inserted_at` and `updated_at` timestamps 741 742 All options can be pre-configured by setting `@timestamps_opts`. 743 """ 744 defmacro timestamps(opts \\ []) do 745 quote bind_quoted: binding() do 746 timestamps = Keyword.merge(@timestamps_opts, opts) 747 748 type = Keyword.get(timestamps, :type, :naive_datetime) 749 autogen = timestamps[:autogenerate] || {Ecto.Schema, :__timestamps__, [type]} 750 751 inserted_at = Keyword.get(timestamps, :inserted_at, :inserted_at) 752 updated_at = Keyword.get(timestamps, :updated_at, :updated_at) 753 754 if inserted_at do 755 opts = if source = timestamps[:inserted_at_source], do: [source: source], else: [] 756 Ecto.Schema.field(inserted_at, type, opts) 757 end 758 759 if updated_at do 760 opts = if source = timestamps[:updated_at_source], do: [source: source], else: [] 761 Ecto.Schema.field(updated_at, type, opts) 762 Module.put_attribute(__MODULE__, :ecto_autoupdate, {[updated_at], autogen}) 763 end 764 765 with [_ | _] = fields <- Enum.filter([inserted_at, updated_at], & &1) do 766 Module.put_attribute(__MODULE__, :ecto_autogenerate, {fields, autogen}) 767 end 768 769 :ok 770 end 771 end 772 773 @doc ~S""" 774 Indicates a one-to-many association with another schema. 775 776 The current schema has zero or more records of the other schema. The other 777 schema often has a `belongs_to` field with the reverse association. 778 779 ## Options 780 781 * `:foreign_key` - Sets the foreign key, this should map to a field on the 782 other schema, defaults to the underscored name of the current schema 783 suffixed by `_id` 784 785 * `:references` - Sets the key on the current schema to be used for the 786 association, defaults to the primary key on the schema 787 788 * `:through` - Allow this association to be defined in terms of existing 789 associations. Read the section on `:through` associations for more info 790 791 * `:on_delete` - The action taken on associations when parent record 792 is deleted. May be `:nothing` (default), `:nilify_all` and `:delete_all`. 793 Using this option is DISCOURAGED for most relational databases. Instead, 794 in your migration, set `references(:parent_id, on_delete: :delete_all)`. 795 Opposite to the migration option, this option cannot guarantee integrity 796 and it is only triggered for `c:Ecto.Repo.delete/2` (and not on 797 `c:Ecto.Repo.delete_all/2`) and it never cascades. If posts has many comments, 798 which has many tags, and you delete a post, only comments will be deleted. 799 If your database does not support references, cascading can be manually 800 implemented by using `Ecto.Multi` or `Ecto.Changeset.prepare_changes/2`. 801 802 * `:on_replace` - The action taken on associations when the record is 803 replaced when casting or manipulating parent changeset. May be 804 `:raise` (default), `:mark_as_invalid`, `:nilify`, `:delete` or 805 `:delete_if_exists`. See `Ecto.Changeset`'s section about `:on_replace` for 806 more info. 807 808 * `:defaults` - Default values to use when building the association. 809 It may be a keyword list of options that override the association schema 810 or a atom/`{module, function, args}` that receives the struct and the owner as 811 arguments. For example, if you set `Post.has_many :comments, defaults: [public: true]`, 812 then when using `Ecto.build_assoc(post, :comments)`, the comment will have 813 `comment.public == true`. Alternatively, you can set it to 814 `Post.has_many :comments, defaults: :update_comment`, which will invoke 815 `Post.update_comment(comment, post)`, or set it to a MFA tuple such as 816 `{Mod, fun, [arg3, arg4]}`, which will invoke `Mod.fun(comment, post, arg3, arg4)` 817 818 * `:where` - A filter for the association. See "Filtering associations" below. 819 It does not apply to `:through` associations. 820 821 * `:preload_order` - Sets the default `order_by` of the association. 822 It is used when the association is preloaded. 823 For example, if you set `Post.has_many :comments, preload_order: [asc: :content]`, 824 whenever the `:comments` associations is preloaded, 825 the comments will be order by the `:content` field. 826 See `Ecto.Query.order_by/3` for more examples. 827 828 ## Examples 829 830 defmodule Post do 831 use Ecto.Schema 832 schema "posts" do 833 has_many :comments, Comment 834 end 835 end 836 837 # Get all comments for a given post 838 post = Repo.get(Post, 42) 839 comments = Repo.all assoc(post, :comments) 840 841 # The comments can come preloaded on the post struct 842 [post] = Repo.all(from(p in Post, where: p.id == 42, preload: :comments)) 843 post.comments #=> [%Comment{...}, ...] 844 845 `has_many` can be used to define hierarchical relationships within a single 846 schema, for example threaded comments. 847 848 defmodule Comment do 849 use Ecto.Schema 850 schema "comments" do 851 field :content, :string 852 field :parent_id, :integer 853 belongs_to :parent, Comment, foreign_key: :parent_id, references: :id, define_field: false 854 has_many :children, Comment, foreign_key: :parent_id, references: :id 855 end 856 end 857 858 ## Filtering associations 859 860 It is possible to specify a `:where` option that will filter the records 861 returned by the association. Querying, joining or preloading the association 862 will use the given conditions as shown next: 863 864 defmodule Post do 865 use Ecto.Schema 866 867 schema "posts" do 868 has_many :public_comments, Comment, 869 where: [public: true] 870 end 871 end 872 873 The `:where` option expects a keyword list where the key is an atom 874 representing the field and the value is either: 875 876 * `nil` - which specifies the field must be nil 877 * `{:not, nil}` - which specifies the field must not be nil 878 * `{:in, list}` - which specifies the field must be one of the values in a list 879 * `{:fragment, expr}` - which specifies a fragment string as the filter 880 (see `Ecto.Query.API.fragment/1`) with the field's value given to it 881 as the only argument 882 * or any other value which the field is compared directly against 883 884 Note the values above are distinctly different from the values you 885 would pass to `where` when building a query. For example, if you 886 attempt to build a query such as 887 888 from Post, where: [id: nil] 889 890 it will emit an error. This is because queries can be built dynamically, 891 and therefore passing `nil` can lead to security errors. However, the 892 `:where` values for an association are given at compile-time, which is 893 less dynamic and cannot leverage the full power of Ecto queries, which 894 explains why they have different APIs. 895 896 **Important!** Please use this feature only when strictly necessary, 897 otherwise it is very easy to end-up with large schemas with dozens of 898 different associations polluting your schema and affecting your 899 application performance. For instance, if you are using associations 900 only for different querying purposes, then it is preferable to build 901 and compose queries. For instance, instead of having two associations, 902 one for comments and another for deleted comments, you might have 903 a single comments association and filter it instead: 904 905 posts 906 |> Ecto.assoc(:comments) 907 |> Comment.deleted() 908 909 Or when preloading: 910 911 from posts, preload: [comments: ^Comment.deleted()] 912 913 ## has_many/has_one :through 914 915 Ecto also supports defining associations in terms of other associations 916 via the `:through` option. Let's see an example: 917 918 defmodule Post do 919 use Ecto.Schema 920 921 schema "posts" do 922 has_many :comments, Comment 923 has_one :permalink, Permalink 924 925 # In the has_many :through example below, the `:comments` 926 # in the list [:comments, :author] refers to the 927 # `has_many :comments` in the Post own schema and the 928 # `:author` refers to the `belongs_to :author` of the 929 # Comment's schema (the module below). 930 # (see the description below for more details) 931 has_many :comments_authors, through: [:comments, :author] 932 933 # Specify the association with custom source 934 has_many :tags, {"posts_tags", Tag} 935 end 936 end 937 938 defmodule Comment do 939 use Ecto.Schema 940 941 schema "comments" do 942 belongs_to :author, Author 943 belongs_to :post, Post 944 has_one :post_permalink, through: [:post, :permalink] 945 end 946 end 947 948 In the example above, we have defined a `has_many :through` association 949 named `:comments_authors`. A `:through` association always expects a list 950 and the first element of the list must be a previously defined association 951 in the current module. For example, `:comments_authors` first points to 952 `:comments` in the same module (Post), which then points to `:author` in 953 the next schema, `Comment`. 954 955 This `:through` association will return all authors for all comments 956 that belongs to that post: 957 958 # Get all comments authors for a given post 959 post = Repo.get(Post, 42) 960 authors = Repo.all assoc(post, :comments_authors) 961 962 `:through` associations can also be preloaded. In such cases, not only 963 the `:through` association is preloaded but all intermediate steps are 964 preloaded too: 965 966 [post] = Repo.all(from(p in Post, where: p.id == 42, preload: :comments_authors)) 967 post.comments_authors #=> [%Author{...}, ...] 968 969 # The comments for each post will be preloaded too 970 post.comments #=> [%Comment{...}, ...] 971 972 # And the author for each comment too 973 hd(post.comments).author #=> %Author{...} 974 975 When the `:through` association is expected to return one or zero items, 976 `has_one :through` should be used instead, as in the example at the beginning 977 of this section: 978 979 # How we defined the association above 980 has_one :post_permalink, through: [:post, :permalink] 981 982 # Get a preloaded comment 983 [comment] = Repo.all(Comment) |> Repo.preload(:post_permalink) 984 comment.post_permalink #=> %Permalink{...} 985 986 Note `:through` associations are read-only. For example, you cannot use 987 `Ecto.Changeset.cast_assoc/3` to modify through associations. 988 """ 989 defmacro has_many(name, queryable, opts \\ []) do 990 queryable = expand_alias(queryable, __CALLER__) 991 quote do 992 Ecto.Schema.__has_many__(__MODULE__, unquote(name), unquote(queryable), unquote(opts)) 993 end 994 end 995 996 @doc ~S""" 997 Indicates a one-to-one association with another schema. 998 999 The current schema has zero or one records of the other schema. The other 1000 schema often has a `belongs_to` field with the reverse association. 1001 1002 ## Options 1003 1004 * `:foreign_key` - Sets the foreign key, this should map to a field on the 1005 other schema, defaults to the underscored name of the current module 1006 suffixed by `_id` 1007 1008 * `:references` - Sets the key on the current schema to be used for the 1009 association, defaults to the primary key on the schema 1010 1011 * `:through` - If this association must be defined in terms of existing 1012 associations. Read the section in `has_many/3` for more information 1013 1014 * `:on_delete` - The action taken on associations when parent record 1015 is deleted. May be `:nothing` (default), `:nilify_all` and `:delete_all`. 1016 Using this option is DISCOURAGED for most relational databases. Instead, 1017 in your migration, set `references(:parent_id, on_delete: :delete_all)`. 1018 Opposite to the migration option, this option cannot guarantee integrity 1019 and it is only triggered for `c:Ecto.Repo.delete/2` (and not on 1020 `c:Ecto.Repo.delete_all/2`) and it never cascades. If posts has many comments, 1021 which has many tags, and you delete a post, only comments will be deleted. 1022 If your database does not support references, cascading can be manually 1023 implemented by using `Ecto.Multi` or `Ecto.Changeset.prepare_changes/2` 1024 1025 * `:on_replace` - The action taken on associations when the record is 1026 replaced when casting or manipulating parent changeset. May be 1027 `:raise` (default), `:mark_as_invalid`, `:nilify`, `:update`, or 1028 `:delete`. See `Ecto.Changeset`'s section on related data for more info. 1029 1030 * `:defaults` - Default values to use when building the association. 1031 It may be a keyword list of options that override the association schema 1032 or as a atom/`{module, function, args}` that receives the struct and the 1033 owner as arguments. For example, if you set `Post.has_one :banner, defaults: [public: true]`, 1034 then when using `Ecto.build_assoc(post, :banner)`, the banner will have 1035 `banner.public == true`. Alternatively, you can set it to 1036 `Post.has_one :banner, defaults: :update_banner`, which will invoke 1037 `Post.update_banner(banner, post)`, or set it to a MFA tuple such as 1038 `{Mod, fun, [arg3, arg4]}`, which will invoke `Mod.fun(banner, post, arg3, arg4)` 1039 1040 * `:where` - A filter for the association. See "Filtering associations" 1041 in `has_many/3`. It does not apply to `:through` associations. 1042 1043 ## Examples 1044 1045 defmodule Post do 1046 use Ecto.Schema 1047 1048 schema "posts" do 1049 has_one :permalink, Permalink 1050 1051 # Specify the association with custom source 1052 has_one :category, {"posts_categories", Category} 1053 end 1054 end 1055 1056 # The permalink can come preloaded on the post struct 1057 [post] = Repo.all(from(p in Post, where: p.id == 42, preload: :permalink)) 1058 post.permalink #=> %Permalink{...} 1059 """ 1060 defmacro has_one(name, queryable, opts \\ []) do 1061 queryable = expand_alias(queryable, __CALLER__) 1062 quote do 1063 Ecto.Schema.__has_one__(__MODULE__, unquote(name), unquote(queryable), unquote(opts)) 1064 end 1065 end 1066 1067 @doc ~S""" 1068 Indicates a one-to-one or many-to-one association with another schema. 1069 1070 The current schema belongs to zero or one records of the other schema. The other 1071 schema often has a `has_one` or a `has_many` field with the reverse association. 1072 1073 You should use `belongs_to` in the table that contains the foreign key. Imagine 1074 a company <-> employee relationship. If the employee contains the `company_id` in 1075 the underlying database table, we say the employee belongs to company. 1076 1077 In fact, when you invoke this macro, a field with the name of foreign key is 1078 automatically defined in the schema for you. 1079 1080 ## Options 1081 1082 * `:foreign_key` - Sets the foreign key field name, defaults to the name 1083 of the association suffixed by `_id`. For example, `belongs_to :company` 1084 will define foreign key of `:company_id`. The associated `has_one` or `has_many` 1085 field in the other schema should also have its `:foreign_key` option set 1086 with the same value. 1087 1088 * `:references` - Sets the key on the other schema to be used for the 1089 association, defaults to: `:id` 1090 1091 * `:define_field` - When false, does not automatically define a `:foreign_key` 1092 field, implying the user is defining the field manually elsewhere 1093 1094 * `:type` - Sets the type of automatically defined `:foreign_key`. 1095 Defaults to: `:integer` and can be set per schema via `@foreign_key_type` 1096 1097 * `:on_replace` - The action taken on associations when the record is 1098 replaced when casting or manipulating parent changeset. May be 1099 `:raise` (default), `:mark_as_invalid`, `:nilify`, `:update`, or `:delete`. 1100 See `Ecto.Changeset`'s section on related data for more info. 1101 1102 * `:defaults` - Default values to use when building the association. 1103 It may be a keyword list of options that override the association schema 1104 or a atom/`{module, function, args}` that receives the struct and the owner as 1105 arguments. For example, if you set `Comment.belongs_to :post, defaults: [public: true]`, 1106 then when using `Ecto.build_assoc(comment, :post)`, the post will have 1107 `post.public == true`. Alternatively, you can set it to 1108 `Comment.belongs_to :post, defaults: :update_post`, which will invoke 1109 `Comment.update_post(post, comment)`, or set it to a MFA tuple such as 1110 `{Mod, fun, [arg3, arg4]}`, which will invoke `Mod.fun(post, comment, arg3, arg4)` 1111 1112 * `:primary_key` - If the underlying belongs_to field is a primary key 1113 1114 * `:source` - Defines the name that is to be used in database for this field 1115 1116 * `:where` - A filter for the association. See "Filtering associations" 1117 in `has_many/3`. 1118 1119 ## Examples 1120 1121 defmodule Comment do 1122 use Ecto.Schema 1123 1124 schema "comments" do 1125 belongs_to :post, Post 1126 end 1127 end 1128 1129 # The post can come preloaded on the comment record 1130 [comment] = Repo.all(from(c in Comment, where: c.id == 42, preload: :post)) 1131 comment.post #=> %Post{...} 1132 1133 If you need custom options on the underlying field, you can define the 1134 field explicitly and then pass `define_field: false` to `belongs_to`: 1135 1136 defmodule Comment do 1137 use Ecto.Schema 1138 1139 schema "comments" do 1140 field :post_id, :integer, ... # custom options 1141 belongs_to :post, Post, define_field: false 1142 end 1143 end 1144 1145 ## Polymorphic associations 1146 1147 One common use case for belongs to associations is to handle 1148 polymorphism. For example, imagine you have defined a Comment 1149 schema and you wish to use it for commenting on both tasks and 1150 posts. 1151 1152 Some abstractions would force you to define some sort of 1153 polymorphic association with two fields in your database: 1154 1155 * commentable_type 1156 * commentable_id 1157 1158 The problem with this approach is that it breaks references in 1159 the database. You can't use foreign keys and it is very inefficient, 1160 both in terms of query time and storage. 1161 1162 In Ecto, we have three ways to solve this issue. The simplest 1163 is to define multiple fields in the Comment schema, one for each 1164 association: 1165 1166 * task_id 1167 * post_id 1168 1169 Unless you have dozens of columns, this is simpler for the developer, 1170 more DB friendly and more efficient in all aspects. 1171 1172 Alternatively, because Ecto does not tie a schema to a given table, 1173 we can use separate tables for each association. Let's start over 1174 and define a new Comment schema: 1175 1176 defmodule Comment do 1177 use Ecto.Schema 1178 1179 schema "abstract table: comments" do 1180 # This will be used by associations on each "concrete" table 1181 field :assoc_id, :integer 1182 end 1183 end 1184 1185 Notice we have changed the table name to "abstract table: comments". 1186 You can choose whatever name you want, the point here is that this 1187 particular table will never exist. 1188 1189 Now in your Post and Task schemas: 1190 1191 defmodule Post do 1192 use Ecto.Schema 1193 1194 schema "posts" do 1195 has_many :comments, {"posts_comments", Comment}, foreign_key: :assoc_id 1196 end 1197 end 1198 1199 defmodule Task do 1200 use Ecto.Schema 1201 1202 schema "tasks" do 1203 has_many :comments, {"tasks_comments", Comment}, foreign_key: :assoc_id 1204 end 1205 end 1206 1207 Now each association uses its own specific table, "posts_comments" 1208 and "tasks_comments", which must be created on migrations. The 1209 advantage of this approach is that we never store unrelated data 1210 together, also ensuring we keep database references fast and correct. 1211 1212 When using this technique, the only limitation is that you cannot 1213 build comments directly. For example, the command below 1214 1215 Repo.insert!(%Comment{}) 1216 1217 will attempt to use the abstract table. Instead, one should use 1218 1219 Repo.insert!(build_assoc(post, :comments)) 1220 1221 leveraging the `Ecto.build_assoc/3` function. You can also 1222 use `Ecto.assoc/2` or pass a tuple in the query syntax 1223 to easily retrieve associated comments to a given post or 1224 task: 1225 1226 # Fetch all comments associated with the given task 1227 Repo.all(Ecto.assoc(task, :comments)) 1228 1229 Or all comments in a given table: 1230 1231 Repo.all from(c in {"posts_comments", Comment}), ...) 1232 1233 The third and final option is to use `many_to_many/3` to 1234 define the relationships between the resources. In this case, 1235 the comments table won't have the foreign key, instead there 1236 is an intermediary table responsible for associating the entries: 1237 1238 defmodule Comment do 1239 use Ecto.Schema 1240 schema "comments" do 1241 # ... 1242 end 1243 end 1244 1245 In your posts and tasks: 1246 1247 defmodule Post do 1248 use Ecto.Schema 1249 1250 schema "posts" do 1251 many_to_many :comments, Comment, join_through: "posts_comments" 1252 end 1253 end 1254 1255 defmodule Task do 1256 use Ecto.Schema 1257 1258 schema "tasks" do 1259 many_to_many :comments, Comment, join_through: "tasks_comments" 1260 end 1261 end 1262 1263 See `many_to_many/3` for more information on this particular approach. 1264 """ 1265 defmacro belongs_to(name, queryable, opts \\ []) do 1266 queryable = expand_alias(queryable, __CALLER__) 1267 quote do 1268 Ecto.Schema.__belongs_to__(__MODULE__, unquote(name), unquote(queryable), unquote(opts)) 1269 end 1270 end 1271 1272 @doc ~S""" 1273 Indicates a many-to-many association with another schema. 1274 1275 The association happens through a join schema or source, containing 1276 foreign keys to the associated schemas. For example, the association 1277 below: 1278 1279 # from MyApp.Post 1280 many_to_many :tags, MyApp.Tag, join_through: "posts_tags" 1281 1282 is backed by relational databases through a join table as follows: 1283 1284 [Post] <-> [posts_tags] <-> [Tag] 1285 id <-- post_id 1286 tag_id --> id 1287 1288 More information on the migration for creating such a schema is shown 1289 below. 1290 1291 ## Options 1292 1293 * `:join_through` - Specifies the source of the associated data. 1294 It may be a string, like "posts_tags", representing the 1295 underlying storage table or an atom, like `MyApp.PostTag`, 1296 representing a schema. This option is required. 1297 1298 * `:join_keys` - Specifies how the schemas are associated. It 1299 expects a keyword list with two entries, the first being how 1300 the join table should reach the current schema and the second 1301 how the join table should reach the associated schema. In the 1302 example above, it defaults to: `[post_id: :id, tag_id: :id]`. 1303 The keys are inflected from the schema names. 1304 1305 * `:on_delete` - The action taken on associations when the parent record 1306 is deleted. May be `:nothing` (default) or `:delete_all`. 1307 Using this option is DISCOURAGED for most relational databases. Instead, 1308 in your migration, set `references(:parent_id, on_delete: :delete_all)`. 1309 Opposite to the migration option, this option cannot guarantee integrity 1310 and it is only triggered for `c:Ecto.Repo.delete/2` (and not on 1311 `c:Ecto.Repo.delete_all/2`). This option can only remove data from the 1312 join source, never the associated records, and it never cascades. 1313 1314 * `:on_replace` - The action taken on associations when the record is 1315 replaced when casting or manipulating parent changeset. May be 1316 `:raise` (default), `:mark_as_invalid`, or `:delete`. 1317 `:delete` will only remove data from the join source, never the 1318 associated records. See `Ecto.Changeset`'s section on related data 1319 for more info. 1320 1321 * `:defaults` - Default values to use when building the association. 1322 It may be a keyword list of options that override the association schema 1323 or a atom/`{module, function, args}` that receives the struct and the owner as 1324 arguments. For example, if you set `Post.many_to_many :tags, defaults: [public: true]`, 1325 then when using `Ecto.build_assoc(post, :tags)`, the tag will have 1326 `tag.public == true`. Alternatively, you can set it to 1327 `Post.many_to_many :tags, defaults: :update_tag`, which will invoke 1328 `Post.update_tag(tag, post)`, or set it to a MFA tuple such as 1329 `{Mod, fun, [arg3, arg4]}`, which will invoke `Mod.fun(tag, post, arg3, arg4)` 1330 1331 * `:join_defaults` - The same as `:defaults` but it applies to the join schema 1332 instead. This option will raise if it is given and the `:join_through` value 1333 is not a schema. 1334 1335 * `:unique` - When true, checks if the associated entries are unique 1336 whenever the association is cast or changed via the parent record. 1337 For instance, it would verify that a given tag cannot be attached to 1338 the same post more than once. This exists mostly as a quick check 1339 for user feedback, as it does not guarantee uniqueness at the database 1340 level. Therefore, you should also set a unique index in the database 1341 join table, such as: `create unique_index(:posts_tags, [:post_id, :tag_id])` 1342 1343 * `:where` - A filter for the association. See "Filtering associations" 1344 in `has_many/3` 1345 1346 * `:join_where` - A filter for the join table. See "Filtering associations" 1347 in `has_many/3` 1348 1349 * `:preload_order` - Sets the default `order_by` of the association. 1350 It is used when the association is preloaded. 1351 For example, if you set `Post.many_to_many :tags, Tag, join_through: "posts_tags", preload_order: [asc: :foo]`, 1352 whenever the `:tags` associations is preloaded, the tags will be order by the `:foo` field. 1353 See `Ecto.Query.order_by/3` for more examples. 1354 1355 ## Using Ecto.assoc/2 1356 1357 One of the benefits of using `many_to_many` is that Ecto will avoid 1358 loading the intermediate whenever possible, making your queries more 1359 efficient. For this reason, developers should not refer to the join 1360 table of `many_to_many` in queries. The join table is accessible in 1361 few occasions, such as in `Ecto.assoc/2`. For example, if you do this: 1362 1363 post 1364 |> Ecto.assoc(:tags) 1365 |> where([t, _pt, p], p.public == t.public) 1366 1367 It may not work as expected because the `posts_tags` table may not be 1368 included in the query. You can address this problem in multiple ways. 1369 One option is to use `...`: 1370 1371 post 1372 |> Ecto.assoc(:tags) 1373 |> where([t, ..., p], p.public == t.public) 1374 1375 Another and preferred option is to rewrite to an explicit `join`, which 1376 leaves out the intermediate bindings as they are resolved only later on: 1377 1378 # keyword syntax 1379 from t in Tag, 1380 join: p in assoc(t, :post), on: p.id == ^post.id 1381 1382 # pipe syntax 1383 Tag 1384 |> join(:inner, [t], p in assoc(t, :post), on: p.id == ^post.id) 1385 1386 If you need to access the join table, then you likely want to use 1387 `has_many/3` with the `:through` option instead. 1388 1389 ## Removing data 1390 1391 If you attempt to remove associated `many_to_many` data, **Ecto will 1392 always remove data from the join schema and never from the target 1393 associations** be it by setting `:on_replace` to `:delete`, `:on_delete` 1394 to `:delete_all` or by using changeset functions such as 1395 `Ecto.Changeset.put_assoc/3`. For example, if a `Post` has a many to many 1396 relationship with `Tag`, setting `:on_delete` to `:delete_all` will 1397 only delete entries from the "posts_tags" table in case `Post` is 1398 deleted. 1399 1400 ## Migration 1401 1402 How your migration should be structured depends on the value you pass 1403 in `:join_through`. If `:join_through` is simply a string, representing 1404 a table, you may define a table without primary keys and you must not 1405 include any further columns, as those values won't be set by Ecto: 1406 1407 create table(:posts_tags, primary_key: false) do 1408 add :post_id, references(:posts) 1409 add :tag_id, references(:tags) 1410 end 1411 1412 However, if your `:join_through` is a schema, like `MyApp.PostTag`, your 1413 join table may be structured as any other table in your codebase, 1414 including timestamps: 1415 1416 create table(:posts_tags) do 1417 add :post_id, references(:posts) 1418 add :tag_id, references(:tags) 1419 timestamps() 1420 end 1421 1422 Because `:join_through` contains a schema, in such cases, autogenerated 1423 values and primary keys will be automatically handled by Ecto. 1424 1425 ## Examples 1426 1427 defmodule Post do 1428 use Ecto.Schema 1429 schema "posts" do 1430 many_to_many :tags, Tag, join_through: "posts_tags" 1431 end 1432 end 1433 1434 # Let's create a post and a tag 1435 post = Repo.insert!(%Post{}) 1436 tag = Repo.insert!(%Tag{name: "introduction"}) 1437 1438 # We can associate at any time post and tags together using changesets 1439 post 1440 |> Repo.preload(:tags) # Load existing data 1441 |> Ecto.Changeset.change() # Build the changeset 1442 |> Ecto.Changeset.put_assoc(:tags, [tag]) # Set the association 1443 |> Repo.update! 1444 1445 # In a later moment, we may get all tags for a given post 1446 post = Repo.get(Post, 42) 1447 tags = Repo.all(assoc(post, :tags)) 1448 1449 # The tags may also be preloaded on the post struct for reading 1450 [post] = Repo.all(from(p in Post, where: p.id == 42, preload: :tags)) 1451 post.tags #=> [%Tag{...}, ...] 1452 1453 ## Join Schema Example 1454 1455 You may prefer to use a join schema to handle many_to_many associations. The 1456 decoupled nature of Ecto allows us to create a "join" struct which 1457 `belongs_to` both sides of the many to many association. 1458 1459 In our example, a `User` has and belongs to many `Organization`s: 1460 1461 defmodule MyApp.Repo.Migrations.CreateUserOrganization do 1462 use Ecto.Migration 1463 1464 def change do 1465 create table(:users_organizations) do 1466 add :user_id, references(:users) 1467 add :organization_id, references(:organizations) 1468 1469 timestamps() 1470 end 1471 end 1472 end 1473 1474 defmodule UserOrganization do 1475 use Ecto.Schema 1476 1477 @primary_key false 1478 schema "users_organizations" do 1479 belongs_to :user, User 1480 belongs_to :organization, Organization 1481 timestamps() # Added bonus, a join schema will also allow you to set timestamps 1482 end 1483 1484 def changeset(struct, params \\ %{}) do 1485 struct 1486 |> Ecto.Changeset.cast(params, [:user_id, :organization_id]) 1487 |> Ecto.Changeset.validate_required([:user_id, :organization_id]) 1488 # Maybe do some counter caching here! 1489 end 1490 end 1491 1492 defmodule User do 1493 use Ecto.Schema 1494 1495 schema "users" do 1496 many_to_many :organizations, Organization, join_through: UserOrganization 1497 end 1498 end 1499 1500 defmodule Organization do 1501 use Ecto.Schema 1502 1503 schema "organizations" do 1504 many_to_many :users, User, join_through: UserOrganization 1505 end 1506 end 1507 1508 # Then to create the association, pass in the ID's of an existing 1509 # User and Organization to UserOrganization.changeset 1510 changeset = UserOrganization.changeset(%UserOrganization{}, %{user_id: id, organization_id: id}) 1511 1512 case Repo.insert(changeset) do 1513 {:ok, assoc} -> # Assoc was created! 1514 {:error, changeset} -> # Handle the error 1515 end 1516 """ 1517 defmacro many_to_many(name, queryable, opts \\ []) do 1518 queryable = expand_alias(queryable, __CALLER__) 1519 opts = expand_alias_in_key(opts, :join_through, __CALLER__) 1520 1521 quote do 1522 Ecto.Schema.__many_to_many__(__MODULE__, unquote(name), unquote(queryable), unquote(opts)) 1523 end 1524 end 1525 1526 ## Embeds 1527 1528 @doc ~S""" 1529 Indicates an embedding of a schema. 1530 1531 The current schema has zero or one records of the other schema embedded 1532 inside of it. It uses a field similar to the `:map` type for storage, 1533 but allows embeds to have all the things regular schema can. 1534 1535 You must declare your `embeds_one/3` field with type `:map` at the 1536 database level. 1537 1538 The embedded may or may not have a primary key. Ecto uses the primary keys 1539 to detect if an embed is being updated or not. If a primary key is not present, 1540 `:on_replace` should be set to either `:update` or `:delete` if there is a 1541 desire to either update or delete the current embed when a new one is set. 1542 1543 ## Options 1544 1545 * `:on_replace` - The action taken on associations when the embed is 1546 replaced when casting or manipulating parent changeset. May be 1547 `:raise` (default), `:mark_as_invalid`, `:update`, or `:delete`. 1548 See `Ecto.Changeset`'s section on related data for more info. 1549 1550 * `:source` - Defines the name that is to be used in database for this field. 1551 This is useful when attaching to an existing database. The value should be 1552 an atom. 1553 1554 ## Examples 1555 1556 defmodule Order do 1557 use Ecto.Schema 1558 1559 schema "orders" do 1560 embeds_one :item, Item 1561 end 1562 end 1563 1564 defmodule Item do 1565 use Ecto.Schema 1566 1567 embedded_schema do 1568 field :title 1569 end 1570 end 1571 1572 # The item is loaded with the order 1573 order = Repo.get!(Order, 42) 1574 order.item #=> %Item{...} 1575 1576 Adding and removal of embeds can only be done via the `Ecto.Changeset` 1577 API so Ecto can properly track the embed life-cycle: 1578 1579 order = Repo.get!(Order, 42) 1580 item = %Item{title: "Soap"} 1581 1582 # Generate a changeset 1583 changeset = Ecto.Changeset.change(order) 1584 1585 # Put a new embed to the changeset 1586 changeset = Ecto.Changeset.put_embed(changeset, :item, item) 1587 1588 # Update the order, and fetch the item 1589 item = Repo.update!(changeset).item 1590 1591 # Item is generated with a unique identification 1592 item 1593 # => %Item{id: "20a97d94-f79b-4e63-a875-85deed7719b7", title: "Soap"} 1594 1595 ## Inline embedded schema 1596 1597 The schema module can be defined inline in the parent schema in simple 1598 cases: 1599 1600 defmodule Parent do 1601 use Ecto.Schema 1602 1603 schema "parents" do 1604 field :name, :string 1605 1606 embeds_one :child, Child do 1607 field :name, :string 1608 field :age, :integer 1609 end 1610 end 1611 end 1612 1613 Options should be passed before the `do` block like this: 1614 1615 embeds_one :child, Child, on_replace: :delete do 1616 field :name, :string 1617 field :age, :integer 1618 end 1619 1620 Primary keys are automatically set up for embedded schemas as well, 1621 defaulting to `{:id, :binary_id, autogenerate: true}`. You can 1622 customize it by passing a `:primary_key` option with the same arguments 1623 as `@primary_key` (see the [Schema attributes](https://hexdocs.pm/ecto/Ecto.Schema.html#module-schema-attributes) 1624 section for more info). 1625 1626 Defining embedded schema in such a way will define a `Parent.Child` module 1627 with the appropriate struct. In order to properly cast the embedded schema. 1628 When casting the inline-defined embedded schemas you need to use the `:with` 1629 option of `Ecto.Changeset.cast_embed/3` to provide the proper function to do the casting. 1630 For example: 1631 1632 def changeset(schema, params) do 1633 schema 1634 |> cast(params, [:name]) 1635 |> cast_embed(:child, with: &child_changeset/2) 1636 end 1637 1638 defp child_changeset(schema, params) do 1639 schema 1640 |> cast(params, [:name, :age]) 1641 end 1642 1643 ## Encoding and decoding 1644 1645 Because many databases do not support direct encoding and decoding 1646 of embeds, it is often emulated by Ecto by using specific encoding 1647 and decoding rules. 1648 1649 For example, PostgreSQL will store embeds on top of JSONB columns, 1650 which means types in embedded schemas won't go through the usual 1651 dump->DB->load cycle but rather encode->DB->decode->cast. This means 1652 that, when using embedded schemas with databases like PG or MySQL, 1653 make sure all of your types can be JSON encoded/decoded correctly. 1654 Ecto provides this guarantee for all built-in types. 1655 """ 1656 defmacro embeds_one(name, schema, opts \\ []) 1657 1658 defmacro embeds_one(name, schema, do: block) do 1659 quote do 1660 embeds_one(unquote(name), unquote(schema), [], do: unquote(block)) 1661 end 1662 end 1663 1664 defmacro embeds_one(name, schema, opts) do 1665 schema = expand_alias(schema, __CALLER__) 1666 quote do 1667 Ecto.Schema.__embeds_one__(__MODULE__, unquote(name), unquote(schema), unquote(opts)) 1668 end 1669 end 1670 1671 @doc """ 1672 Indicates an embedding of a schema. 1673 1674 For options and examples see documentation of `embeds_one/3`. 1675 """ 1676 defmacro embeds_one(name, schema, opts, do: block) do 1677 quote do 1678 {schema, opts} = Ecto.Schema.__embeds_module__(__ENV__, unquote(schema), unquote(opts), unquote(Macro.escape(block))) 1679 Ecto.Schema.__embeds_one__(__MODULE__, unquote(name), schema, opts) 1680 end 1681 end 1682 1683 @doc ~S""" 1684 Indicates an embedding of many schemas. 1685 1686 The current schema has zero or more records of the other schema embedded 1687 inside of it. Embeds have all the things regular schemas have. 1688 1689 It is recommended to declare your `embeds_many/3` field with type `:map` 1690 in your migrations, instead of using `{:array, :map}`. Ecto can work with 1691 both maps and arrays as the container for embeds (and in most databases 1692 maps are represented as JSON which allows Ecto to choose what works best). 1693 1694 The embedded may or may not have a primary key. Ecto uses the primary keys 1695 to detect if an embed is being updated or not. If a primary is not present 1696 and you still want the list of embeds to be updated, `:on_replace` must be 1697 set to `:delete`, forcing all current embeds to be deleted and replaced by 1698 new ones whenever a new list of embeds is set. 1699 1700 For encoding and decoding of embeds, please read the docs for 1701 `embeds_one/3`. 1702 1703 ## Options 1704 1705 * `:on_replace` - The action taken on associations when the embed is 1706 replaced when casting or manipulating parent changeset. May be 1707 `:raise` (default), `:mark_as_invalid`, or `:delete`. 1708 See `Ecto.Changeset`'s section on related data for more info. 1709 1710 * `:source` - Defines the name that is to be used in database for this field. 1711 This is useful when attaching to an existing database. The value should be 1712 an atom. 1713 1714 ## Examples 1715 1716 defmodule Order do 1717 use Ecto.Schema 1718 1719 schema "orders" do 1720 embeds_many :items, Item 1721 end 1722 end 1723 1724 defmodule Item do 1725 use Ecto.Schema 1726 1727 embedded_schema do 1728 field :title 1729 end 1730 end 1731 1732 # The items are loaded with the order 1733 order = Repo.get!(Order, 42) 1734 order.items #=> [%Item{...}, ...] 1735 1736 Adding and removal of embeds can only be done via the `Ecto.Changeset` 1737 API so Ecto can properly track the embed life-cycle: 1738 1739 # Order has no items 1740 order = Repo.get!(Order, 42) 1741 order.items 1742 # => [] 1743 1744 items = [%Item{title: "Soap"}] 1745 1746 # Generate a changeset 1747 changeset = Ecto.Changeset.change(order) 1748 1749 # Put a one or more new items 1750 changeset = Ecto.Changeset.put_embed(changeset, :items, items) 1751 1752 # Update the order and fetch items 1753 items = Repo.update!(changeset).items 1754 1755 # Items are generated with a unique identification 1756 items 1757 # => [%Item{id: "20a97d94-f79b-4e63-a875-85deed7719b7", title: "Soap"}] 1758 1759 Updating of embeds must be done using a changeset for each changed embed. 1760 1761 # Order has an existing items 1762 order = Repo.get!(Order, 42) 1763 order.items 1764 # => [%Item{id: "20a97d94-f79b-4e63-a875-85deed7719b7", title: "Soap"}] 1765 1766 # Generate a changeset 1767 changeset = Ecto.Changeset.change(order) 1768 1769 # Put the updated item as a changeset 1770 current_item = List.first(order.items) 1771 item_changeset = Ecto.Changeset.change(current_item, title: "Mujju's Soap") 1772 order_changeset = Ecto.Changeset.put_embed(changeset, :items, [item_changeset]) 1773 1774 # Update the order and fetch items 1775 items = Repo.update!(order_changeset).items 1776 1777 # Item has the updated title 1778 items 1779 # => [%Item{id: "20a97d94-f79b-4e63-a875-85deed7719b7", title: "Mujju's Soap"}] 1780 1781 ## Inline embedded schema 1782 1783 The schema module can be defined inline in the parent schema in simple 1784 cases: 1785 1786 defmodule Parent do 1787 use Ecto.Schema 1788 1789 schema "parents" do 1790 field :name, :string 1791 1792 embeds_many :children, Child do 1793 field :name, :string 1794 field :age, :integer 1795 end 1796 end 1797 end 1798 1799 Primary keys are automatically set up for embedded schemas as well, 1800 defaulting to `{:id, :binary_id, autogenerate: true}`. You can 1801 customize it by passing a `:primary_key` option with the same arguments 1802 as `@primary_key` (see the [Schema attributes](https://hexdocs.pm/ecto/Ecto.Schema.html#module-schema-attributes) 1803 section for more info). 1804 1805 Defining embedded schema in such a way will define a `Parent.Child` module 1806 with the appropriate struct. In order to properly cast the embedded schema. 1807 When casting the inline-defined embedded schemas you need to use the `:with` 1808 option of `cast_embed/3` to provide the proper function to do the casting. 1809 For example: 1810 1811 def changeset(schema, params) do 1812 schema 1813 |> cast(params, [:name]) 1814 |> cast_embed(:children, with: &child_changeset/2) 1815 end 1816 1817 defp child_changeset(schema, params) do 1818 schema 1819 |> cast(params, [:name, :age]) 1820 end 1821 1822 """ 1823 defmacro embeds_many(name, schema, opts \\ []) 1824 1825 defmacro embeds_many(name, schema, do: block) do 1826 quote do 1827 embeds_many(unquote(name), unquote(schema), [], do: unquote(block)) 1828 end 1829 end 1830 1831 defmacro embeds_many(name, schema, opts) do 1832 schema = expand_alias(schema, __CALLER__) 1833 quote do 1834 Ecto.Schema.__embeds_many__(__MODULE__, unquote(name), unquote(schema), unquote(opts)) 1835 end 1836 end 1837 1838 @doc """ 1839 Indicates an embedding of many schemas. 1840 1841 For options and examples see documentation of `embeds_many/3`. 1842 """ 1843 defmacro embeds_many(name, schema, opts, do: block) do 1844 quote do 1845 {schema, opts} = Ecto.Schema.__embeds_module__(__ENV__, unquote(schema), unquote(opts), unquote(Macro.escape(block))) 1846 Ecto.Schema.__embeds_many__(__MODULE__, unquote(name), schema, opts) 1847 end 1848 end 1849 1850 # Internal function for integrating associations into schemas. 1851 # 1852 # This function exists as an extension point for libraries to 1853 # experiment new types of associations to Ecto, although it may 1854 # break at any time (as with any of the association callbacks). 1855 # 1856 # This function expects the current schema, the association cardinality, 1857 # the association name, the association module (that implements 1858 # `Ecto.Association` callbacks) and a keyword list of options. 1859 @doc false 1860 @spec association(module, :one | :many, atom(), module, Keyword.t) :: Ecto.Association.t 1861 def association(schema, cardinality, name, association, opts) do 1862 not_loaded = %Ecto.Association.NotLoaded{ 1863 __owner__: schema, 1864 __field__: name, 1865 __cardinality__: cardinality 1866 } 1867 1868 put_struct_field(schema, name, not_loaded) 1869 opts = [cardinality: cardinality] ++ opts 1870 struct = association.struct(schema, name, opts) 1871 Module.put_attribute(schema, :ecto_assocs, {name, struct}) 1872 struct 1873 end 1874 1875 ## Callbacks 1876 1877 @doc false 1878 def __timestamps__(:naive_datetime) do 1879 %{NaiveDateTime.utc_now() | microsecond: {0, 0}} 1880 end 1881 1882 def __timestamps__(:naive_datetime_usec) do 1883 NaiveDateTime.utc_now() 1884 end 1885 1886 def __timestamps__(:utc_datetime) do 1887 %{DateTime.utc_now() | microsecond: {0, 0}} 1888 end 1889 1890 def __timestamps__(:utc_datetime_usec) do 1891 DateTime.utc_now() 1892 end 1893 1894 def __timestamps__(type) do 1895 type.from_unix!(System.os_time(:microsecond), :microsecond) 1896 end 1897 1898 @doc false 1899 def __loaded__(module, struct_fields) do 1900 case Map.new([{:__struct__, module} | struct_fields]) do 1901 %{__meta__: meta} = struct -> %{struct | __meta__: Map.put(meta, :state, :loaded)} 1902 struct -> struct 1903 end 1904 end 1905 1906 @doc false 1907 def __field__(mod, name, type, opts) do 1908 # Check the field type before we check options because it is 1909 # better to raise unknown type first than unsupported option. 1910 type = check_field_type!(mod, name, type, opts) 1911 1912 if type == :any && !opts[:virtual] do 1913 raise ArgumentError, "only virtual fields can have type :any, " <> 1914 "invalid type for field #{inspect name}" 1915 end 1916 1917 check_options!(type, opts, @field_opts, "field/3") 1918 Module.put_attribute(mod, :ecto_changeset_fields, {name, type}) 1919 validate_default!(type, opts[:default], opts[:skip_default_validation]) 1920 define_field(mod, name, type, opts) 1921 end 1922 1923 defp define_field(mod, name, type, opts) do 1924 virtual? = opts[:virtual] || false 1925 pk? = opts[:primary_key] || false 1926 put_struct_field(mod, name, Keyword.get(opts, :default)) 1927 1928 if Keyword.get(opts, :redact, false) do 1929 Module.put_attribute(mod, :ecto_redact_fields, name) 1930 end 1931 1932 if virtual? do 1933 Module.put_attribute(mod, :ecto_virtual_fields, {name, type}) 1934 else 1935 source = opts[:source] || Module.get_attribute(mod, :field_source_mapper).(name) 1936 1937 if not is_atom(source) do 1938 raise ArgumentError, "the :source for field `#{name}` must be an atom, got: #{inspect(source)}" 1939 end 1940 1941 if name != source do 1942 Module.put_attribute(mod, :ecto_field_sources, {name, source}) 1943 end 1944 1945 if raw = opts[:read_after_writes] do 1946 Module.put_attribute(mod, :ecto_raw, name) 1947 end 1948 1949 case gen = opts[:autogenerate] do 1950 {_, _, _} -> 1951 store_mfa_autogenerate!(mod, name, type, gen) 1952 1953 true -> 1954 store_type_autogenerate!(mod, name, source || name, type, pk?) 1955 1956 _ -> 1957 :ok 1958 end 1959 1960 if raw && gen do 1961 raise ArgumentError, "cannot mark the same field as autogenerate and read_after_writes" 1962 end 1963 1964 if pk? do 1965 Module.put_attribute(mod, :ecto_primary_keys, name) 1966 end 1967 1968 if Keyword.get(opts, :load_in_query, true) do 1969 Module.put_attribute(mod, :ecto_query_fields, {name, type}) 1970 end 1971 1972 Module.put_attribute(mod, :ecto_fields, {name, type}) 1973 end 1974 end 1975 1976 @valid_has_options [:foreign_key, :references, :through, :on_delete, :defaults, :on_replace, :where, :preload_order] 1977 1978 @doc false 1979 def __has_many__(mod, name, queryable, opts) do 1980 if is_list(queryable) and Keyword.has_key?(queryable, :through) do 1981 check_options!(queryable, @valid_has_options, "has_many/3") 1982 association(mod, :many, name, Ecto.Association.HasThrough, queryable) 1983 else 1984 check_options!(opts, @valid_has_options, "has_many/3") 1985 struct = association(mod, :many, name, Ecto.Association.Has, [queryable: queryable] ++ opts) 1986 Module.put_attribute(mod, :ecto_changeset_fields, {name, {:assoc, struct}}) 1987 end 1988 end 1989 1990 @doc false 1991 def __has_one__(mod, name, queryable, opts) do 1992 if is_list(queryable) and Keyword.has_key?(queryable, :through) do 1993 check_options!(queryable, @valid_has_options, "has_one/3") 1994 association(mod, :one, name, Ecto.Association.HasThrough, queryable) 1995 else 1996 check_options!(opts, @valid_has_options, "has_one/3") 1997 struct = association(mod, :one, name, Ecto.Association.Has, [queryable: queryable] ++ opts) 1998 Module.put_attribute(mod, :ecto_changeset_fields, {name, {:assoc, struct}}) 1999 end 2000 end 2001 2002 # :primary_key is valid here to support associative entity 2003 # https://en.wikipedia.org/wiki/Associative_entity 2004 @valid_belongs_to_options [:foreign_key, :references, :define_field, :type, 2005 :on_replace, :defaults, :primary_key, :source, :where] 2006 2007 @doc false 2008 def __belongs_to__(mod, name, queryable, opts) do 2009 opts = Keyword.put_new(opts, :foreign_key, :"#{name}_id") 2010 2011 foreign_key_name = opts[:foreign_key] 2012 foreign_key_type = opts[:type] || Module.get_attribute(mod, :foreign_key_type) 2013 foreign_key_type = check_field_type!(mod, name, foreign_key_type, opts) 2014 check_options!(foreign_key_type, opts, @valid_belongs_to_options, "belongs_to/3") 2015 2016 if foreign_key_name == name do 2017 raise ArgumentError, "foreign_key #{inspect name} must be distinct from corresponding association name" 2018 end 2019 2020 if Keyword.get(opts, :define_field, true) do 2021 Module.put_attribute(mod, :ecto_changeset_fields, {foreign_key_name, foreign_key_type}) 2022 define_field(mod, foreign_key_name, foreign_key_type, opts) 2023 end 2024 2025 struct = 2026 association(mod, :one, name, Ecto.Association.BelongsTo, [queryable: queryable] ++ opts) 2027 2028 Module.put_attribute(mod, :ecto_changeset_fields, {name, {:assoc, struct}}) 2029 end 2030 2031 @valid_many_to_many_options [:join_through, :join_defaults, :join_keys, :on_delete, :defaults, :on_replace, :unique, :where, :join_where, :preload_order] 2032 2033 @doc false 2034 def __many_to_many__(mod, name, queryable, opts) do 2035 check_options!(opts, @valid_many_to_many_options, "many_to_many/3") 2036 2037 struct = 2038 association(mod, :many, name, Ecto.Association.ManyToMany, [queryable: queryable] ++ opts) 2039 Module.put_attribute(mod, :ecto_changeset_fields, {name, {:assoc, struct}}) 2040 end 2041 2042 @valid_embeds_one_options [:strategy, :on_replace, :source] 2043 2044 @doc false 2045 def __embeds_one__(mod, name, schema, opts) when is_atom(schema) do 2046 check_options!(opts, @valid_embeds_one_options, "embeds_one/3") 2047 embed(mod, :one, name, schema, opts) 2048 end 2049 2050 def __embeds_one__(_mod, _name, schema, _opts) do 2051 raise ArgumentError, 2052 "`embeds_one/3` expects `schema` to be a module name, but received #{inspect(schema)}" 2053 end 2054 2055 @valid_embeds_many_options [:strategy, :on_replace, :source] 2056 2057 @doc false 2058 def __embeds_many__(mod, name, schema, opts) when is_atom(schema) do 2059 check_options!(opts, @valid_embeds_many_options, "embeds_many/3") 2060 opts = Keyword.put(opts, :default, []) 2061 embed(mod, :many, name, schema, opts) 2062 end 2063 2064 def __embeds_many__(_mod, _name, schema, _opts) do 2065 raise ArgumentError, 2066 "`embeds_many/3` expects `schema` to be a module name, but received #{inspect(schema)}" 2067 end 2068 2069 @doc false 2070 def __embeds_module__(env, name, opts, block) do 2071 {pk, opts} = Keyword.pop(opts, :primary_key, {:id, :binary_id, autogenerate: true}) 2072 2073 block = 2074 quote do 2075 use Ecto.Schema 2076 2077 @primary_key unquote(Macro.escape(pk)) 2078 embedded_schema do 2079 unquote(block) 2080 end 2081 end 2082 2083 module = Module.concat(env.module, name) 2084 Module.create(module, block, env) 2085 {module, opts} 2086 end 2087 2088 ## Quoted callbacks 2089 2090 @doc false 2091 def __after_compile__(%{module: module} = env, _) do 2092 # If we are compiling code, we can validate associations now, 2093 # as the Elixir compiler will solve dependencies. 2094 # 2095 # TODO: Use Code.can_await_module_compilation?/0 from Elixir v1.10+. 2096 if Process.info(self(), :error_handler) == {:error_handler, Kernel.ErrorHandler} do 2097 for name <- module.__schema__(:associations) do 2098 assoc = module.__schema__(:association, name) 2099 2100 case assoc.__struct__.after_compile_validation(assoc, env) do 2101 :ok -> 2102 :ok 2103 2104 {:error, message} -> 2105 IO.warn "invalid association `#{assoc.field}` in schema #{inspect module}: #{message}", 2106 Macro.Env.stacktrace(env) 2107 end 2108 end 2109 end 2110 2111 :ok 2112 end 2113 2114 @doc false 2115 def __schema__(fields, field_sources, assocs, embeds, virtual_fields) do 2116 load = 2117 for {name, type} <- fields do 2118 if alias = field_sources[name] do 2119 {name, {:source, alias, type}} 2120 else 2121 {name, type} 2122 end 2123 end 2124 2125 dump = 2126 for {name, type} <- fields do 2127 {name, {field_sources[name] || name, type}} 2128 end 2129 2130 field_sources_quoted = 2131 for {name, _type} <- fields do 2132 {[:field_source, name], field_sources[name] || name} 2133 end 2134 2135 types_quoted = 2136 for {name, type} <- fields do 2137 {[:type, name], Macro.escape(type)} 2138 end 2139 2140 virtual_types_quoted = 2141 for {name, type} <- virtual_fields do 2142 {[:virtual_type, name], Macro.escape(type)} 2143 end 2144 2145 assoc_quoted = 2146 for {name, refl} <- assocs do 2147 {[:association, name], Macro.escape(refl)} 2148 end 2149 2150 assoc_names = Enum.map(assocs, &elem(&1, 0)) 2151 2152 embed_quoted = 2153 for {name, refl} <- embeds do 2154 {[:embed, name], Macro.escape(refl)} 2155 end 2156 2157 embed_names = Enum.map(embeds, &elem(&1, 0)) 2158 2159 single_arg = [ 2160 {[:dump], dump |> Map.new() |> Macro.escape()}, 2161 {[:load], load |> Macro.escape()}, 2162 {[:associations], assoc_names}, 2163 {[:embeds], embed_names} 2164 ] 2165 2166 catch_all = [ 2167 {[:field_source, quote(do: _)], nil}, 2168 {[:type, quote(do: _)], nil}, 2169 {[:virtual_type, quote(do: _)], nil}, 2170 {[:association, quote(do: _)], nil}, 2171 {[:embed, quote(do: _)], nil} 2172 ] 2173 2174 [ 2175 single_arg, 2176 field_sources_quoted, 2177 types_quoted, 2178 virtual_types_quoted, 2179 assoc_quoted, 2180 embed_quoted, 2181 catch_all 2182 ] 2183 end 2184 2185 ## Private 2186 2187 defp embed(mod, cardinality, name, schema, opts) do 2188 opts = [cardinality: cardinality, related: schema, owner: mod, field: name] ++ opts 2189 struct = Ecto.Embedded.init(opts) 2190 2191 Module.put_attribute(mod, :ecto_changeset_fields, {name, {:embed, struct}}) 2192 Module.put_attribute(mod, :ecto_embeds, {name, struct}) 2193 define_field(mod, name, {:parameterized, Ecto.Embedded, struct}, opts) 2194 end 2195 2196 defp put_struct_field(mod, name, assoc) do 2197 fields = Module.get_attribute(mod, :ecto_struct_fields) 2198 2199 if List.keyfind(fields, name, 0) do 2200 raise ArgumentError, "field/association #{inspect name} already exists on schema, you must either remove the duplication or choose a different name" 2201 end 2202 2203 Module.put_attribute(mod, :ecto_struct_fields, {name, assoc}) 2204 end 2205 2206 defp validate_default!(_type, _value, true), do: :ok 2207 defp validate_default!(type, value, _skip) do 2208 case Ecto.Type.dump(type, value) do 2209 {:ok, _} -> 2210 :ok 2211 _ -> 2212 raise ArgumentError, "value #{inspect(value)} is invalid for type #{inspect(type)}, can't set default" 2213 end 2214 end 2215 2216 defp check_options!(opts, valid, fun_arity) do 2217 case Enum.find(opts, fn {k, _} -> not(k in valid) end) do 2218 {k, _} -> raise ArgumentError, "invalid option #{inspect k} for #{fun_arity}" 2219 nil -> :ok 2220 end 2221 end 2222 2223 defp check_options!({:parameterized, _, _}, _opts, _valid, _fun_arity) do 2224 :ok 2225 end 2226 2227 defp check_options!({_, type}, opts, valid, fun_arity) do 2228 check_options!(type, opts, valid, fun_arity) 2229 end 2230 2231 defp check_options!(_type, opts, valid, fun_arity) do 2232 check_options!(opts, valid, fun_arity) 2233 end 2234 2235 defp check_field_type!(_mod, name, :datetime, _opts) do 2236 raise ArgumentError, "invalid type :datetime for field #{inspect name}. " <> 2237 "You probably meant to choose one between :naive_datetime " <> 2238 "(no time zone information) or :utc_datetime (time zone is set to UTC)" 2239 end 2240 2241 defp check_field_type!(mod, name, type, opts) do 2242 cond do 2243 composite?(type, name) -> 2244 {outer_type, inner_type} = type 2245 {outer_type, check_field_type!(mod, name, inner_type, opts)} 2246 2247 not is_atom(type) -> 2248 raise ArgumentError, "invalid type #{inspect type} for field #{inspect name}" 2249 2250 Ecto.Type.base?(type) -> 2251 type 2252 2253 Code.ensure_compiled(type) == {:module, type} -> 2254 cond do 2255 function_exported?(type, :type, 0) -> 2256 type 2257 2258 function_exported?(type, :type, 1) -> 2259 Ecto.ParameterizedType.init(type, Keyword.merge(opts, field: name, schema: mod)) 2260 2261 function_exported?(type, :__schema__, 1) -> 2262 raise ArgumentError, 2263 "schema #{inspect type} is not a valid type for field #{inspect name}." <> 2264 " Did you mean to use belongs_to, has_one, has_many, embeds_one, or embeds_many instead?" 2265 2266 true -> 2267 raise ArgumentError, 2268 "module #{inspect(type)} given as type for field #{inspect name} is not an Ecto.Type/Ecto.ParameterizedType" 2269 end 2270 2271 true -> 2272 raise ArgumentError, "unknown type #{inspect type} for field #{inspect name}" 2273 end 2274 end 2275 2276 defp composite?({composite, _} = type, name) do 2277 if Ecto.Type.composite?(composite) do 2278 true 2279 else 2280 raise ArgumentError, 2281 "invalid or unknown composite #{inspect type} for field #{inspect name}. " <> 2282 "Did you mean to use :array or :map as first element of the tuple instead?" 2283 end 2284 end 2285 2286 defp composite?(_type, _name), do: false 2287 2288 defp store_mfa_autogenerate!(mod, name, type, mfa) do 2289 if autogenerate_id?(type) do 2290 raise ArgumentError, ":autogenerate with {m, f, a} not supported by ID types" 2291 end 2292 2293 Module.put_attribute(mod, :ecto_autogenerate, {[name], mfa}) 2294 end 2295 2296 defp store_type_autogenerate!(mod, name, source, {:parameterized, typemod, params} = type, pk?) do 2297 cond do 2298 store_autogenerate_id!(mod, name, source, type, pk?) -> 2299 :ok 2300 2301 not function_exported?(typemod, :autogenerate, 1) -> 2302 raise ArgumentError, "field #{inspect name} does not support :autogenerate because it uses a " <> 2303 "parameterized type #{inspect type} that does not define autogenerate/1" 2304 2305 true -> 2306 Module.put_attribute(mod, :ecto_autogenerate, {[name], {typemod, :autogenerate, [params]}}) 2307 end 2308 end 2309 2310 defp store_type_autogenerate!(mod, name, source, type, pk?) do 2311 cond do 2312 store_autogenerate_id!(mod, name, source, type, pk?) -> 2313 :ok 2314 2315 Ecto.Type.primitive?(type) -> 2316 raise ArgumentError, "field #{inspect name} does not support :autogenerate because it uses a " <> 2317 "primitive type #{inspect type}" 2318 2319 # Note the custom type has already been loaded in check_type!/3 2320 not function_exported?(type, :autogenerate, 0) -> 2321 raise ArgumentError, "field #{inspect name} does not support :autogenerate because it uses a " <> 2322 "custom type #{inspect type} that does not define autogenerate/0" 2323 2324 true -> 2325 Module.put_attribute(mod, :ecto_autogenerate, {[name], {type, :autogenerate, []}}) 2326 end 2327 end 2328 2329 defp store_autogenerate_id!(mod, name, source, type, pk?) do 2330 cond do 2331 not autogenerate_id?(type) -> 2332 false 2333 2334 not pk? -> 2335 raise ArgumentError, "only primary keys allow :autogenerate for type #{inspect type}, " <> 2336 "field #{inspect name} is not a primary key" 2337 2338 Module.get_attribute(mod, :ecto_autogenerate_id) -> 2339 raise ArgumentError, "only one primary key with ID type may be marked as autogenerated" 2340 2341 true -> 2342 Module.put_attribute(mod, :ecto_autogenerate_id, {name, source, type}) 2343 true 2344 end 2345 end 2346 2347 defp autogenerate_id?(type), do: Ecto.Type.type(type) in [:id, :binary_id] 2348 2349 defp expand_alias({:__aliases__, _, _} = ast, env), 2350 do: Macro.expand(ast, %{env | function: {:__schema__, 2}}) 2351 defp expand_alias(ast, _env), 2352 do: ast 2353 2354 defp expand_alias_in_key(opts, key, env) do 2355 if is_list(opts) and Keyword.has_key?(opts, key) do 2356 Keyword.update!(opts, key, &expand_alias(&1, env)) 2357 else 2358 opts 2359 end 2360 end 2361 end