Backup & Migration

ram0ng1

📦 Backup & Migration - Portable Backups for Flarum 2

A complete backup, export and import system for Flarum - bundles your forum
into a single .flarum file, restores it on the same install or a different
one, with optional libsodium encryption.

Admin dashboard

Inspired by All-in-One WP Migration, but written from scratch with a custom
streaming format (no .wpress, no zip) so multi-GB backups never need to fit
in memory.

✨ What it does

Single portable .flarum file — database, public/assets, storage,
and any installed extensions (workbench or vendor)
Per-extension picker with a tag on each row showing whether it's
composer-managed or local
composer.json + composer.lock travel along when bundling extensions,
so vendor extensions stay reproducible on the destination
Resumable progress on both export and import (₄ MB per HTTP request)
with live progress bars and an upload % indicator
Optional libsodium encryption — sealed-box wraps a per-archive
XChaCha20-Poly1305 stream key. Public key in the database, private key
only in config.php
Cross-server transfer — encrypt to a foreign public key, paste the
matching private key at import time
Automatic URL rewriting — the source URL is recorded in the archive
header and rewritten across settings, posts.content and
posts.parsed_content when restoring on a different host
Selectable restore — per-section and per-extension checkboxes,
populated from the archive's manifest
Plus: foreign-key-safe DDL replay, node_modules/.git pruning,
dedicated "you've been logged out" screen when a DB restore replaces the
admin session

📸 Screenshots

Creating a backup
Create modal

Selecting what to restore
Restore selection

After a successful restore
Logout screen

📥 Install

composer require ramon/backup
php flarum migrate
php flarum cache:clear

Then enable Backup & Migration under the Extensions page.

🔗 Links

GitHub: https://github.com/ram0ng1/backup
Packagist: https://packagist.org/packages/ramon/backup
Issues / feedback: https://github.com/ram0ng1/backup/issues

It's MIT-licensed and on Packagist. Tested on Flarum 2.0 with MySQL 8 / PHP 8.3
and 8.5. libsodium is required only when you opt into encryption.

Would love feedback — especially edge cases around vendor-extension restores
and giant archives. Bug reports and PRs welcome on GitHub. 🙌

navindra

ram0ng1 Single portable .flarum file — database, public/assets, storage,
and any installed extensions (workbench or vendor)

Holy smokes, this one is next level! 👏

自在の偶

I really need this

jedafe

Thank you very much for this great extension 🙏

I tried installing Flarum 2.× on Postgres but didn't work out due to "No Driver Found" error and later went on by installing it on MySQL database. But my major aim was to use Postgres. Though I later figure out the issue with the Postgres install after I have spent hours installing and configuring my Flarum on MySQL.

So my question is:

Can I use this extension to migrate Flarum from my old MySQL installed to the newly installed Postgres?

MaxDob

Great extension that is really needed! I encountered a problem when creating a backup. Is there a solution?

ram0ng1

jedafe
MaxDob

It doesn't support PostgreSQL yet. But I'll check the current status later today.

ram0ng1

Try:

composer update ramon/backup -W

php flarum migrate

php flarum cache:clear

jedafe

ram0ng1 Thanks alot. I'll try it out.

GreXXL

ram0ng1 that’s interesting. You also built a DB Migration Tool with this. Interested to see how well ports between different databases.

Karl

GreXXL thanks for mentioning that. I am halting all work towards linkrobins/db-transfer lol

ram0ng1

GreXXL Even though the Flarum core supports extensions, third-party ones might not work. I've added a warning stating that some extension data is lost when selected (mostly due to database incompatibility).

The extension is not perfect yet, and I'm already working on improving compatibility across all drivers.

During my own MySQL to PostgreSQL tests, I even found my Avocado theme to be incompatible, and posts weren't migrated. In short: I'm still working on improvements.

Database Migration Architecture

Current Capabilities:

