docs: loud deprecation of badger v1 datastore (#11187)
* docs: loud deprecation of badger v1 datastore badger v1 (go-ds-badger) has not been maintained by its upstream maintainers for years and has known bugs (startup timeouts, shutdown hangs, fd exhaustion). make the deprecation loud and unavoidable: - print ERROR log line and bordered stderr message on every daemon start when a badger-based datastore is detected - mark badgerds and badgerds-measure init profiles as DEPRECATED - update docs/datastores.md and docs/config.md with migration guidance - add changelog highlight for v0.40 badger v1 support will be removed later in 2026. part of https://github.com/ipfs/kubo/issues/11186 * docs(changelog): link badger deprecation to #11186
Marcin Rataj committed
Feb 9, 2026 at 22:00 UTC
d405dfd1aebfc589659ed03aa981ce68f9272c16
5 files changed
+85
-17
config/profile.go
+14
-3
@@ -210,7 +210,9 @@ NOTE: This profile may only be applied when first initializing node at IPFS_PATH
210
},
211
},
212
"badgerds": {
213
- Description: `Configures the node to use the legacy badgerv1 datastore.
213
+ Description: `DEPRECATED: Configures the node to use the legacy badgerv1 datastore.
214
+This profile will be removed in a future Kubo release.
215
+New deployments should use 'flatfs' or 'pebbleds' instead.
216
217
NOTE: this is badger 1.x, which has known bugs and is no longer supported by the upstream team.
218
It is provided here only for pre-existing users, allowing them to migrate away to more modern datastore.
@@ -225,6 +227,14 @@ Other caveats:
227
* Good for medium-size datastores, but may run into performance issues
228
if your dataset is bigger than a terabyte.
229
230
+To migrate: create a new IPFS_PATH with 'ipfs init --profile=flatfs',
231
+move pinned data via 'ipfs dag export/import' or 'ipfs pin ls -t recursive|add',
232
+and decommission the old badger-based node.
233
+When it comes to block storage, use experimental 'pebbleds' only if you are sure
234
+modern 'flatfs' does not serve your use case (most users will be perfectly fine
235
+with flatfs, it is also possible to keep flatfs for blocks and replace leveldb
236
+with pebble if preferred over leveldb).
237
+
238
See configuration documentation at:
239
https://github.com/ipfs/kubo/blob/master/docs/datastores.md#badgerds
240
@@ -239,8 +249,9 @@ NOTE: This profile may only be applied when first initializing node at IPFS_PATH
249
},
250
},
251
"badgerds-measure": {
242
- Description: `Configures the node to use the legacy badgerv1 datastore with metrics wrapper.
243
-Additional '*_datastore_*' metrics will be exposed on /debug/metrics/prometheus
252
+ Description: `DEPRECATED: Configures the node to use the legacy badgerv1 datastore with metrics wrapper.
253
+This profile will be removed in a future Kubo release.
254
+New deployments should use 'flatfs' or 'pebbleds' instead.
255
256
NOTE: This profile may only be applied when first initializing node at IPFS_PATH
257
via 'ipfs init --profile badgerds-measure'
docs/changelogs/v0.40.md
+7
@@ -31,6 +31,7 @@ This release was brought to you by the [Shipyard](https://ipshipyard.com/) team.
31
- [📋 Long listing format for `ipfs ls`](#-long-listing-format-for-ipfs-ls)
32
- [🖥️ WebUI Improvements](#-webui-improvements)
33
- [📢 libp2p announces all interface addresses](#-libp2p-announces-all-interface-addresses)
34
+ - [🗑️ Badger v1 datastore slated for removal this year](#-badger-v1-datastore-slated-for-removal-this-year)
35
- [📦️ Dependency updates](#-dependency-updates)
36
- [📝 Changelog](#-changelog)
37
- [👨👩👧👦 Contributors](#-contributors)
@@ -313,6 +314,12 @@ $ ipfs config --json Addresses.NoAnnounce '["/ip4/172.17.0.0/ipcidr/16"]'
314
315
The [`server` profile](https://github.com/ipfs/kubo/blob/master/docs/config.md#server-profile) already [filters common private ranges](https://github.com/ipfs/kubo/blob/master/config/profile.go#L24-L43) via `Addresses.NoAnnounce`.
316
317
+#### 🗑️ Badger v1 datastore slated for removal this year
318
+
319
+The `badgerds` datastore (based on badger 1.x) is slated for removal. Badger v1 has not been maintained by its upstream maintainers for years and has known bugs including startup timeouts, shutdown hangs, and file descriptor exhaustion. Starting with this release, every daemon start with a badger-based repository prints a loud deprecation error on stderr.
320
+
321
+See the [`badgerds` profile documentation](https://github.com/ipfs/kubo/blob/master/docs/config.md#badgerds-profile) for migration guidance, and [#11186](https://github.com/ipfs/kubo/issues/11186) for background.
322
+
323
#### 📦️ Dependency updates
324
325
- update `go-libp2p` to [v0.47.0](https://github.com/libp2p/go-libp2p/releases/tag/v0.47.0) (incl. [v0.46.0](https://github.com/libp2p/go-libp2p/releases/tag/v0.46.0))
docs/config.md
+17
-6
@@ -4066,9 +4066,21 @@ Configures the node to use the pebble datastore with metrics. This is the same a
4066
Configures the node to use the **legacy** badgerv1 datastore.
4067
4068
> [!CAUTION]
4069
-> This is based on very old badger 1.x, which has known bugs and is no longer supported by the upstream team.
4070
-> It is provided here only for pre-existing users, allowing them to migrate away to more modern datastore.
4071
-> Do not use it for new deployments, unless you really, really know what you are doing.
4069
+> **Badger v1 datastore is deprecated and will be removed in a future Kubo release.**
4070
+>
4071
+> This is based on very old badger 1.x, which has not been maintained by its
4072
+> upstream maintainers for years and has known bugs (startup timeouts, shutdown
4073
+> hangs, file descriptor
4074
+> exhaustion, and more). Do not use it for new deployments.
4075
+>
4076
+> **To migrate:** create a new `IPFS_PATH` with `flatfs`
4077
+> (`ipfs init --profile=flatfs`), move pinned data via
4078
+> `ipfs dag export/import` or `ipfs pin ls -t recursive|add`, and decommission the
4079
+> old badger-based node. When it comes to block storage, use experimental
4080
+> `pebbleds` only if you are sure modern `flatfs` does not serve your use case
4081
+> (most users will be perfectly fine with `flatfs`, it is also possible to keep
4082
+> `flatfs` for blocks and replace `leveldb` with `pebble` if preferred over
4083
+> `leveldb`).
4084
4085
Also, be aware that:
4086
@@ -4078,17 +4090,16 @@ Also, be aware that:
4090
`flatfs`.
4091
- This datastore uses up to several gigabytes of memory.
4092
- Good for medium-size datastores, but may run into performance issues if your dataset is bigger than a terabyte.
4081
-- The current implementation is based on old badger 1.x which is no longer supported by the upstream team.
4093
4094
> [!WARNING]
4095
> This profile may only be applied when first initializing the node via `ipfs init --profile badgerds`
4096
4097
> [!NOTE]
4087
-> See other caveats and configuration options at [`datastores.md#pebbleds`](datastores.md#pebbleds)
4098
+> See other caveats and configuration options at [`datastores.md#badgerds`](datastores.md#badgerds)
4099
4100
### `badgerds-measure` profile
4101
4091
-Configures the node to use the **legacy** badgerv1 datastore with metrics. This is the same as [`badgerds` profile](#badger-profile) with the addition of the `measure` datastore wrapper.
4102
+Configures the node to use the **legacy** badgerv1 datastore with metrics. This is the same as [`badgerds` profile](#badger-profile) with the addition of the `measure` datastore wrapper. This profile will be removed in a future Kubo release.
4103
4104
### `lowpower` profile
4105
docs/datastores.md
+18
-7
@@ -93,13 +93,24 @@ When installing a new version of kubo when `"formatMajorVersion"` is configured,
93
Uses [badger](https://github.com/dgraph-io/badger) as a key-value store.
94
95
> [!CAUTION]
96
-> This is based on very old badger 1.x, which has known bugs and is no longer supported by the upstream team.
97
-> It is provided here only for pre-existing users, allowing them to migrate away to more modern datastore.
98
-> Do not use it for new deployments, unless you really, really know what you are doing.
99
-
100
-
101
-* `syncWrites`: Flush every write to disk before continuing. Setting this to false is safe as kubo will automatically flush writes to disk before and after performing critical operations like pinning. However, you can set this to true to be extra-safe (at the cost of a 2-3x slowdown when adding files).
102
-* `truncate`: Truncate the DB if a partially written sector is found (defaults to true). There is no good reason to set this to false unless you want to manually recover partially written (and unpinned) blocks if kubo crashes half-way through a write operation.
96
+> **Badger v1 datastore is deprecated and will be removed in a future Kubo release.**
97
+>
98
+> This is based on very old badger 1.x, which has not been maintained by its
99
+> upstream maintainers for years and has known bugs (startup timeouts, shutdown
100
+> hangs, file descriptor
101
+> exhaustion, and more). Do not use it for new deployments.
102
+>
103
+> **To migrate:** create a new `IPFS_PATH` with `flatfs`
104
+> (`ipfs init --profile=flatfs`), move pinned data via
105
+> `ipfs dag export/import` or `ipfs pin ls -t recursive|add`, and decommission the
106
+> old badger-based node. When it comes to block storage, use experimental
107
+> `pebbleds` only if you are sure modern `flatfs` does not serve your use case
108
+> (most users will be perfectly fine with `flatfs`, it is also possible to keep
109
+> `flatfs` for blocks and replace `leveldb` with `pebble` if preferred over
110
+> `leveldb`).
111
+
112
+- `syncWrites`: Flush every write to disk before continuing. Setting this to false is safe as kubo will automatically flush writes to disk before and after performing critical operations like pinning. However, you can set this to true to be extra-safe (at the cost of a 2-3x slowdown when adding files).
113
+- `truncate`: Truncate the DB if a partially written sector is found (defaults to true). There is no good reason to set this to false unless you want to manually recover partially written (and unpinned) blocks if kubo crashes half-way through a write operation.
114
115
```json
116
{
plugin/plugins/badgerds/badgerds.go
+29
-1
@@ -5,6 +5,7 @@ import (
5
"os"
6
"path/filepath"
7
8
+ logging "github.com/ipfs/go-log/v2"
9
"github.com/ipfs/kubo/plugin"
10
"github.com/ipfs/kubo/repo"
11
"github.com/ipfs/kubo/repo/fsrepo"
@@ -13,6 +14,8 @@ import (
14
badgerds "github.com/ipfs/go-ds-badger"
15
)
16
17
+var log = logging.Logger("plugin/badgerds")
18
+
19
// Plugins is exported list of plugins that will be loaded.
20
var Plugins = []plugin.Plugin{
21
&badgerdsPlugin{},
@@ -108,7 +111,32 @@ func (c *datastoreConfig) DiskSpec() fsrepo.DiskSpec {
111
}
112
113
func (c *datastoreConfig) Create(path string) (repo.Datastore, error) {
111
- fmt.Fprintln(os.Stderr, "⚠️ badgerds is based on badger 1.x, which has known bugs and is no longer supported by the upstream team. Please switch to a newer datastore such as pebbleds or flatfs.")
114
+ log.Error("badger v1 datastore is deprecated and will be removed later in 2026, migrate to flatfs or experimental pebbleds: https://github.com/ipfs/kubo/issues/11186")
115
+ fmt.Fprintf(os.Stderr, `
116
+╔════════════════════════════════════════════════════════════════════════════╗
117
+║ ║
118
+║ ERROR: BADGER v1 DATASTORE IS DEPRECATED ║
119
+║ ║
120
+║ This datastore is based on badger 1.x which has not been maintained ║
121
+║ by its upstream maintainers for years and has known bugs (startup ║
122
+║ timeouts, shutdown hangs, file descriptor exhaustion, and more). ║
123
+║ ║
124
+║ Badger v1 support will be REMOVED later in 2026. ║
125
+║ ║
126
+║ To migrate: ║
127
+║ 1. Create a new IPFS_PATH with flatfs (or experimental pebbleds ║
128
+║ if flatfs does not serve your use case): ║
129
+║ export IPFS_PATH=/path/to/new/repo ║
130
+║ ipfs init --profile=flatfs ║
131
+║ 2. Move pinned data via ipfs dag export/import ║
132
+║ or ipfs pin ls -t recursive|add ║
133
+║ 3. Decommission the old badger-based node ║
134
+║ ║
135
+║ See https://github.com/ipfs/kubo/blob/master/docs/datastores.md ║
136
+║ https://github.com/ipfs/kubo/issues/11186 ║
137
+║ ║
138
+╚════════════════════════════════════════════════════════════════════════════╝
139
+`)
140
p := c.path
141
if !filepath.IsAbs(p) {
142
p = filepath.Join(path, p)