ecto

# Changelog for v2.0

This is a new major release of Ecto that removes previously deprecated features and introduces a series of improvements and features based on [`db_connection`](https://github.com/fishcakez/db_connection).

Ecto 2.0 requires Elixir 1.2+.

## Highlights

### Revamped changesets

Due to feedback, we have made three important changes to changesets:

  1. `changeset.model` has been renamed to `changeset.data` (we no longer have "models" in Ecto)
  2. Passing required and optional fields to `cast/4` is deprecated in favor of `cast/3` and `validate_required/3`
  3. The `:empty` atom in `cast(source, :empty, required, optional)` has been removed. An empty map can now be used

To summarize those changes, instead of:

    def changeset(user, params \\ :empty) do
      user
      |> cast(params, [:name], [:age])
    end

One should write:

    def changeset(user, params \\ %{}) do
      user
      |> cast(params, [:name, :age])
      |> validate_required([:name])
    end

### Subqueries

Ecto v2.0 introduces `Ecto.Query.subquery/1` that will convert any query into a subquery to be used either as part of a `from` or a `join`. For example, if you want to calculate the average number of visits per posts, you can write:

    query = from p in Post, select: avg(p.visits)
    TestRepo.all(query) #=> [#Decimal<1743>]

However, if you want to calculate the average only across the top 10 most visited, you need subqueries:

    query = from p in Post, select: [:visits], order_by: [desc: :visits], limit: 10
    TestRepo.all(from p in subquery(query), select: avg(p.visits)) #=> [#Decimal<4682>]

Or alternatively, for the particular example where you are calculating aggregates, use the new `Repo.aggregate` function that handles those concerns automatically for you:

    # Average across all
    TestRepo.aggregate(Post, :avg, :visits) #=> #Decimal<1743>

    # Average across top 10
    query = from Post, order_by: [desc: :visits], limit: 10
    TestRepo.aggregate(query, :avg, :visits) #=> #Decimal<4682>

### Concurrent transactional tests

Ecto has reimplemented the `Ecto.Adapters.SQL.Sandbox` pool used for testing to use an ownership mechanism. This allows tests to safely run concurrently even when depending on the database. To use, declare sandbox as your pool in your repository configuration, as before:

    pool: Ecto.Adapters.SQL.Sandbox

Now at the end of your `test_helper.exs`, set the sandbox mode to `:manual` in order to disable the automatic checkout of connections:

    Ecto.Adapters.SQL.Sandbox.mode(TestRepo, :manual)

And now checkout the connection in the `setup` block of every test case that needs the database:

    setup do
      :ok = Ecto.Adapters.SQL.Sandbox.checkout(TestRepo)
    end

The previous sandbox API, which used `begin_test_transaction` and `restart_test_transaction`, is no longer supported.

### Insert all

Ecto now allows developers to insert multiple entries at once via `Ecto.Repo.insert_all/3`:

    Ecto.Repo.insert_all Post, [%{title: "foo"}, %{title: "bar"}]

Similar to `update_all/3`, `insert_all/3` is meant to be closer to the datastore and it won't automatically handle autogenerated fields like `inserted_at` or `updated_at` timestamps. `insert_all/3` also adds to Ecto the ability to introduce entries to the database without an underlying `Ecto.Schema` by simply giving a table name:

    Ecto.Repo.insert_all "some_table", [%{hello: "foo"}, %{hello: "bar"}]

### Many to many

Ecto 2.0 supports `many_to_many` associations:

    defmodule Post do
      use Ecto.Schema
      schema "posts" do
        many_to_many :tags, Tag, join_through: "posts_tags"
      end
    end

The `join_through` option can be a string, representing a table that will have both `post_id` and `tag_id` columns, or a regular schema, like `PostTag`, which would also handle primary keys and autogenerate fields. This is an improvement over `has_many :through` as `has_many :through` relationships are read-only, while `many_to_many` supports also inserting, updating and deleting associated entries through changeset, as we will see next.

### Improved association support

Ecto now supports `belongs_to` and `many_to_many` associations to be cast or changed via changesets, beyond `has_one`, `has_many` and embeds. Not only that, Ecto supports associations and embeds to be defined directly from the struct on insertion. For example, one can call:

    Repo.insert! %Permalink{
      url: "//root",
      post: %Post{
        title: "A permalink belongs to a post which we are inserting",
        comments: [
          %Comment{text: "child 1"},
          %Comment{text: "child 2"},
        ]
      }
    }

This allows developers to easily insert a tree of structs into the database, be it when seeding data for production or during tests.

Finally, Ecto now allows putting existing records in changesets, and the proper changes will be reflected in both structs and the database. For example, you may retrieve the permalink above and associate it to another existing post:

    permalink
    |> Ecto.Changeset.change
    |> Ecto.Changeset.put_assoc(:post, existing_post)
    |> Repo.update!

## Backwards incompatible changes

  * [Changeset] `changeset.model` has been renamed to `changeset.data`
  * [Changeset] `changeset.optional` has been removed
  * [Repo] `Ecto.StaleModelError` has been renamed to `Ecto.StaleEntryError`
  * [Repo] Poolboy now expects `:pool_overflow` option instead of `:max_overflow`
  * [Repo] `Repo.insert/2` will now send only non-nil fields from the struct to the storage (in previous versions, all fields from the struct were sent to the database)
  * [Repo] `Ecto.Pools.Poolboy` and `Ecto.Pools.SojournBroker` have been removed in favor of `DBConnection.Poolboy` and `DBConnection.Sojourn`
  * [Repo] `:timeout` in `Repo.transaction` now affects the whole transaction block and not only the particular transaction queries
  * [Repo] Overriding `Repo.log/1` is no longer supported. Instead, provide custom loggers configuration via `:loggers`. The default is: `[{Ecto.LogEntry, :log, []}]`
  * [Schema] Array fields no longer default to an empty list `[]`. Previous behaviour can be achieved by passing `default: []` to the field definition
  * [SQL] `Ecto.Adapters.SQL.begin_test_transaction`, `Ecto.Adapters.SQL.restart_test_transaction` and `Ecto.Adapters.SQL.rollback_test_transaction` have been removed in favor of the new ownership-based `Ecto.Adapters.SQL.Sandbox`

## Deprecations

  * [Changeset] Deprecate `:empty` in `Ecto.Changeset.cast`
  * [Changeset] Deprecate `Ecto.Changeset.cast/4` in favor of `Ecto.Changeset.cast/3`
  * [Repo] `Repo.after_connect/1` is deprecated, please pass the `:after_connect` repository option instead

## Enhancements

  * [Adapter] Ensure adapters work on native types, guaranteeing adapters compose better with custom types
  * [Adapter] Support prepared queries in adapters
  * [DateTime] Ensure the given date and datetimes are valid
  * [Migration] Add support for partial indexes by specifying the `:where` option when on `Ecto.Migration.index/2`
  * [Migration] Allow the migration table name to be configured in the repository via `:migration_source`
  * [Migration] Use pool of 1 connection for `mix ecto.migrate/rollback`
  * [Mix] Automatically reenable migration and repository management tasks after execution
  * [Postgres] Add migration and changeset support for PostgreSQL exclusion constraints. Example: `create constraint(:sizes, :cannot_overlap, exclude: ~s|gist (int4range("min", "max", '[]') WITH &&)|)` and `exclusion_constraint(changeset, :sizes, name: :cannot_overlap, message: "must not overlap")`
  * [Postgres] Add migration and changeset support for PostgreSQL check constraints. Example: `create constraint(@table.name, "positive_price", check: "price > 0")` and `check_constraint(changeset, :description, name: :positive_price, message: "must be greater than zero")`
  * [Query] Allow the `:on` field to be specified with association joins
  * [Query] Support expressions in map keys in `select` in queries. Example: `from p in Post, select: %{p.title => p.visitors}`
  * [Query] Allow struct fields to be selected with `take/2`, including support for dynamic fields
  * [Query] Add `first/2` and `last/2`
  * [Repo] Add `Repo.aggregate/4` for easy aggregations
  * [Repo] Allow custom `select` field in preload queries
  * [Repo] Support the `:force` option in preloads
  * [Repo] Perform preloads in parallel by default
  * [Repo] Add `Repo.in_transaction?` to know if the current process is in a transaction
  * [Repo] Support `:returning` option in `insert_all`, `update_all` and `delete_all`
  * [Schema] Allow `@schema_prefix` to be configured per schema. It is used for new structs as well as queries where the given schema is used as `from`
  * [Schema] Support composite primary keys

## Bug fixes

  * [Changeset] The `:required` option on `cast_assoc` and `cast_embed` will now tag `has_many` and `embeds_many` relationships as missing if they contain an empty list
  * [DateTime] Fix Date/DateTime serialization for years above 9999
  * [Postgres] Switch pg storage management away from `psql` and use direct database connections, solving many issues like locale and database connection
  * [Repo] Ensure nested preload works even if intermediate associations were already loaded
  * [Repo] Do not attempt to execute insert/update/delete statement for associations if a previous operation failed due to a constraint error

## Previous versions

  * See the CHANGELOG.md in the v1.1 branch