Engine-Neutral Schema: Uses an abstract model (ColumnType.php) to normalize column types into ₂₅ universal types (BIGINT, JSON, UUID, etc.).
Multi-Engine Support: Includes specific Introspectors and Emitters for MySQL, MariaDB, PostgreSQL, and SQLite.
Smart Fixups: * Postgres: Defers Foreign Keys to prevent creation errors and resyncs sequences (setval) to avoid ID collisions.
- SQLite: Coerces auto-incrementing fields to INTEGER PRIMARY KEY to maintain compatibility.
- MariaDB/MySQL: Handles specific JSON implementation differences between the two.

Known Constraints:

Postgres Specifics: Native PG types (INET, Arrays) fallback to strings; ENUMs are rendered as CHECK constraints rather than CREATE TYPE.
Meta-Data: Collations and charsets are reset to the target server's defaults.
Flarum Focus: While optimized for Flarum's MySQL-portable schema, arbitrary complex schemas might trigger fallback paths.

Summary: There are still many flaws and I’m still working on it. I’ll be posting some news and findings soon!

ram0ng1

MySQL to Postgres testing is complete! The restoration successfully migrated everything from MySQL to PostgreSQL. 😃

To update to ramon/backup:2.0.13, run the following commands:

composer update ramon/backup
php flarum migrate
php flarum cache:clear

Origin:

Destination:

Permissions:

Destination Permissions:

Successfully finished! Data migrated from a MySQL server to a PostgreSQL server without any issues. 😃

@GreXXL

Migration Fixes Logic Summary

2. ENUM CHECK Constraints

Files: src/Database/Emitter/PostgresEmitter.php
Logic: MySQL is lenient with invalid ENUM values (coercing them to empty strings), whereas Postgres CHECK constraints are strict and fail the entire batch. The fix removes the CHECK constraint, emitting the column as plain TEXT to ensure data integrity during import.

3. Foreign Key Validation

Files: src/Database/Emitter/PostgresEmitter.php
Logic: Legacy databases often contain "orphan" rows where FK checks were disabled. Postgres prevents creating FKs if existing data violates them. The fix adds NOT VALID to the ALTER TABLE statement, allowing the constraint to be created without immediate validation of historical data.

4. Btree Index Size Limits

Files: - src/Database/Emitter/PostgresEmitter.php
- src/Database/Emitter/SqlEmitter.php
- src/Database/Emitter/AbstractEmitter.php
- src/Database/DatabaseDumper.php
Logic: Postgres btree indexes have a strict limit of ₂₇₀₄ bytes per row. Large text or blob columns from MySQL that exceed this limit cause migration failure. The logic now detects these columns and skips index creation for them to preserve the actual data, issuing a warning to the admin.

5. Postgres Sequence Resync

Files: src/Job/ImportJob.php
Logic: After bulk-loading data with explicit IDs, Postgres internal sequences (SERIAL/IDENTITY) are not automatically updated. This causes primary key collisions on the next insert. The fix implements a post-restore sweep that detects sequences via pg_get_serial_sequence and resets them to MAX(id) + 1.

luceos

I think this is a fantastic feature. But I am curious how export and import work for larger communities, eg databases of multiple GB in size. From what I read, an admin needs to keep a tab open for the export to continue between timeouts? Have you tested this with larger databases?

ram0ng1

luceos So far, I've only tested it with sample models, but I can scale it up with several GBs of test data for a proper stress test. The only downside is that I'll only be able to get to it next week, hahaha."

ram0ng1

luceos . From what I read, an admin needs to keep a tab open for the export to continue between timeouts?

Yes! To keep the connection active.

luceos

ram0ng1 I am curious whether an implementation would be possible that kicks of the generation of such a backup (in partials) by relying on cli-side processes like the cronjob (scheduled task) or queue. The queue also has a time limit though. Because relying on a client connection, which can timeout for a disastrous amount of reasons, seems very unreliable?

The cli (usually) has no memory limit and time limit constraints.

Karl

luceos the CLI is what I use on my hosting service, I can vouch that this is the way to go.

flavour1

MaxDob

@ram0ng1 are you planning to implement mariadb support?

(ramon-backup 2.0.13, MariaDB version: 10.11.14)

ram0ng1

flavour1 are you planning to implement mariadb support?

Yes!

MaxDob

ram0ng1 Good afternoon! I am looking forward to receiving support from MariaDB