VictoriaMetrics: a Prometheus-compatible time series database in one binary

The problem VictoriaMetrics targets: long-term metric storage without a dependency chain

Prometheus is good at scraping and alerting, but it was not designed as a long-term store, and teams that keep months or years of metrics usually end up running a second system alongside it. VictoriaMetrics is aimed at that gap. The README calls it a fast, cost-effective and scalable solution for monitoring and managing time series data, and lists long-term storage for Prometheus as the first prominent feature, along with use as a drop-in replacement for Prometheus and Graphite in Grafana.

The audience is infrastructure and platform teams that already produce Prometheus exposition format or remote write traffic: Kubernetes clusters, APM pipelines, IoT sensors, industrial telemetry, financial data. The README names those workloads explicitly under its big data bullet. It is not aimed at application developers who want an embedded database, and it is not a general SQL store. If your data is not time series, this is the wrong tool.

How VictoriaMetrics works: one binary, many ingestion protocols, one query view

The architecture is deliberately flat. The README states there are no dependencies, configuration is through command-line flags, and the defaults are fine-tuned. A single small binary handles ingestion, storage and querying. The repository layout matches that claim: the top-level app/ directory holds the binaries, lib/ holds the shared storage and query code, and go.mod shows the storage engine is assembled from the project's own libraries (metricsql for the query language, fastcache, easyproto) rather than from an external database engine.

Ingestion is protocol-first. The README lists Prometheus exporters, the Prometheus remote write API, the Prometheus exposition format, InfluxDB line protocol over HTTP, TCP and UDP, Graphite plaintext with tags, OpenTSDB put messages, HTTP OpenTSDB /api/put requests, and JSON line format. That breadth is the practical reason teams pick it: existing agents keep sending what they already send.

Querying supports both PromQL and MetricsQL, which the README describes as the more performant of the two. The global query view is the other structural idea: multiple Prometheus instances or other data sources can ingest into one VictoriaMetrics instance and be queried through a single query, which removes the per-instance federation problem.

There are two deployment shapes, both open source under Apache-2.0: a single-node version and a cluster version. The README does not describe the internal sharding of the cluster version in the excerpt available, so treat that as documentation to read before sizing.

Installing VictoriaMetrics and running a first query

The README points to binary releases on GitHub, Docker images on Docker Hub and Quay, and source code. It also points to a quick start guide and a key concepts page, and says the default configuration is fine-tuned. The README does not reproduce the exact server flags or the HTTP listen port in the text available here, so check the quick start guide before running anything in production. What the repository does give is the Docker image name and the build targets.

To build from source, the Makefile at the repository root defines the target set. The default target builds the full family of binaries:

make all

That target produces victoria-metrics-prod along with vmagent-prod, vmalert-prod, vmalert-tool-prod, vmauth-prod, vmbackup-prod, vmrestore-prod and vmctl-prod. If you only want the server plus the utility set, the Makefile also defines a vmutils target:

make vmutils

Once the server is running, the README describes adding it to Grafana as a drop-in replacement for Prometheus, which means the Grafana data source is the Prometheus one pointed at the VictoriaMetrics query endpoint. The README does not state that endpoint in the excerpt available, so take it from the quick start guide.

Where VictoriaMetrics stops being the right answer

The README is candid that the project evolves fast and directs readers to the changelog and to a how-to-upgrade page. That is a real operational cost: a fast-moving database means upgrade notes are part of your runbook, not an afterthought. The README does not document rollback in the excerpt available, so if downgrade matters to you, that is a question to resolve before you commit.

The second limit is scope. The README describes VictoriaMetrics as long-term storage for Prometheus and as a drop-in replacement in Grafana. Those are storage and query roles. It does not claim to replace alerting or service discovery, and the repository ships separate binaries for those adjacent jobs (vmalert, vmagent, vmauth, vmbackup, vmrestore, vmctl, all listed in the Makefile). If you expect one process to do everything Prometheus does, you will be assembling several components.

The third is the single-node ceiling. The README offers a cluster version for scale, but moving from one binary to a cluster is an architectural change, not a flag. Teams that pick single-node for simplicity and later need horizontal scale should plan that migration rather than assume it is incremental.

Finally, if your queries are relational, or your workload is log search rather than metrics, this is the wrong category of tool. The README's feature list is metric-shaped from top to bottom.

VictoriaMetrics versus Prometheus and versus ClickHouse

Against Prometheus, the difference is role, not syntax. VictoriaMetrics speaks PromQL and accepts Prometheus remote write and exposition formats, so it slots in where Prometheus would store data. The README markets it as long-term storage for Prometheus and a drop-in replacement in Grafana, which is a narrower claim than replacing Prometheus end to end. The practical split many teams land on is Prometheus or vmagent for collection, VictoriaMetrics for storage and query.

Against ClickHouse, the difference is the data model. ClickHouse is a general analytical column store that you shape with SQL and your own schema. VictoriaMetrics arrives with a time series model, a query language built for it, and ingestion protocols for metrics already in place. That means less design work for metric workloads and less flexibility for anything that is not a metric.

The cluster version is the third axis. The README also points to Thanos and Mimir as adjacent topics in the repository metadata, and the honest framing is that all three address long-term Prometheus storage with different operational shapes. VictoriaMetrics' distinguishing choice is that the single-node version is a complete system on its own, so you can start without a distributed architecture at all.

Licence and the upgrade treadmill

Both the single-node and cluster versions are published under Apache License 2.0, per the README and the LICENSE file at the repository root. That is a permissive licence, and the README notes the open-source status of both editions explicitly. Enterprise features and long-term support releases exist separately and are described as publicly available for evaluation with a free trial licence. Read the enterprise page and the LTS release notes if you need support guarantees; this is a description of what the repository states, not legal advice.

Upgrade cost is the part worth budgeting. The README says the project evolves fast and links a changelog and a how-to-upgrade page. The repository's release cadence supports that: v1.150.0, v1.151.0 and v1.152.0 all landed within roughly a month of each other. Frequent releases are good for fixes and bad for teams that upgrade rarely, because the distance between your version and current grows quickly. The Makefile also shows the build produces a family of binaries (victoria-metrics-prod, vmagent-prod, vmalert-prod, vmauth-prod, vmbackup-prod, vmrestore-prod, vmctl-prod), so an upgrade is rarely a single artifact swap if you run more than the server.

Editorial conclusion

Adopt VictoriaMetrics if you already emit Prometheus-style metrics and want a single binary that handles ingestion, storage and querying without a separate dependency chain, or if you need the cluster version for horizontal scale. Do not adopt it expecting a general-purpose SQL database or a full drop-in replacement for every Prometheus operational behaviour: the README positions it as long-term storage for Prometheus and as a drop-in replacement in Grafana, which is narrower than replacing the whole Prometheus deployment. Before committing, verify the retention and snapshot behaviour against your own data volume, and read the upgrade notes linked from the README, because the project states it evolves fast and publishes a changelog.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. VictoriaMetrics/VictoriaMetrics on GitHub