mirror of
https://gitlab.computer.surgery/matrix/grapevine.git
synced 2025-12-16 23:31:24 +01:00
5a5608e088
The primary motivation for this change is to support databases that don't take a path, e.g. out of process databases. This configuration structure leaves the door open for other media storage mechanisms in the future, such as S3. It's also structured to avoid `#[serde(flatten)]` so that we can use `#[serde(deny_unknown_fields)]`.
118 lines
4.5 KiB
Markdown
118 lines
4.5 KiB
Markdown
# 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
|
|
|
|
## Filesystem
|
|
|
|
Grapevine requires database data and media data to live in **separate**,
|
|
**non-nested** directories, which are configurable. Here is a typical example,
|
|
starting with the filesystem structure:
|
|
|
|
```text
|
|
/var/lib/grapevine
|
|
+ database/
|
|
| + database-file-1
|
|
| + ...
|
|
| + database-file-n
|
|
+ media/
|
|
+ media-file-1
|
|
+ ...
|
|
+ media-file-n
|
|
```
|
|
|
|
And here is the matching configuration:
|
|
|
|
```toml
|
|
[database]
|
|
path = "/var/lib/grapevine/database"
|
|
|
|
[media.backend]
|
|
type = "filesystem"
|
|
path = "/var/lib/grapevine/media"
|
|
```
|
|
|
|
On the other hand, Conduit's filesystem layout looks like this:
|
|
|
|
```text
|
|
/var/lib/conduit
|
|
+ media/
|
|
| + media-file-1
|
|
| + ...
|
|
| + media-file-n
|
|
+ database-file-1
|
|
+ ...
|
|
+ database-file-n
|
|
```
|
|
|
|
Which **nests** the media directory inside the database directory. Grapevine
|
|
will reject this layout, so the filesystem layout must be changed before
|
|
starting Grapevine. It is important to migrate the filesystem layout before
|
|
starting Grapevine, because otherwise it will create a fresh database instead of
|
|
using the existing one.
|
|
|
|
## 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
|