{"id":13480687,"url":"https://github.com/elixir-mongo/mongodb","last_synced_at":"2025-05-15T01:05:15.334Z","repository":{"id":22505942,"uuid":"25846077","full_name":"elixir-mongo/mongodb","owner":"elixir-mongo","description":"MongoDB driver for Elixir","archived":false,"fork":false,"pushed_at":"2023-12-16T18:07:14.000Z","size":5004,"stargazers_count":572,"open_issues_count":20,"forks_count":154,"subscribers_count":24,"default_branch":"master","last_synced_at":"2025-04-13T19:01:25.807Z","etag":null,"topics":["driver","elixir","mongodb"],"latest_commit_sha":null,"homepage":"","language":"Elixir","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/elixir-mongo.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2014-10-28T00:39:27.000Z","updated_at":"2025-04-08T22:50:53.000Z","dependencies_parsed_at":"2024-01-26T05:39:57.915Z","dependency_job_id":null,"html_url":"https://github.com/elixir-mongo/mongodb","commit_stats":{"total_commits":554,"total_committers":81,"mean_commits":6.839506172839506,"dds":0.7220216606498195,"last_synced_commit":"a4a304e3a60d00fde6be052da3321e3a7e9f72a9"},"previous_names":["ericmj/mongodb","kobil-systems/mongodb"],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elixir-mongo%2Fmongodb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elixir-mongo%2Fmongodb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elixir-mongo%2Fmongodb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elixir-mongo%2Fmongodb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/elixir-mongo","download_url":"https://codeload.github.com/elixir-mongo/mongodb/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248785011,"owners_count":21161218,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["driver","elixir","mongodb"],"created_at":"2024-07-31T17:00:43.654Z","updated_at":"2025-04-13T21:29:13.186Z","avatar_url":"https://github.com/elixir-mongo.png","language":"Elixir","funding_links":[],"categories":["Libraries","Elixir"],"sub_categories":["Elixir"],"readme":"# MongoDB\n\n[![Build Status](https://travis-ci.org/ankhers/mongodb.svg?branch=master)](https://travis-ci.org/ankhers/mongodb)\n\n[Documentation for MongoDB is available online](http://hexdocs.pm/mongodb/).\n\n## 1.0.0 Released: March 22, 2023\n\nThere's one breaking change!\n- `Mongo.find_one_and_replace/5`, `Mongo.find_one_and_update/5` now return `{:ok, Mongo.FindAndModifyResult{:value, :matched_count, :upserted_id, :updated_existing}}` instead of `{:ok, doc}`\n  The change should be rather mechanical.\n\n## Features\n  * Supports MongoDB versions 3.4, 3.6, 4.0, 4.2, 4.4, 5.0\n  * Connection pooling (through `db_connection`)\n  * Streaming cursors\n  * Performant ObjectID generation\n  * Follows driver specification set by 10gen\n  * Safe (by default) and unsafe writes\n  * Aggregation pipeline\n  * Replica sets\n  * Sessions and transactions\n\n\n## Tentative Roadmap\n  * Use meta-driver test suite\n\n## Data representation\n\n| BSON             | Elixir\n| ---------------- | ------\n| double           | `0.0`\n| string           | `\"Elixir\"`\n| document         | `[{\"key\", \"value\"}]` \\| `%{\"key\" =\u003e \"value\"}` ¹\n| binary           | `%BSON.Binary{binary: \u003c\u003c42, 43\u003e\u003e, subtype: :generic}`\n| object id        | `%BSON.ObjectId{value: \u003c\u003c...\u003e\u003e}`\n| boolean          | `true` | `false`\n| UTC datetime     | `%DateTime{}`\n| null             | `nil`\n| regex            | `%BSON.Regex{pattern: \"...\"}`\n| JavaScript       | `%BSON.JavaScript{code: \"...\"}`\n| integer          | `42`\n| symbol           | `\"foo\"` ²\n| min key          | `:BSON_min`\n| max key          | `:BSON_max`\n\n¹ Since BSON documents are ordered Elixir maps cannot be used to fully\nrepresent them. This driver chose to accept both maps and lists of key-value\npairs when encoding but will only decode documents to maps. This has the\nside-effect that the information about order of keys in a BSON document is lost\nwhen it's decoded. Additionally the driver will accept both atoms and strings\nfor document keys but will only decode to strings.\n\n² BSON symbols can only be decoded.\n\n### Writing your own encoding info\n\nIf you want to write a custom struct to your mongo collection - you can do that\nby implementing `Mongo.Encoder` protocol for your class. The output should be a map,\nwhich will be passed to the Mongo database.\n\nExample:\n\n```elixir\ndefmodule CustomStruct do\n  @fields [:a, :b, :c, :id]\n  @enforce_keys @fields\n  defstruct @fields\n\n  defimpl Mongo.Encoder do\n    def encode(%{a: a, b: b, id: id}) do\n      %{\n        _id: id,\n        a: a,\n        b: b,\n        custom_encoded: true\n      }\n    end\n  end\nend\n```\n\nSo, given the struct:\n```elixir\n%CustomStruct{a: 10, b: 20, c: 30, id: \"5ef27e73d2a57d358f812001\"}\n```\n\nit will be written to database, as:\n```json\n{\n  \"a\": 10,\n  \"b\": 20,\n  \"custom_encoded\": true,\n  \"_id\": \"5ef27e73d2a57d358f812001\"\n}\n```\n\n## Usage\n\n### Installation:\n\nAdd `mongodb` to your `mix.exs` `deps`.\n\n```elixir\ndefp deps do\n  [\n    {:mongodb, \"~\u003e 0.5.1\"}\n  ]\nend\n```\n\nThen run `mix deps.get` to fetch dependencies.\n\n### Connection pooling\n\nBy default `mongodb` will start a single connection, but it also supports\npooling with the `:pool_size` option.\n\n```elixir\n# Starts an unpooled connection\n{:ok, conn} = Mongo.start_link(url: \"mongodb://localhost:27017/db-name\")\n\n# Gets an enumerable cursor for the results\ncursor = Mongo.find(conn, \"test-collection\", %{})\n\ncursor\n|\u003e Enum.to_list()\n|\u003e IO.inspect\n```\n\nIf you're using pooling it is recommend to add it to your application supervisor:\n\n```elixir\ndef start(_type, _args) do\n  children = [\n    {Mongo, [name: :mongo, database: \"test\", pool_size: 2]}\n  ]\n\n  opts = [strategy: :one_for_one, name: MyApp.Supervisor]\n  Supervisor.start_link(children, opts)\nend\n```\n\nSimple start with pooling:\n\n```elixir\n{:ok, conn} = Mongo.start_link(name: :mongo, database: \"test\", pool_size: 2)\n```\n\nOperate the `mongodb` with specify pool name in each query:\n\n```elixir\nMongo.find(:mongo, \"collection\", %{}, limit: 20)\n```\n\nMore pool options in [here](https://hexdocs.pm/db_connection/2.0.6/DBConnection.html#start_link/2-options).\n\n\n### Using with MongoDB Ecto\n\nIf you're using Mongo with the MongoDB Ecto library, where you have it defined in your config/runtime.exs like this:\n\n```elixir\nconfig :my_app, MyApp.Repo,\n  url: \"mongo connection url\"\n```\n\nYou'll want to do reference mongo like this:\n\n```elixir\nMongo.find(MyApp.Repo.pool(), collection, %{_id: %{\"$in\" =\u003e\"some_ids\"}})\n```\n\n### Replica Sets\n\nTo connect to a MongoDB cluster that is using replica sets, it is recommended to\nuse the `:seeds` list instead of a `:hostname` and `:port` pair.\n\n```elixir\n{:ok, pid} = Mongo.start_link(database: \"test\", seeds: [\"hostname1.net:27017\", \"hostname2.net:27017\"])\n```\n\nThis will allow for scenarios where the first `\"hostname1.net:27017\"` is\nunreachable for any reason and will automatically try to connect to each of the\nfollowing entries in the list to connect to the cluster.\n\n### Auth mechanisms\n\nFor versions of MongoDB 3.0 and greater, the auth mechanism defaults to SCRAM.\nIf you'd like to use [MONGODB-X509][] authentication, you can specify that as a\n`start_link` option.\n\n```elixir\n{:ok, pid} = Mongo.start_link(database: \"test\", auth_mechanism: :x509)\n```\n\n### AWS, TLS and Erlang SSL ciphers\n\nSome MongoDB cloud providers (notably AWS) require a particular TLS cipher that\nisn't enabled by default in the Erlang SSL module. In order to connect to these\nservices, you'll want to add this cipher to your `ssl_opts`:\n\n```elixir\n{:ok, pid} = Mongo.start_link(database: \"test\",\n      ssl_opts: [\n        ciphers: ['AES256-GCM-SHA384'],\n        cacertfile: \"...\",\n        certfile: \"...\")\n      ]\n)\n```\n\n### Examples\n\nUsing `$and`\n\n```elixir\nMongo.find(:mongo, \"users\", %{\"$and\" =\u003e [%{email: \"my@email.com\"}, %{first_name: \"first_name\"}]})\n```\n\nUsing `$or`\n\n```elixir\nMongo.find(:mongo, \"users\", %{\"$or\" =\u003e [%{email: \"my@email.com\"}, %{first_name: \"first_name\"}]})\n```\n\nUsing `$in`\n\n```elixir\nMongo.find(:mongo, \"users\", %{email: %{\"$in\" =\u003e [\"my@email.com\", \"other@email.com\"]}})\n```\n\n## Contributing\n\nThe SSL test suite is enabled by default. You have two options. Either exclude\nthe SSL tests or enable SSL on your MongoDB server.\n\n### Disable the SSL tests\n\n`mix test --exclude ssl`\n\n### Enable SSL on your Mongo server\n\n```bash\n$ openssl req -newkey rsa:2048 -new -x509 -days 365 -nodes -out mongodb-cert.crt -keyout mongodb-cert.key\n$ cat mongodb-cert.key mongodb-cert.crt \u003e mongodb.pem\n$ mongod --sslMode allowSSL --sslPEMKeyFile /path/to/mongodb.pem\n```\n\n* For `--sslMode` you can use one of `allowSSL` or `preferSSL`\n* You can enable any other options you want when starting `mongod`\n\n## License\n\nCopyright 2015 Justin Wood and Kobil Systems GmbH\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n    http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n\n[MONGODB-X509]: https://docs.mongodb.com/manual/tutorial/configure-x509-client-authentication/#authenticate-with-a-x-509-certificate\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felixir-mongo%2Fmongodb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Felixir-mongo%2Fmongodb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felixir-mongo%2Fmongodb/lists"}