From eda34adef20291d61aee6ec03d11793875e84f42 Mon Sep 17 00:00:00 2001 From: Olivia Lee Date: Sun, 1 Dec 2024 17:53:25 -0800 Subject: [PATCH] add conduit migration section to docs Most of the database compatibility info came from Charles' notes in #17. --- book/SUMMARY.md | 1 + book/migration.md | 69 +++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 70 insertions(+) create mode 100644 book/migration.md diff --git a/book/SUMMARY.md b/book/SUMMARY.md index 478d6135..289236ad 100644 --- a/book/SUMMARY.md +++ b/book/SUMMARY.md @@ -2,5 +2,6 @@ * [Introduction](./introduction.md) * [Code of conduct](./code-of-conduct.md) +* [Migration to/from conduit](./migration.md) * [Contributing](./contributing.md) * [Changelog](./changelog.md) diff --git a/book/migration.md b/book/migration.md new file mode 100644 index 00000000..e1651531 --- /dev/null +++ b/book/migration.md @@ -0,0 +1,69 @@ +# Migration to/from conduit + +Before migrating a conduit instance to grapevine, make sure to read through +all of the breaking changes listed in [the changelog](./changelog.md). + +In order to migrate an existing conduit instance to/from grapevine, the +grapevine config must include `conduit_compat = true`. This parameter cannot +currently be modified after creating the database for the first time, so make +sure to set it when creating a fresh grapevine instance that you may want to +migrate to a different implementation in the future. + +## Config + +Grapevine includes several breaking changes to the config schema. We don't +currently have docs on how to migrate an existing config. All breaking config +changes are mentioned in [the changelog](./changelog.md), so the best current +option is to read through those. Feel free to ask for config migration help in +[#grapevine:computer.surgery][room] if something is unclear. + +We plan to add [a config migration tool][config-migration-issue] to support +automatically migrating existing configs to the new schema. + +[room]: https://matrix.to/#/#grapevine:computer.surgery +[config-migration-issue]: https://gitlab.computer.surgery/matrix/grapevine/-/issues/38 + +## Database + +Grapevine is currently compatible with the Conduit 0.7.0 database format. It is +still possible to migrate to or from some newer conduit versions, but it may +require manual intervention or break some functionality. + +We plan to add [a migration tool][db-compatibility-mr] to support cleanly +migrating to or from conduit versions we are not internally compatible with. + +| Is migrating from | to | workable? | +|-|-|-| +| Conduit <=0.8.0 | Grapevine | Yes | +| Conduit 0.9.0 | Grapevine | [Yes, with caveats](#conduit-090-to-grapevine) | +| Grapevine | Conduit 0.7.0 | Yes | +| Grapevine | Conduit 0.8.0 | [Yes, with caveats](#grapevine-to-conduit-080-or-090) | +| Grapevine | Conduit 0.9.0 | [Yes, with caveats](#grapevine-to-conduit-080-or-090) | + +[db-compatibility-mr]: https://gitlab.computer.surgery/matrix/grapevine/-/merge_requests/85 + +### Conduit 0.9.0 to Grapevine + +Conduit 0.9.0 includes [a database migration][conduit-db-16-migration] that +modifies data that Grapevine doesn't read. Grapevine does not currently +recognize the new db version, and will fail to start against a conduit 0.9.0 +database. Grapevine can start and run without issues if the version recorded in +the db is rolled back from 16 to 13. It is possible to do this by editing the +db manually, or by modifying grapevine to change the version. [This +patch][conduit-db-16-patch] is an example of the latter approach. + +[conduit-db-16-migration]: https://gitlab.com/famedly/conduit/-/blob/f8d7ef04e664580e882bac852877b68e7bd3ab1e/src/database/mod.rs#L945 +[conduit-db-16-patch]: https://gitlab.computer.surgery/matrix/grapevine/-/commit/fdaa30f0d670c6f04f4e6be5d193f9146d179d95 + +### Grapevine to Conduit 0.8.0 or 0.9.0 + +Conduit 0.8.0 added [a new database table][alias_userid-commit] to track which +users created each room alias. Grapevine does not write to this table, so it is +not possible to delete aliases created in grapevine through the normal +client-server API after migrating to conduit 0.8.0. It is possible to delete +aliases with the `remove-alias` admin command. Not that this issue also applies +to migrations from conduit 0.7.0 to conduit 0.8.0. + +There are no additional known issues when migrating to conduit 0.9.0. + +[alias_userid-commit]: https://gitlab.com/famedly/conduit/-/commit/144d548ef739324ca97db12e8cada60ca3e43e09