diff --git a/book/SUMMARY.md b/book/SUMMARY.md index a696c9f4..136c331d 100644 --- a/book/SUMMARY.md +++ b/book/SUMMARY.md @@ -2,9 +2,9 @@ * [Introduction](./introduction.md) * [Code of conduct](./code-of-conduct.md) -* [Migration to/from Conduit](./migration.md) * [Changelog](./changelog.md) * [Installing](./installing.md) + * [Migrating to/from Conduit](./installing/migrating-conduit.md) * [Contributing](./contributing.md) * [Coordinated vulnerability disclosure](./contributing/security.md) * [Style guide](./contributing/style-guide.md) diff --git a/book/installing/migrating-conduit.md b/book/installing/migrating-conduit.md new file mode 100644 index 00000000..f847c7af --- /dev/null +++ b/book/installing/migrating-conduit.md @@ -0,0 +1,70 @@ +# Migrating 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 database schema 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 databse is rolled back from 16 to 13. It is possible to +do this by editing the database 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. Note that this issue also applies +to migrations from Conduit <0.8.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 diff --git a/book/migration.md b/book/migration.md index 6ec2f833..432f4e47 100644 --- a/book/migration.md +++ b/book/migration.md @@ -1,70 +1 @@ # 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 database schema 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 databse is rolled back from 16 to 13. It is possible to -do this by editing the database 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. Note that this issue also applies -to migrations from Conduit <0.8.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