MongoDB Explorer
Relevant source files
The following files were used as context for generating this wiki page:
The MongoDB Explorer is a specialized module within KamehaDB designed for interacting with MongoDB instances. It provides a comprehensive interface for browsing databases and collections, performing document CRUD operations, and executing complex aggregation pipelines. The system is split between a React-based desktop frontend and a Node.js sidecar that handles the actual database driver communication.
Sources: AGENTS.md:12-15, apps/desktop/src/components/mongo-view.tsx:28-30
Architecture and Data Flow
The MongoDB Explorer follows a client-server architecture where the Desktop UI communicates with a Hono-based sidecar. The sidecar utilizes the official mongodb driver to interact with the database.
System Interaction Flow
The diagram below illustrates how a user request for data flows from the UI through the sidecar to the MongoDB instance.
The sidecar includes a caching layer to improve performance for metadata requests like database and collection listings.
Sources: apps/sidecar/src/routes/mongo.ts:25-35, apps/sidecar/src/adapters/mongodb.ts:66-70
Core Components
1. Document Browser (MongoView)
The main interface for viewing and managing documents within a specific collection. It supports two viewing modes:
- Table View: A grid-based layout for structured data comparison.
- List View: An expandable card-based layout ideal for deeply nested JSON documents.
Key features include client-side searching across string fields, server-side pagination (default 20 documents), and multi-format export (JSON/CSV).
Sources: apps/desktop/src/components/mongo-view.tsx:50-100, apps/desktop/src/components/mongo-view.tsx:145-180
2. Aggregation Editor (MongoQuery)
A Monaco-powered editor that allows users to write and execute MongoDB aggregation pipelines using JSON5 syntax. It provides:
- Real-time syntax highlighting for JavaScript/JSON.
- Database and collection selectors.
- Results rendered in a paginated grid.
- Keyboard shortcuts (Ctrl+Enter) for execution.
Sources: apps/desktop/src/components/mongo-query.tsx:35-70, apps/desktop/src/components/mongo-query.tsx:115-130
3. MongoDB Adapter
The sidecar-side logic that abstracts MongoDB operations into a standard interface defined in @kamehadb/shared.
| Function | Description | Source |
|---|---|---|
findDocuments | Fetches documents with optional filtering, sorting, and regex-based search. | apps/sidecar/src/adapters/mongodb.ts:79 |
aggregate | Executes an aggregation pipeline with automated $limit and $skip injection. | apps/sidecar/src/adapters/mongodb.ts:182 |
updateDocument | Modifies existing documents using $set operations. | apps/sidecar/src/adapters/mongodb.ts:153 |
getCollectionStats | Retrieves document counts and index metadata (name, keys, uniqueness). | apps/sidecar/src/adapters/mongodb.ts:236 |
Data Models and Safety
Connection Configuration
MongoDB connections require a standard URI connection string. Unlike SQL databases in the project, MongoDB does not strictly require separate host/port fields if the URI is provided.
export const CreateConnectionProfileSchema = BaseCreateSchema.refine(
(data) => {
if (data.kind === 'mongodb' && !data.connectionString) {
return false;
}
return true;
},
// ... validation message
);
Sources: packages/shared/src/index.ts:40-55
Read-Only Enforcement
KamehaDB enforces a readonly property at the connection level. If a connection is marked as read-only, the sidecar explicitly blocks update and delete routes for MongoDB.
Serialization Logic
Since MongoDB uses BSON types like ObjectId and Date, the adapter includes a serializeDocument helper to convert these types into standard JSON strings (e.g., ISO strings for dates) before sending them to the frontend.
Sources: apps/sidecar/src/adapters/mongodb.ts:15-27
API Endpoints Summary
The sidecar exposes several endpoints specific to MongoDB management:
| Endpoint | Method | Purpose |
|---|---|---|
/mongo/:connectionId/databases | GET | Lists all databases in the cluster. |
/mongo/:connectionId/collections | GET | Lists collections for a specific database. |
/mongo/:connectionId/find | POST | Performs a find operation with filters. |
/mongo/:connectionId/aggregate | POST | Executes an aggregation pipeline. |
/mongo/:connectionId/stats | GET | Returns index and document count stats. |
/mongo/:connectionId/update | POST | Updates a document by filter. |
Sources: apps/sidecar/src/routes/mongo.ts:25-240
Conclusion
The MongoDB Explorer provides a robust set of tools for both simple data browsing and complex analysis. By utilizing a shared adapter contract and a dedicated sidecar router, it maintains architectural consistency with the rest of KamehaDB while catering to the specific needs of document-oriented storage, such as BSON serialization and aggregation pipeline support.