Add :include option to support covering indexes (#182)

When specifying the :include option during index creation, the `CREATE
INDEX` operation receives an additional option `INCLUDE` to specify
non-key columns to include in the index.

lib/ecto/adapters/postgres/connection.ex

@@ -752,6 +752,7 @@ if Code.ensure_loaded?(Postgrex) do
 
     def execute_ddl({:create, %Index{} = index}) do
       fields = intersperse_map(index.columns, ", ", &index_expr/1)
+      include_fields = intersperse_map(index.include, ", ", &index_expr/1)
 
       queries = [["CREATE ",
                   if_do(index.unique, "UNIQUE "),
@@ -762,6 +763,7 @@ if Code.ensure_loaded?(Postgrex) do
                   quote_table(index.prefix, index.table),
                   if_do(index.using, [" USING " , to_string(index.using)]),
                   ?\s, ?(, fields, ?),
+                  if_do(include_fields != [], [" INCLUDE ", ?(, include_fields, ?)]),
                   if_do(index.where, [" WHERE ", to_string(index.where)])]]
 
       queries ++ comments_on("INDEX", quote_table(index.prefix, index.name), index.comment)

lib/ecto/migration.ex

@@ -154,8 +154,8 @@ defmodule Ecto.Migration do
   terminates.
 
   However, in some situations you may want to guarantee that all of the
-  previous steps have been executed before continuing. This is useful when 
-  you need to apply a set of changes to the table before continuing with the 
+  previous steps have been executed before continuing. This is useful when
+  you need to apply a set of changes to the table before continuing with the
   migration. This can be done with `flush/0`:
 
       def up do
@@ -315,6 +315,7 @@ defmodule Ecto.Migration do
               unique: false,
               concurrently: false,
               using: nil,
+              include: [],
               where: nil,
               comment: nil,
               options: nil
@@ -327,6 +328,7 @@ defmodule Ecto.Migration do
       unique: boolean,
       concurrently: boolean,
       using: atom | String.t,
+      include: [atom | String.t],
       where: atom | String.t,
       comment: String.t | nil,
       options: String.t
@@ -625,6 +627,9 @@ defmodule Ecto.Migration do
     * `:using` - configures the index type.
     * `:prefix` - specify an optional prefix for the index.
     * `:where` - specify conditions for a partial index.
+    * `:include` - specify fields for a covering index. This is not supported
+      by all databases. For more information on PostgreSQL support, please
+      [read the official docs](https://www.postgresql.org/docs/11/indexes-index-only-scans.html).
 
   ## Adding/dropping indexes concurrently
 
@@ -696,6 +701,9 @@ defmodule Ecto.Migration do
       # Partial indexes are created by specifying a :where option
       create index("products", [:user_id], where: "price = 0", name: :free_products_index)
 
+      # Covering indexes are created by specifying a :include option
+      create index("products", [:user_id], include: [:category_id])
+
   Indexes also support custom expressions. Some databases may require the
   index expression to be written between parentheses:
 

test/ecto/adapters/postgres_test.exs

@@ -1532,6 +1532,16 @@ defmodule Ecto.Adapters.PostgresTest do
       [~s|CREATE UNIQUE INDEX "posts_permalink_index" ON "posts" ("permalink") WHERE public|]
   end
 
+  test "create index with include fields" do
+    create = {:create, index(:posts, [:permalink], unique: true, include: [:public])}
+    assert execute_ddl(create) ==
+      [~s|CREATE UNIQUE INDEX "posts_permalink_index" ON "posts" ("permalink") INCLUDE ("public")|]
+
+    create = {:create, index(:posts, [:permalink], unique: true, include: [:public], where: "public IS TRUE")}
+    assert execute_ddl(create) ==
+      [~s|CREATE UNIQUE INDEX "posts_permalink_index" ON "posts" ("permalink") INCLUDE ("public") WHERE public IS TRUE|]
+  end
+
   test "create index concurrently" do
     index = index(:posts, [:permalink])
     create = {:create, %{index | concurrently: true}}