Elixir Driver for MongoDB

Most query functions return a %Mongo.Stream{} struct, which implements the Enumerable protocol. The driver uses this to manage MongoDB sessions automatically: it checks out a session, streams batches from the server, and checks the session back in once the stream is exhausted.

Warning: Do not attempt to access the internal :docs field of the %Mongo.Stream{} struct directly. Doing so will prevent the session from being checked back in and will only retrieve the first batch of documents.

Correct Usage: Always process the result using an Enum or Stream function to ensure proper session lifecycle management.

# CORRECT: Use Enum to ensure session management
@topology
|> Mongo.aggregate(collection, pipeline, opts)
|> Enum.to_list()

# INCORRECT: Accessing internal docs directly leaves session open
%Mongo.Stream{docs: docs} = Mongo.aggregate(@topology, collection, pipeline, opts)
Enum.map(docs, fn elem -> elem end)

To use MONGODB-X509 authentication, you must provide specific SSL options in Mongo.start_link/1.

Requirements:

1. Set auth_mechanism: :x509.
2. Set username to the subject entry of the user certificate (e.g., "CN=cert-user").
3. Provide an empty password (required for current implementation).
4. Configure ssl_opts with verify: :verify_peer, a cacertfile, and a certfile.

Note: If using MongoDB Atlas with OTP 26, you may need to force TLS 1.2 using versions: [:"tlsv1.2"] in your SSL options to avoid compatibility issues.

opts = [
    url: "mongodb+srv://cluster0.xxx.mongodb.net/myFirstDatabase?authSource=%24external&retryWrites=true&w=majority",
    ssl: true,
    username: "CN=cert-user",
    password: "",
    auth_mechanism: :x509,
    ssl_opts: [
      verify: :verify_peer,
      cacertfile: to_charlist(CAStore.file_path()),
      certfile: '/path-to-cert/X509-cert.pem',
      customize_hostname_check: [
        match_fun: :public_key.pkix_verify_hostname_match_fun(:https)
      ]
    ]
]

Mongo.start_link(opts)

The driver provides a migration workflow similar to Ecto to maintain indexes and manage collections.

Workflow

1. Generate a migration: Run mix mongo.gen.migration <name> [topology] to create a new script in priv/mongo/migrations/ (or priv/<topology>/migrations/).
2. Define logic: Implement the up/1 and down/1 functions in the generated Elixir script.
3. Run migrations: Use mix mongo.migrate or call Mongo.Migration.migrate() within your application startup logic.

Migration Locking

To prevent multiple instances from running migrations simultaneously, the driver uses a software lock in the migration collection. If a migration fails and leaves the system locked, you can:

• Call Mongo.Migration.unlock() or mix mongo.unlock.
• Manually delete the document with {_id: "lock"} from the migration collection.

Supporting Multiple Topologies

You can organize migrations for different databases or clusters by using the topology option. This creates separate sub-folders and module namespaces.

• Generate: mix mongo.gen.migration add_indexes topology_2 creates scripts in priv/topology_2/migrations/.
• Run: Mongo.Migration.migrate([topology: :topology_2]) executes migrations for that specific topology.

# Example migration script
defmodule Mongo.Migrations.AddIndexes do
  def up(opts) do
    indexes = [
      [key: [email: 1], name: "email_index", unique: true]
    ]
    Mongo.create_indexes(:my_db, "my_collection", indexes)
  end

  def down(opts) do
    Mongo.drop_index(:my_db, "my_collection", "email_index")
  end
end

# Running migration in an application release
defmodule MyApp.Release do
  def migrate() do
    # ... setup code ...
    Mongo.start_link(name: :mongo_db, url: "mongodb://localhost:27017/my-database", timeout: 60_000)
    Mongo.Migration.migrate()
  end
end

While the driver uses maps and keyword lists for documents, you can use Mongo.Collection to automate the conversion between MongoDB maps and Elixir structs. This provides support for default values, type specifications, and nested structures.

To use it, include use Mongo.Collection and define your attributes using the document macro. This automatically generates functions like load/2 (map to struct) and dump/1 (struct to map).

Note on Querying: Mongo.Collection does not automatically rewrite attribute names in queries or updates. You must use the actual MongoDB attribute names (e.g., if you aliased :uuid to :u, you must query using :u) when performing database operations.

defmodule Label do
    use Mongo.Collection

    document do
      attribute :name, String.t(), default: "warning"
      attribute :color, String.t(), default: :red
    end
end

# Usage:
x = Label.new()
m = Label.dump(x)
Label.load(m)