MongoDB Store

The MongoDB store uses the MongoDB Go Driver v2 to persist data in MongoDB. It is the recommended store for teams that prefer document databases or need horizontal scalability.

When to use

• 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.

Configuration

import "github.com/xraph/ctrlplane/store/mongo"

s, err := mongo.New(mongo.Config{
    URI:      "mongodb://localhost:27017",
    Database: "ctrlplane",
})

With the app

s, err := mongo.New(mongo.Config{
    URI:      "mongodb+srv://user:pass@cluster.mongodb.net",
    Database: "ctrlplane",
})

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

Collections

The MongoDB store uses 15 collections:

Internals

BSON models

Each entity has an intermediate BSON model struct that handles serialization:

type instanceModel struct {
    ID           string `bson:"_id"`
    TenantID     string `bson:"tenant_id"`
    Name         string `bson:"name"`
    Slug         string `bson:"slug"`
    // ...
}

Conversion functions (toInstanceModel / fromInstanceModel) translate between domain entities and BSON models. TypeIDs are stored as strings and parsed back on read.

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.
• Health results — (check_id, checked_at) for latest-result queries.
• Audit entries — (tenant_id, created_at) for chronological queries.

Error mapping

Security

The ListSecrets method uses a MongoDB projection to exclude the value field from results, so secret values are never returned in list operations.

Limitations

• 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.

Comparison