From bbd62f4d7fc88861cf952f1be3c4d1359ec71238 Mon Sep 17 00:00:00 2001 From: Matthew Weidner <17693586+mweidner037@users.noreply.github.com> Date: Tue, 11 Mar 2025 14:38:07 -0500 Subject: [PATCH 1/6] setup instructions; id types --- README.md | 65 ++++++++++++++++++++++++++++++++--------------- lib/mongo_ecto.ex | 2 ++ 2 files changed, 46 insertions(+), 21 deletions(-) diff --git a/README.md b/README.md index 435b2d2..a1905b5 100644 --- a/README.md +++ b/README.md @@ -21,16 +21,24 @@ config :my_app, Repo, adapter: Mongo.Ecto, database: "ecto_simple", username: "mongodb", - password: "mongosb", + password: "mongodb", hostname: "localhost" + # Or you can use a connection string (mongodb:// or mongodb+srv://), e.g.: + # mongo_url: "mongodb://mongodb:mongodb@localhost:27017/ecto_simple" # 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 @primary_key {:id, :binary_id, autogenerate: true} schema "weather" do @@ -105,6 +113,18 @@ For additional information on usage please see the documentation for [Ecto](http | timestamp | `BSON.Timestamp` | | 64-bit integer | `:integer` | +Primary keys on Ecto schemas are named `:id` and represented as strings, whereas in the actual MongoDB collection, they are named `_id` and stored as object ids. Schema definitions for MongoDB collections should start with `@primary_key {:id, :binary_id, autogenerate: true}` like in the above example. To create an `:id` for an Ecto struct, use `BSON.ObjectId.encode!(Mongo.object_id())`, e.g.: + +```elixir +weather = %Weather{ + id: BSON.ObjectId.encode!(Mongo.object_id()), + city: "New York City", + temp_lo: 32, + temp_hi: 50, + prcp: 0.0 +} +``` + Symbols are deprecated by the [BSON specification](http://bsonspec.org/spec.html). They will be converted to simple strings on reads. There is no possibility of persisting them to @@ -126,25 +146,28 @@ The adapter and the driver are tested against most recent versions from 5.0, 6.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`. -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: +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: + 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. diff --git a/lib/mongo_ecto.ex b/lib/mongo_ecto.ex index 27bf1dc..6821360 100644 --- a/lib/mongo_ecto.ex +++ b/lib/mongo_ecto.ex @@ -28,6 +28,8 @@ defmodule Mongo.Ecto do password: "mongodb", hostname: "localhost" + 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: From c429f716d03db092b6aadb035a8f353df4be742c Mon Sep 17 00:00:00 2001 From: Matthew Weidner <17693586+mweidner037@users.noreply.github.com> Date: Tue, 11 Mar 2025 14:43:23 -0500 Subject: [PATCH 2/6] remove applications: advice It should be auto-inferred, and if not, extra_applications is correct instead: https://elixirforum.com/t/why-do-we-use-application-function-in-mix-exs/23834/2 --- README.md | 8 -------- 1 file changed, 8 deletions(-) diff --git a/README.md b/README.md index a1905b5..41eb3a6 100644 --- a/README.md +++ b/README.md @@ -73,14 +73,6 @@ def deps do 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 From e2f0bbe6c81ea43e04ce3c5729aa845948963227 Mon Sep 17 00:00:00 2001 From: Matthew Weidner <17693586+mweidner037@users.noreply.github.com> Date: Tue, 11 Mar 2025 14:53:21 -0500 Subject: [PATCH 3/6] autogenerate: refer to module docs instead --- README.md | 15 +++------------ lib/mongo_ecto.ex | 2 +- 2 files changed, 4 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 41eb3a6..cfb7467 100644 --- a/README.md +++ b/README.md @@ -40,7 +40,10 @@ end defmodule Weather do 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 @@ -105,18 +108,6 @@ For additional information on usage please see the documentation for [Ecto](http | timestamp | `BSON.Timestamp` | | 64-bit integer | `:integer` | -Primary keys on Ecto schemas are named `:id` and represented as strings, whereas in the actual MongoDB collection, they are named `_id` and stored as object ids. Schema definitions for MongoDB collections should start with `@primary_key {:id, :binary_id, autogenerate: true}` like in the above example. To create an `:id` for an Ecto struct, use `BSON.ObjectId.encode!(Mongo.object_id())`, e.g.: - -```elixir -weather = %Weather{ - id: BSON.ObjectId.encode!(Mongo.object_id()), - city: "New York City", - temp_lo: 32, - temp_hi: 50, - prcp: 0.0 -} -``` - Symbols are deprecated by the [BSON specification](http://bsonspec.org/spec.html). They will be converted to simple strings on reads. There is no possibility of persisting them to diff --git a/lib/mongo_ecto.ex b/lib/mongo_ecto.ex index 6821360..792154d 100644 --- a/lib/mongo_ecto.ex +++ b/lib/mongo_ecto.ex @@ -52,7 +52,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 From 498eac38acb263d6f25fcb790dfa602ea11f90b4 Mon Sep 17 00:00:00 2001 From: Matthew Weidner <17693586+mweidner037@users.noreply.github.com> Date: Tue, 11 Mar 2025 15:21:51 -0500 Subject: [PATCH 4/6] ecto_repos config example --- README.md | 9 +++++++-- lib/mongo_ecto.ex | 4 ++++ 2 files changed, 11 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index cfb7467..6c01a0a 100644 --- a/README.md +++ b/README.md @@ -19,12 +19,17 @@ 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: "mongodb", hostname: "localhost" - # Or you can use a connection string (mongodb:// or mongodb+srv://), e.g.: - # mongo_url: "mongodb://mongodb:mongodb@localhost:27017/ecto_simple" + # 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 diff --git a/lib/mongo_ecto.ex b/lib/mongo_ecto.ex index 792154d..a82919b 100644 --- a/lib/mongo_ecto.ex +++ b/lib/mongo_ecto.ex @@ -28,6 +28,10 @@ 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 From de2094f3d134d421f9c2e6176c399c2f7e186b48 Mon Sep 17 00:00:00 2001 From: Matthew Weidner <17693586+mweidner037@users.noreply.github.com> Date: Tue, 11 Mar 2025 15:27:46 -0500 Subject: [PATCH 5/6] add link to full docs --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 6c01a0a..70b5d55 100644 --- a/README.md +++ b/README.md @@ -91,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 From a1f98d58a982b2ad6e0a15a3082bb881b8406811 Mon Sep 17 00:00:00 2001 From: Matthew Weidner <17693586+mweidner037@users.noreply.github.com> Date: Wed, 12 Mar 2025 09:09:13 -0500 Subject: [PATCH 6/6] update versions --- CHANGELOG.md | 65 ++++++++++++++++++++++++++++------------------------ README.md | 4 ++-- 2 files changed, 37 insertions(+), 32 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 7376927..a0268be 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/README.md b/README.md index 70b5d55..a42fe61 100644 --- a/README.md +++ b/README.md @@ -76,7 +76,7 @@ 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 ``` @@ -132,7 +132,7 @@ 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: