Database layout compatibility between editions

Your question

New database layout: the key layout was redesigned and the database schema version is now tied to the edition (AGPL-only or AGPL/SEL).

  1. Why?
  2. What should I do if I decide to switch from OSS to the official binary or vice versa?

A data store created by one build can’t be opened by the other. I couldn’t find a documented tool for converting between them, and the reason for the change isn’t documented either.

1. Why

The changelog says the key layout was redesigned and that the schema version is now tied to the edition (AGPL-only or AGPL/SEL). It doesn’t say why. The source shows how it works:

  • DATABASE_SCHEMA_VERSION is 7 (the v1.0 base) in builds compiled with the enterprise feature, which is the AGPL/SEL build.
  • In builds without that feature (AGPL-only), the same base is OR’d with an “OSS flag” in the top bit.
  • At startup, verify_schema_version compares the stored value with the one the binary expects. If only the flag differs, startup fails with The data store was created by the Stalwart <other> edition and cannot be opened by this edition.

2. Switching between a self-built OSS binary and the official binary

I found no documented procedure or conversion tool for this, and the startup check refuses to open the store. Some points:

  • Moving from the official binary to an AGPL-only build, or back, means moving the data into a new, empty store. I can’t point you to a supported way to do that.
  • Don’t edit the schema version key by hand. The key layout is tied to the edition, and I found nothing saying that’s safe.
  • The Enterprise docs say both editions share one data format when you use the official binary. Installing or cancelling a license key switches between Community and Enterprise features without a migration. The restriction applies to the AGPL-only build compared with the AGPL/SEL build, not to Community compared with Enterprise.
  • If you want the official binary, I’d choose the edition before loading real data, and take a backup first.

Whether a supported conversion path exists is something a staff member would need to confirm.

Docs: Enterprise edition | Stalwart

This is an automated reply from the Stalwart Help Bot. Other community members may follow up if this answer is incomplete or wrong.

“Edition” there means the build, not the license. The official binaries and Docker images are compiled with the enterprise feature, which brings in the SEL-licensed code; a build without that feature is pure AGPL-3.0. The SEL code isn’t only extra logic, it also adds fields and object types to the stored data, for example the tenant a domain or certificate belongs to. Records written by one build therefore don’t decode the same way in the other, so 1.0 records which build created the store, and a mismatched binary stops at startup with The data store was created by the Stalwart AGPL3-only edition and cannot be opened by this edition (or the other way round) before it can misread anything.

Community and Enterprise are both the official binary, the only difference being whether a license key is installed, so going from one to the other needs nothing (Enterprise edition). The restriction applies only between a self-compiled build without enterprise and the official binary. 1.0 has no tool to convert a store between the two builds, so pick the build before you migrate: stalwart-migrate comes in a matching -oss version for servers built without enterprise (installation).

For me, restrictions like these might mean I don’t upgrade to 1.0 at all :thinking:

(Similarly, I still use Gitea 1.22 because I haven’t yet chosen between Gitea and Forgejo)

This is why it had to be done: Private Tests, Public Code: Protecting Stalwart from AI Clones | Stalwart

Would you consider updating the installation docs? I read the Note as meaning that a community user should use the -oss migrate tool. It seems that is not correct, and I should be using the standard ghcr.io/stalwartlabs/stalwart-migrate:1.0.1 image if I am using the Stalwart official Docker image?

Notably, I already ran prepare with the -oss image and it did not raise an error. I guess I should clear out the state folder and re-run with non oss?

Hi Zeus,

Yes, with the official Docker image you want the standard ghcr.io/stalwartlabs/stalwart-migrate image, with or without a license. The -oss build is only for people who compile Stalwart themselves without the enterprise feature. My earlier reply and the note on the installation page made it sound broader than that, and I’m rewording the note so nobody else falls into it.

prepare didn’t complain because nothing in the 0.16 data says which v1 build you’re going to run, and at that stage the target is still untouched: prepare only writes answers.toml and prepare-report.txt into the state directory. So yes, clear the state folder (or point --state at a new one) and run prepare again with the standard image. I’d take the 1.0.2 tag, which is the current release.

Had you already gone on to run, the official server would refuse that store at startup with the “created by the Stalwart AGPL3-only edition” error, and you’d need a fresh target as well.