apache / apache/couchdb

CouchDB should provide advice on safe use with BTRFS storage

Open
#4,227 10 comments 0 reactions 0 assignees View on GitHub
documentation
Dominant language
Erlang
Stars
7k
Forks
1.1k
Avg merge
1d 16h
Merged PRs (30d)
9

Description

## Summary

BTRFS filesystem does not play well with database files due to its Copy-on-Write feature. This kind of files should be created inside a folder whose CoW feature is turned off.

See https://btrfs.wiki.kernel.org/index.php/Gotchas#Fragmentation

> Files with a lot of random writes can become heavily fragmented (10000+ extents) causing thrashing on HDDs and excessive multi-second spikes of CPU load on systems with an SSD or large amount a RAM.
On servers and workstations this affects databases and virtual machine images.

Disabling CoW for "data" folder on a BTRFS filesystem would be a wise move.

## Possible Solution

Following script fixes the issue:

```bash
#!/bin/bash
set -eu

curr="/var/lib/couchdb"
new="$curr.new"

if lsattr $curr -a | grep /\.$ | grep -- "-C-" > /dev/null; then
echo "CoW is already disabled for $curr. Doing nothing."
exit 0
fi
systemctl stop couchdb
mkdir $new
chown couchdb:couchdb $new
chattr +C $new
rsync -avxHAX --info=progress2 $curr/ $new/
mv $curr $curr.bak
mv $new $curr
systemctl start couchdb

echo "---------------------------------------------"
echo "Changes made successfully."
echo "You can delete $curr.bak if everything works correctly."
echo "---------------------------------------------"
```

Contributor guide

Open the contributing guide

Research direction

Start by reviewing the BTRFS gotcha and the proposed Bash migration script, which uses /var/lib/couchdb and systemctl. Locate the appropriate CouchDB storage documentation and describe safe BTRFS use, including disabling CoW for the data directory; done means users have clear, accurate operational guidance.

Written by the indexing model from the issue text.

Assessment

Tech stack
bash
Domain
databases
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.