Mastodon Migration Benchmarks: Database and Transfer Thresholds

By 4FreeForums Editors · Published October 30, 2026 · Sources linked below

Relocating an established federated community node to fresh server hardware requires disciplined sequencing across multiple application tiers. While moving an operational Mastodon deployment inevitably involves planned downtime, understanding critical data boundaries and resource behaviors prevents data loss across relational tables, active job queues, and media directories.

15 Gigabytes: PostgreSQL Dump Duration and Tuning Thresholds

The core bottleneck of any Mastodon database transfer centers on PostgreSQL data extraction and restoration. According to the Migrating to a new machine - Mastodon documentation, both dumping and restoring database archives can consume multiple hours once reaching a ~15GB backup file size. Because of this duration, administrators of moderate to large instances may want to temporarily tune Postgres performance settings strictly to handle dump and restore throughput before reverting to production defaults.

On the destination machine, administrators set up the environment using standard production guidance without running the automated database setup utility. Instead, create a blank database from the clean template database:

createdb -T template0 mastodon_production

If your setup requires passwords, configure the database user on the destination to use the same password before running operations. Creating reliable snapshots ahead of these operations aligns with standard practices for how to back up your forum and verify database state integrity.

CPU Allocation (-j#): Scaling Multi-Threaded Restoration

To reduce restoration downtime, the standard PostgreSQL custom-format dump archive enables multi-core unpacking. The database dump is generated on the source system as the dedicated application user:

pg_dump -Fc mastodon_production -f backup.dump

Once transferred to the new host via network copy tools like rsync or scp, the restoration process can leverage multi-threading:

pg_restore -Fc -j# -U mastodon -n public --no-owner --role=mastodon -d mastodon_production backup.dump

In this command, the literal hash symbol in the -j# parameter is replaced with the specific number of CPUs available on the destination server. If the administrative system user differs on the replacement machine, both the -U flag and the --role parameter must be adjusted to match that local user account.

1 Day Ahead: Pre-Migration DNS TTL and Downtime Notices

Network propagation delays can needlessly prolong community service interruptions if caching intervals are neglected. The documentation recommends lowering your domain DNS TTL to a short duration, such as 30 minutes, approximately a day in advance of the scheduled migration. Lowering this interval allows public resolvers to discover the new destination IP address rapidly once the final network switch occurs.

While the transfer steps are underway, administrators can inform active visitors by editing the maintenance error file on the old node:

• Customize ~/live/public/500.html to display a clear notice indicating maintenance is in progress.
• Halt background activities by running systemctl stop 'mastodon-*.service' on the old host.
• Inspect propagation progress across global resolvers using external tools like whatsmydns.net.
• Point your local administrative machine directly to the replacement server early by modifying your workstation /etc/hosts file.

Zero Job Loss: Preserving Redis in /var/lib/redis/

Maintaining queued federated deliveries and background jobs requires migrating Redis state cleanly. The Redis datastore in /var/lib/redis/ retains pending background Sidekiq jobs that have not yet executed. To prevent state divergence, administrators must avoid running Redis on the destination while copying files.

The exact preservation workflow involves three steps on the source host as root:

redis-cli SAVE
systemctl stop redis-server.service
rsync -avz /var/lib/redis/ root@example.com:/var/lib/redis

Before executing this network copy, confirm that Redis is stopped on the new machine with systemctl stop redis-server.service so that active local processes do not overwrite the incoming database files. Managing queue workers and database connections cleanly is essential when scaling Mastodon concurrency with Puma, Sidekiq, and PgBouncer.

Storage Architecture: Media Directories vs. Cloud Object Storage

User-generated assets represent the largest storage footprint on standalone installations. The ~/live/public/system directory houses user-uploaded images, avatars, and video attachments. Administrators running local storage must mirror this directory to the new server:

rsync -avz ~/live/public/system/ mastodon@example.com:~/live/public/system/

However, if the community routes uploads to external S3 object storage, the entire media directory synchronization step can be skipped entirely, saving substantial migration time. Beyond media, administrators must copy the environment configuration file at ~/live/.env.production, which stores database credentials, application secrets, and environment flags.

Post-Cutover Execution: Rebuilding Feeds and Search Indices

After migrating files, database tables, and configuration files, administrators complete application compilation and start systemd units on the new server. Under the application user, precompile assets:

RAILS_ENV=production bundle exec rails assets:precompile

As root, reload service managers and launch daemons:

systemctl daemon-reload
systemctl start redis-server
systemctl enable --now mastodon-web mastodon-sidekiq mastodon-streaming
systemctl restart nginx

Once online, rebuilding user timelines is necessary to restore home feeds: run RAILS_ENV=production ./bin/tootctl feeds build, which varies in duration based on user count. For deployments utilizing external search, execute RAILS_ENV=production ./bin/tootctl search deploy to rebuild Elasticsearch indices, as described in the official Mastodon documentation on server migration.

Sources

• Migrating to a new machine - Mastodon documentation

Published October 30, 2026. No affiliate links on this page. Facts come from the sources linked above; check them for updates.