Migration Framework

If you'd like to move your data in either direction between any database engine (currently 3) supported by Socialstack, there is a built in migration mechanism at /v1/migration/migrate. This mechanism is best used for sidegrades rather than up/downgrading.

The following example assumes MySQL to MongoDB.

Configuration

You first need to have installed Api/DatabaseMySQL and Api/DatabaseMongoDB in to your project. In your appsettings.json, you then connect to both:

"ConnectionStrings": {
  "DefaultConnection": "server=localhost;port=3306;SslMode=none;AllowPublicKeyRetrieval=true;database=X;user=Y;password=Z"
},
"MongoConnectionStrings": {
  "IsPrimary": true,
  "DefaultConnection": "mongodb://localhost:27017/X?ssl=false"
}

Mark the target database engine as IsPrimary: true. Start it up and you should see "MySQL is installed and configured but not mounting as it is not the primary DBE" appear in the console.

From here, login as the admin account as normal (using details from the primary database, Mongo in this case). Then, load the migrate URL:

/v1/migration/migrate?from=mysql&to=mongodb

The files for this are in Api/Database/Migration/ - it is recommended to look over that to understand how it works and what it will do. Importantly, it does not delete anything at any point by default, it essentially just loads objects from one database engine and creates them in the other, transferring the ID's as-is. You may want to delete any generated contents of your target database in between starting up the site and running this.

Compatibility

Due to the copy transfer mechanism, note that it does not passively upgrade or downgrade. Most things are cross-compatible through a wide range of socialstack versions, however there are two notable compatibility points:

• Any mappings from core 2024 and earlier would be skipped. This is because in core 2025 and onwards, they changed to being inline in rows/documents instead. Similarly you would also be missing

• Permalinks did not exist in core 2024 and earlier. There is a custom built routing engine inside core 2025 which made automated link preservation possible, complex multi-directory slugs as well as removing the dependency on having a reverse proxy (you can run core 2026 onwards without NGINX, redirect rules included). In a core 2024 -> 2025+ migration, the URLs on pages will implicitly be dropped. The page structure itself is the same however.

If you need any assistance with generating permalinks or migrating mappings as well please do ask! In short you can see the target format if you allow core 2025+ to startup and generate its default data, and then look at e.g. the site_page table. In there is a JSON column called Mappings which holds that data instead. For permalinks, it is site_permalink where you will see a relatively simple source URL and target locator, usually of the form "page:X" where X is an ID.