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

move conduit migration to installing section

Browse source
This commit is contained in:
Charles Hall 2024-12-11 17:15:34 -08:00
parent f831dfd1f1
commit 28a4483c6e
No known key found for this signature in database
GPG key ID: 7B8E0645816E07CF
3 changed files with 71 additions and 70 deletions
Download patch file Download diff file Expand all files Collapse all files

2
book/SUMMARY.md
View file

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

70
book/installing/migrating-conduit.md Normal file
View file

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

69
book/migration.md
View file

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