Skip to content
LinkMesh Docs

Storage backends

The LinkMesh server keeps its operational state in a database. You get to choose which one:

  • BoltDB — an embedded, file-based database that ships inside the server binary. This is the default, and it needs no external database service at all.
  • MongoDB — an external database you run yourself. Use this when you want to run more than one server instance (high availability).

This page explains what the storage backend holds, the trade-offs between the two, and how to switch. For the step-by-step MongoDB setup, see Deploy with MongoDB.

What the storage backend holds

The storage backend is where the server keeps its operational state:

  • the collector fleet (which collectors exist, their status and last-seen times)
  • collector lifecycle events
  • per-component throughput metrics (what the dashboard charts)
  • the audit log
  • enrollment and OTLP tokens

Two things are not in this database, and it’s worth being clear about the boundary:

  • Your pipeline configuration — sources, destinations, pipelines, and routes — lives in the Git-backed config store, not in the storage backend. See where your data lives in the architecture overview.
  • Your telemetry — logs, metrics, and traces — is never stored by LinkMesh at all. It flows through your collectors straight to your backends.

The two backends at a glance

BoltDB (default)MongoDB
TypeEmbedded, file-basedExternal database service
External dependencyNoneA MongoDB cluster you run
Server instances supportedOneOne or many
High availabilityNoYes (with a replica set)
Best forSingle host, dev, proof-of-conceptProduction, HA, larger fleets
Config keystorage.backend: boltstorage.backend: mongodb

BoltDB — the zero-dependency default

Out of the box the server writes its state to a single BoltDB file on local disk (storage.boltPath, default /data/linkmesh/state.db). Nothing else to install, configure, or operate — this is why the quickstart gets you running without a database to set up.

BoltDB is a great fit for:

  • a single-host install
  • dev and evaluation
  • small fleets where one server instance is plenty

The one thing BoltDB cannot do is back more than one server instance: the file lives on one host’s disk, so a second instance can’t share it. The moment you want two server instances behind a load balancer, you need MongoDB.

MongoDB — the database for high availability

Pointing the server at an external MongoDB database lets multiple server instances share one source of truth for fleet state. That shared database is the foundation of a highly-available deployment.

Switch with storage.backend: mongodb and a connection string:

storage:
  backend: mongodb
database:
  uri: "mongodb+srv://linkmesh-app:CHANGEME@cluster.example.mongodb.net/linkmesh?retryWrites=true&w=majority"

The full set of storage.* and database.* keys is documented in the configuration reference.

Choosing a backend

  • One server instance, and that’s enough? Stay on BoltDB. It’s the default for a reason — less to run, nothing to back up separately.
  • Need the control plane to survive a node failure, or expect to outgrow one instance? Use MongoDB and run a highly-available deployment.

You don’t choose based on fleet size alone — even a large fleet runs fine on a single BoltDB-backed instance. The deciding question is whether you need more than one server instance, which only MongoDB supports.

Switching backends

Set storage.backend and restart the server. There is no in-place migration tool yet, so the two backends start from independent state:

  • Greenfield: just start on MongoDB from the beginning — set the backend before you enrol any collectors.
  • Already have state on BoltDB? Your sources, destinations, pipelines, and routes live in the Git-backed config store and follow the new server automatically. Re-enrol your collectors against the MongoDB-backed server to rebuild the fleet state.