backups/grapevine
1
0
Fork 0
mirror of https://gitlab.computer.surgery/matrix/grapevine.git synced 2025-12-16 15:21:24 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions

add conduit migration section to docs

Browse source 
Most of the database compatibility info came from Charles' notes
in #17.
This commit is contained in:
Olivia Lee 2024-12-01 17:53:25 -08:00
parent 54c25ceb3c
commit eda34adef2
No known key found for this signature in database
GPG key ID: 54D568A15B9CD1F9
2 changed files with 70 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

1
book/SUMMARY.md
View file

@ -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)

69
book/migration.md Normal file
View file

@ -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