MongoDB Store

The MongoDB store (store/mongo) uses the Grove ORM with mongodriver to persist data in MongoDB. It is the recommended store for teams that prefer document databases or need horizontal scalability.

When to use01

Document-oriented data -- flexible schemas that evolve with your application.
Horizontal scaling -- MongoDB sharding for large-scale deployments.
Cloud-native -- MongoDB Atlas for managed deployments.
Teams familiar with MongoDB -- leverage existing document database expertise.

Configuration02

import (
    "github.com/xraph/grove"
    "github.com/xraph/grove/drivers/mongodriver"
    "github.com/xraph/ctrlplane/store/mongo"
)

// Open a MongoDB connection via Grove's mongodriver.
db := grove.Open(mongodriver.New(
    mongodriver.WithURI("mongodb://localhost:27017"),
    mongodriver.WithDatabase("ctrlplane"),
))

s := mongo.New(db)
if err := s.Migrate(ctx); err != nil {
    log.Fatal(err)
}

With the app

cp, err := app.New(
    app.WithStore(s),
)

Collections03

The MongoDB store uses 15 collections:

Collection	Entity	Primary key
`cp_instances`	Instance	TypeID string
`cp_deployments`	Deployment	TypeID string
`cp_releases`	Release	TypeID string
`cp_health_checks`	HealthCheck	TypeID string
`cp_health_results`	HealthResult	TypeID string
`cp_metrics`	Metric	TypeID string
`cp_logs`	LogEntry	TypeID string
`cp_traces`	Trace	TypeID string
`cp_resource_snapshots`	ResourceSnapshot	TypeID string
`cp_domains`	Domain	TypeID string
`cp_routes`	Route	TypeID string
`cp_certificates`	Certificate	TypeID string
`cp_secrets`	Secret	TypeID string
`cp_tenants`	Tenant	TypeID string
`cp_audit_entries`	AuditEntry	TypeID string

Internals04

Aspect	Detail
Driver	Grove ORM with `mongodriver` (MongoDB)
Serialization	Intermediate BSON model structs with `bson:` tags
Identity	TypeID strings stored as `_id` field
Migrate	Creates compound and unique indexes on all collections
Ping	`db.Ping(ctx)`
Close	`db.Close()` to disconnect

Indexes

Migrate() creates compound indexes for efficient queries:

All collections -- (tenant_id, ...) compound indexes for tenant-scoped queries.
Instances -- unique (tenant_id, slug) index.
Tenants -- unique (slug) index.
Domains -- unique (hostname) index.
Secrets -- unique (tenant_id, instance_id, key) index.
Time-series -- (tenant_id, instance_id, timestamp) for metrics, logs, traces, and snapshots.

Limitations05

External dependency -- requires a running MongoDB instance or Atlas cluster.
No ACID transactions -- individual operations are atomic, but multi-document transactions require explicit sessions.
Index management -- Migrate() must run before first use to create indexes.

Comparison06

Feature	Memory	Badger	PostgreSQL	SQLite	MongoDB
Setup	None	Path only	DSN	File path	URI
Persistence	No	Yes	Yes	Yes	Yes
Multi-process	No	No	Yes	No	Yes
Query flexibility	Low	Low	High	Medium	High
Horizontal scaling	No	No	Read replicas	No	Sharding
Best for	Tests	Embedded KV	Production SQL	Embedded SQL	Production NoSQL

← Previous

SQLite Store

Instances