Improve README setup instructions

CHANGELOG.md

@@ -7,68 +7,73 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## 2.0.0
 
-* Change underlying driver from [`mongodb`](https://github.com/elixir-mongo/mongodb) to [`mongodb_driver`](https://github.com/zookzook/elixir-mongodb-driver) 1.4.0
-* Remove config options `pool`, `pool_overflow`, and `pool_timeout`
-* Add support for MongoDB 6.0 and 7.0
-* Add support for loading & dumping nil binaries and dumping nil dates
+- Change underlying driver from [`mongodb`](https://github.com/elixir-mongo/mongodb) to [`mongodb_driver`](https://github.com/zookzook/elixir-mongodb-driver) 1.4
+- Remove config options `pool`, `pool_overflow`, and `pool_timeout`
+- Add support for MongoDB 6.0 and 7.0
+- Add support for loading & dumping nil binaries and dumping nil dates
 
 ### Possible breaking changes
 
 Calls to the Ecto adapter itself should not require any changes. However, if you make direct calls to the `Mongo` driver, you will need to update some of them to account for the `mongodb` -> `mongodb_driver` upgrade. See [Migrating to 2.0](./README.md#migrating-to-20) in the Readme.
 
 ## 1.1.2
-* Add support for loading nil dates
+
+- Add support for loading nil dates
 
 ## 1.1.1
-* Allow `binary_id` fields to be nil
+
+- Allow `binary_id` fields to be nil
 
 ## 1.1.0
-* Add support for Ecto 1.11
+
+- Add support for Ecto 1.11
 
 ## 1.0.0
 
-* Introduce support for Ecto 3
-* Introduce GitHub actions, replacing Travis CI
-* Use MongoDB 1.0.0 to add support for Mongodb 4.4. and 5.0
+- Introduce support for Ecto 3
+- Introduce GitHub actions, replacing Travis CI
+- Use MongoDB 1.0.0 to add support for Mongodb 4.4. and 5.0
 
-* NOTE: This might work with versions of Ecto less than 3.6.
-Refer to the ecto-3 branch if you need to find a commit that works with a non-officially supported version
-of Ecto.
+- NOTE: This might work with versions of Ecto less than 3.6.
+  Refer to the ecto-3 branch if you need to find a commit that works with a non-officially supported version
+  of Ecto.
 
 ### Possible breaking changes
 
-  * Some upsert operations are only supported with MongoDBs 4.2 or newer.
+- Some upsert operations are only supported with MongoDBs 4.2 or newer.
 
 ## v0.1.4 (2016-03-03)
 
-  *  Support MongoDB version 3.2
+- Support MongoDB version 3.2
 
 ## v0.1.3 (2016-01-15)
 
-  * This version is limited to Ecto 1.0 because of known issues with 1.1
+- This version is limited to Ecto 1.0 because of known issues with 1.1
 
-  * Additions:
-    * Implement `count(field, :distinct)`
+- Additions:
 
-  * Bug fixes:
-    * Handle models without autogenerated primary key on update and delete
-    * Implement `Ecto.Adapter.stop/2` callback
-    * Move encoding to adapter `load` and `dump` callbacks
+  - Implement `count(field, :distinct)`
+
+- Bug fixes:
+  - Handle models without autogenerated primary key on update and delete
+  - Implement `Ecto.Adapter.stop/2` callback
+  - Move encoding to adapter `load` and `dump` callbacks
 
 ## v0.1.2 (2015-10-18)
 
-  * Breaking changes:
-    * Raise on `limit` and `offset` in `update_all` and `delete_all` queries,
-      it's not supported by MongoDB, we were failing siletnly before
+- Breaking changes:
+
+  - Raise on `limit` and `offset` in `update_all` and `delete_all` queries,
+    it's not supported by MongoDB, we were failing siletnly before
 
-  * Bug fixes:
-    * Allow interpolation in limit and offset
+- Bug fixes:
+  - Allow interpolation in limit and offset
 
 ## v0.1.1 (2015-08-30)
 
-  * Bug fixes:
-    * Fix logging issues on find queries
+- Bug fixes:
+  - Fix logging issues on find queries
 
 ## v0.1.0 (2015-08-25)
 
-  * First release
+- First release

README.md

@@ -19,20 +19,36 @@ or check out examples below.
 # In your config/config.exs file
 config :my_app, Repo,
   adapter: Mongo.Ecto,
+  # Example key-value configuration:
   database: "ecto_simple",
   username: "mongodb",
-  password: "mongosb",
+  password: "mongodb",
   hostname: "localhost"
+  # OR you can configure with a connection string (mongodb:// or mongodb+srv://):
+  mongo_url: "mongodb://mongodb:mongodb@localhost:27017/ecto_simple"
+
+config :my_app,
+  # Add Repo to this list so you can run commands like `mix ecto.create`.
+  ecto_repos: [Repo]
 
 # In your application code
 defmodule Repo do
-  use Ecto.Repo, otp_app: :my_app
+  use Ecto.Repo,
+    otp_app: :my_app,
+    adapter: Mongo.Ecto
+
+  def pool() do
+    Ecto.Adapter.lookup_meta(__MODULE__).pid
+  end
 end
 
 defmodule Weather do
-  use Ecto.Model
+  use Ecto.Schema
 
+  # see Mongo.Ecto module docs for explanation of this line
   @primary_key {:id, :binary_id, autogenerate: true}
+
+  # weather is the MongoDB collection name
   schema "weather" do
     field :city     # Defaults to type :string
     field :temp_lo, :integer
@@ -60,19 +76,11 @@ Add `:mongodb_ecto` as a dependency in your `mix.exs` file.
 ```elixir
 def deps do
   [
-    {:mongodb_ecto, "~> 1.0.0"}
+    {:mongodb_ecto, "~> 2.0.0"}
   ]
 end
 ```
 
-You should also update your applications to include both projects:
-
-```elixir
-def application do
-  [applications: [:logger, :mongodb_ecto, :ecto]]
-end
-```
-
 To use the adapter in your repo:
 
 ```elixir
@@ -83,7 +91,7 @@ defmodule MyApp.Repo do
 end
 ```
 
-For additional information on usage please see the documentation for [Ecto](http://hexdocs.pm/ecto).
+For additional information on usage please see the documentation for the [Mongo.Ecto module](https://hexdocs.pm/mongodb_ecto/Mongo.Ecto.html) and for [Ecto](http://hexdocs.pm/ecto).
 
 ## Data Type Mapping
 
@@ -124,27 +132,30 @@ The adapter and the driver are tested against most recent versions from 5.0, 6.0
 
 ## Migrating to 2.0
 
-Release 2.0 changes the underlying driver from [`mongodb`](https://github.com/elixir-mongo/mongodb) to [`mongodb_driver`](https://github.com/zookzook/elixir-mongodb-driver) 1.4.0. Calls to the Ecto adapter itself should not require any changes. Some config options are no longer used and can be simply deleted: `pool`, `pool_overflow`, `pool_timeout`.
+Release 2.0 changes the underlying driver from [`mongodb`](https://github.com/elixir-mongo/mongodb) to [`mongodb_driver`](https://github.com/zookzook/elixir-mongodb-driver) 1.4. Calls to the Ecto adapter itself should not require any changes. Some config options are no longer used and can be simply deleted: `pool`, `pool_overflow`, `pool_timeout`.
+
+If you make direct calls to the `Mongo` driver, you will need to update some of them to account for the `mongodb` -> `mongodb_driver` upgrade. Also, remember to replace `:mongodb` with `{:mongodb_driver, "~> 1.4"}` in your `mix.exs`. The known updates are:
 
-If you make direct calls to the `Mongo` driver, you will need to update some of them to account for the `mongodb` -> `mongodb_driver` upgrade. Also, remember to replace `:mongodb` with `{:mongodb_driver, "~> 1.4.0"}` in your `mix.exs`. The known updates are:
 1. `Mongo` functions no longer accept a `pool` option or `MyApp.Repo.Pool` module argument. Instead, a pool PID is expected:
-    ```elixir
-    # Old driver call
-    Mongo.find(MyApp.Repo.Pool, "my_coll", %{"id": id}, projection: %{"field": 1}, pool: db_pool())
-
-    # New driver call
-    Mongo.find(MyApp.Repo.pool(), "my_coll", %{"id": id}, projection: %{"field": 1})
-
-    # repo.ex
-    # Provided the following function is defined in MyApp.Repo:
-    defmodule MyApp.Repo do
-      use Ecto.Repo, otp_app: :my_app, adapter: Mongo.Ecto
-
-      def pool() do
-        Ecto.Adapter.lookup_meta(__MODULE__).pid
-      end
-    end
-    ```
+
+   ```elixir
+   # Old driver call
+   Mongo.find(MyApp.Repo.Pool, "my_coll", %{"id": id}, projection: %{"field": 1}, pool: db_pool())
+
+   # New driver call
+   Mongo.find(MyApp.Repo.pool(), "my_coll", %{"id": id}, projection: %{"field": 1})
+
+   # repo.ex
+   # Provided the following function is defined in MyApp.Repo:
+   defmodule MyApp.Repo do
+     use Ecto.Repo, otp_app: :my_app, adapter: Mongo.Ecto
+
+     def pool() do
+       Ecto.Adapter.lookup_meta(__MODULE__).pid
+     end
+   end
+   ```
+
 2. [`Mongo.command`](https://hexdocs.pm/mongodb_driver/1.4.1/Mongo.html#command/3) requires a keyword list instead of a document. E.g., instead of `Mongo.command(MyApp.Repo.pool(), %{listCollections: 1}, opts)`, do `Mongo.command(MyApp.Repo.pool(), [listCollections: 1], opts)`.
 3. `Mongo.ReadPreferences.defaults` is renamed to `Mongo.ReadPreference.merge_defaults`.
 4. When passing a `hint` to `Mongo.find_one` etc., if the hinted index does not exist, an error is now returned.

lib/mongo_ecto.ex

@@ -28,6 +28,12 @@ defmodule Mongo.Ecto do
         password: "mongodb",
         hostname: "localhost"
 
+      config :my_app,
+        # Add Repo to this list so you can run commands like `mix ecto.create`.
+        ecto_repos: [Repo]
+
+  For more connection options, see mongodb-driver's [Mongo.start_link](https://hexdocs.pm/mongodb_driver/1.5.2/Mongo.html#start_link/1). Note that to use a connection string (mongodb:// or mongodb+srv://), you must set `mongo_url: ` instead of `url: `.
+
   Each repository in Ecto defines a `start_link/0` function that needs to be
   invoked before using the repository. This function is generally from your
   supervision tree:
@@ -50,7 +56,7 @@ defmodule Mongo.Ecto do
       defmodule Weather do
         use Ecto.Model
 
-        # see the note below for explanation of that line
+        # see the note below for explanation of this line
         @primary_key {:id, :binary_id, autogenerate: true}
 
         # weather is the MongoDB collection name