v25.1.0

[matthewmcneely]

We're pleased to announce the release of v25.1.0. Other than a fix to the dgraph import command, this release remains unchanged from the v25.1.0-preview1 that was released last week.

A big thanks to @xqqp for the posting list caching fixes that have greatly improved the heap performance of Dgraph. See an analysis that we completed prior to this release in the comments below. If you'd like to have profiles of the smoke tests, reach out to me @matthewmcneely, and I can provide them.

For the blow-by-blow changes introduced in #9515 and #9526, see the comments in those PRs.

Important note: The default for the cache superflag, --cache "size-mb=xxxx;" is now set to 4GB (4096Mb), up from 1G in v25. But as discussed in PR 9515, for most deployments this default actually improves the cache performance in this release, again a full analysis of the heap performance of this release can be found in the comments below. The only situation in which this change to the default cache size might be critical is one in which you are trying to run Dgraph in extremely limited RAM deployments. If that's your situation, reading the analysis below is recommended.

What's Changed

• fix(cache): Estimate size of posting lists by @xqqp in fix(cache): Estimate size of posting lists #9515
• fix(dev): Add jemalloc package to local docker image by @xqqp in fix(dev): Add jemalloc package to local docker image #9516
• fix(import): add sanity checks for connection string and bulk output directory in … by @shiva-istari in fix(import): add sanity checks for connection string and bulk output directory in … #9541
• fix(cache): make updating the max cost of posting cache work again by @xqqp in fix(cache): make updating the max cost of posting cache work again #9526
• chore: fixes for intermittent test failures by @matthewmcneely in chore: fixes for intermittent test failures #9517
• Update telemetry URL to use events.dgraph.io by @ryanfoxtyler in Update telemetry URL to use events.dgraph.io #9518
• chore: update readme, other docs for v25 and account change by @matthewmcneely in chore: update readme, other docs for v25 and account change #9522
• chore(deps): Update go minor and patch (main) by @renovate[bot] in chore(deps): Update go minor and patch (main) #9523
• .github/workflows: Migrate workflows to Blacksmith runners by @blacksmith-sh[bot] in .github/workflows: Migrate workflows to Blacksmith runners #9524
• chore(deps): bump golang.org/x/crypto from 0.43.0 to 0.45.0 by @dependabot[bot] in chore(deps): bump golang.org/x/crypto from 0.43.0 to 0.45.0 #9530
• chore: correct the renovate path by @matthewmcneely in chore: correct the renovate path #9531
• chore(test): change upgrade CI tests to weekly by @matthewmcneely in chore(test): change upgrade CI tests to weekly #9532
• chore: update module path and copyright disclaimers by @matthewmcneely in chore: update module path and copyright disclaimers #9533
• chore: disable nightly builds by @matthewmcneely in chore: disable nightly builds #9536
• chore: update the changelog (incl past releases) by @matthewmcneely in chore: update the changelog (incl past releases) #9538
• chore(docs): document release process by @matthewmcneely in chore(docs): document release process #9543

New Contributors

• @shiva-istari made their first contribution in fix(import): add sanity checks for connection string and bulk output directory in … #9541

Full Changelog: v25.0.0...v25.1.0

---

This discussion was created from the release v25.1.0.

[matthewmcneely]

What follows is an analysis of heap performance ran over several days against the v25.1.0-preview1 release.

Cache Implementation Performance Report

Release: v25.1.0-preview1

Test Duration: 48 hours (December 9-11, 2025)

Test Type: Continuous multi-threaded load test

---

Overview

This report evaluates the posting list cache improvements introduced in PR #9515 through analysis of
heap profiles collected during a 2-day continuous load test with moderately aggressive multi-threaded query and
mutation patterns.

The single alpha cluster ran on an old, crusty Mac laptop, running Ubuntu 18.04.6 LTS

Server: ubuntu-laptop - Linux 5.4.0-150-generic
CPU: Intel(R) Core(TM) i7-3615QM CPU @ 2.30GHz (8 cores)
Memory: 7.7G

The alpha was started with the cache superflag set to --cache "size-mb=4096;"--although that's not
necessary as that's the new default in this branch.

The cluster was loaded with the infamous 1 million movies dataset and against it ran a 2-day load
test with 12 threads from a remote machine. The load test ran a combination of reads and mutations.
Mutations consisted of a mix of updates and inserts.

During the load test, heap profiles were collected at various stages of the cluster's operation.
Below, the term 'stabilized' refers to the state of the cluster after it had reached a stable state
after the data load. The term 'after 48 hours' refers to the state of the cluster after 48 hours of
continuous operation from the start of the load test.

At the conclusion of the tests, prometheus metrics were collected--summaries of which are reported below.

Test Results

Memory Stability

The system demonstrated exceptional memory stability over the 48-hour test period:

• Initial State: 18.33 MiB at startup
• After Data Load: 2.292 GiB (with expected CPU spike to 307%)
• Stabilized (70 seconds): 2.545 GiB
• After 48 Hours: 2.526 GiB

Result: Zero memory growth over 2 days. The slight decrease from 2.545 GiB to 2.526 GiB
demonstrates effective garbage collection.

Heap Analysis

Metric	Baseline	Stabilized	After 48h	Assessment
Total Heap	1,231 MB	1,355 MB	1,355 MB	Stable
Ristretto Cache	780 MB	780 MB	780 MB	Fixed size
Cache % of Heap	63.4%	57.6%	57.6%	Appropriate
Container Memory	0.23%	33.15%	32.90%	Well within limits

Result: Heap stabilized at 1.35 GB after initial warmup and remained constant throughout the
test.

Allocation Efficiency

Over 48 hours of continuous operation:

• LocalCache.getInternal: 3.65 GB total allocated (76 MB/hour average)
• Posting List Operations: 33.45 GB allocated, 81.5 MB retained (99.8% garbage collected)
• Cache Overhead: 1.27 MB/minute sustained rate

Result: Highly efficient allocation patterns with aggressive GC preventing memory accumulation.

Cache Hit Ratio

Measured via Prometheus endpoint after 48 hours:

• Hit Ratio: 0.9997 (99.97%)
• Metric: dgraph_hit_ratio_posting_cache

Result: Exceptional cache effectiveness with only 0.03% of requests requiring disk access.

Workload Characteristics

Total operations processed over 48 hours:

• Total Queries: 5,404,861
• Total Mutations: 1,352,507 commits
• Transaction Success Rate: 99.9993% (only 10 discards)
• Query:Mutation Ratio: ~4:1 (read-heavy workload)
• Edges Created: 38.15 million
• Data Written: 253 GB
• Data Read from Disk: 918 GB

Result: Cache performed exceptionally under sustained, realistic multi-threaded load with
millions of operations.

Storage Layer Performance

Badger storage engine metrics after 48 hours:

• Total Gets: 852 million
• Successful Gets: 849.6 million (99.7% success rate)
• Block Cache Hit Ratio: 96.9% (dgraph_hit_ratio_postings_block)
• LSM Tree Size: 1.19 GB (stable)
• Value Log Size: 2.15 GB

Result: Posting list cache works in harmony with Badger's block cache for optimal I/O
efficiency.

System Stability

Raft consensus and system health indicators:

• Raft Leader Changes: 1 (single election at startup, zero failovers)
• Pending Proposals: 0 (no backlog)
• Active Mutations: 0 (clean state)
• Alpha Health Status: Healthy throughout test

Result: Rock-solid cluster stability with no consensus issues or operational anomalies.