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.

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, so the best current option is to read through those. Feel free to ask for config migration help in #grapevine:computer.surgery if something is unclear.

We plan to add a config migration tool to support automatically migrating existing configs to the new schema.

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:

/var/lib/grapevine
+ database/
| + database-file-1
| + ...
| + database-file-n
+ media/
  + media-file-1
  + ...
  + media-file-n

And here is the matching configuration:

[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:

/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 to support cleanly migrating to or from Conduit versions we are not internally compatible with.

Conduit 0.9.0 to Grapevine

Conduit 0.9.0 includes a database 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 is an example of the latter approach.

Grapevine to Conduit 0.8.0 or 0.9.0

Conduit 0.8.0 added a new database table 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.