How zookzook/elixir-mongodb-driver works
Project type and purpose
• This is a library–an Elixir driver for MongoDB. Its purpose is to provide a complete MongoDB client implementation in Elixir, including connection pooling, BSON encoding/decoding, change streams, GridFS, transactions, migrations, bulk writes, telemetry, and various MongoDB commands.
File structure
• Top-level: configuration (config/*.exs), CI workflows, examples, an “insights” Phoenix app, the driver source under lib/ (split into bson/, mongo/, mongo_db_connection/, session/, tasks/, utilities), tests under test/, Mix project files.
• “examples” demonstrate usage patterns (change streams, CRUD, AWS X.509).
• “insights” is a Phoenix-based monitoring UI leveraging the driver.
• Core driver modules implement key features:
• lib/bson/* – BSON codec, types, encoder/decoder protocols
• lib/mongo/* – the public API (Mongo module), command modules, topology, events, bulk writes, GridFS, migration, change streams, session management
• lib/mongo_db_connection/* – integration with DBConnection for pooling
• lib/session/* – server-side session and transaction wrappers
• lib/tasks/mongo.ex – Mix tasks for migrations
README for additional insights
• Confirms features: versions supported, pooling via DBConnection, streaming cursors, GridFS, change streams, transactions, telemetry, migrations, compression, auth mechanisms, plug-ins, and example usages.
• Mentions Telemetry events, Mix.Tasks.Mongo for migrations, external dependencies (DBConnection, Telemetry, optional :ezstd, Phoenix in insights).
Main components
a. Client application layer
• User code (can be plain Elixir app, Ecto adapter, Phoenix “insights” web UI, or example scripts)
b. Public API layer (Mongo module suite)
• Mongo façade
• Mongo.Repo convenience wrapper
• Mongo.Collection macros
c. Core driver internals
• Connection management & pooling
– DBConnection Behaviour
– Mongo.MongoDBConnection adapter
– TCP/SSL socket under the hood
• BSON subsystem
– BSON.Encoder, BSON.Decoder, types, utilities
• Topology & server monitoring
– Replica set discovery, Topology, Monitor
• Command execution
– CRUD commands, aggregation, change streams, bulk writes, GridFS, transactions
• Session & transaction manager
– Mongo.Session, session pooling, transaction boundaries
• Migration engine
– Mix tasks (Mix.Tasks.Mongo*), Mongo.Migration lock/unlock, scripts under priv/mongo/migrations
• Telemetry & logging
– Telemetry events [:mongodb_driver, :execution], optional Logger via Mongo.EventHandler
d. External systems and dependencies
• MongoDB deployment (single node, replica set, sharded cluster)
• Optional compressors (:zlib, :zstd via :ezstd)
• Optional Phoenix app (insights) for monitoring
• DBConnection and Telemetry hex packages
Relationships and data flows
• The Client calls the Mongo API → API builds BSON document via BSON.Encoder → passes to DBConnection adapter → opens/borrows a connection from the pool → encodes request onto TCP/SSL → sent to MongoDB → receives wire protocol response → BSON.Decoder decodes → returns results to client.
• Session/Transaction: client wraps calls in Mongo.transaction/3, driver attaches session metadata, commits/aborts via session module.
• Change streams and GridFS: special long-lived cursors managed by event handlers/streaming modules.
• Migration: at startup or via Mix task, migration scripts run through Mongo.Migration, use the same connection subsystem.
• Telemetry: each command emits execution duration event.
Architectural patterns & design principles
• Behaviour abstraction: DBConnection behaviour for pooling, telemetry hooks, event handlers for logging/monitoring.
• Protocols: Elixir protocols for BSON encoding/decoding and user-defined structs.
• Supervision: OTP supervisors for connection pool, monitor processes, example Phoenix app has its own supervision tree.
• Modular design: separate modules for codecs, connections, commands, sessions, migrations.
• Streaming: use of Elixir Streams and Enumerable protocol for cursors and bulk writes.