From 4711fcf8de4eaec9c4e0390d3dd73c38bfad8d6b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Przemys=C5=82aw=20Wojtasik?= Date: Fri, 27 Aug 2021 12:12:40 +0200 Subject: [PATCH] Update migration guide with multi-tenancy changes --- doc/migrations/4.2.0_4.3.0.md | 215 ---------------------------------- doc/migrations/4.2.0_5.0.0.md | 59 ++++++++++ 2 files changed, 59 insertions(+), 215 deletions(-) delete mode 100644 doc/migrations/4.2.0_4.3.0.md create mode 100644 doc/migrations/4.2.0_5.0.0.md diff --git a/doc/migrations/4.2.0_4.3.0.md b/doc/migrations/4.2.0_4.3.0.md deleted file mode 100644 index a7efbcb28b..0000000000 --- a/doc/migrations/4.2.0_4.3.0.md +++ /dev/null @@ -1,215 +0,0 @@ -## DB migrations - -### Inbox indexes - -Domain removal feature requires the order of fields to be changed: - -For Postgres: - -```sql --- Create a new index for the new primary key. -CREATE UNIQUE INDEX i_inbox_sur ON inbox (lserver, luser, remote_bare_jid); - --- Now enter a transaction block to replace the primary with the new one. -BEGIN; -ALTER TABLE inbox DROP CONSTRAINT inbox_pkey; -ALTER TABLE inbox ADD CONSTRAINT inbox_pkey PRIMARY KEY USING INDEX i_inbox_sur; -COMMIT; - -CREATE INDEX i_inbox_timestamp - ON inbox - USING BTREE(lserver, luser, timestamp); -DROP INDEX i_inbox; -``` - -For MySQL: - -```sql -BEGIN; -ALTER TABLE inbox DROP PRIMARY KEY; -ALTER TABLE inbox ADD PRIMARY KEY USING BTREE(lserver, luser, remote_bare_jid); -COMMIT; - -CREATE INDEX i_inbox_timestamp ON inbox(lserver, luser, timestamp); -DROP INDEX i_inbox ON inbox; -``` - -For MSSQL: - -```sql -CREATE INDEX i_inbox_su_ts ON inbox(lserver, luser, timestamp); -GO - -DROP INDEX i_inbox_ts ON inbox; -GO - -ALTER TABLE inbox DROP CONSTRAINT PK_inbox; -GO - -ALTER TABLE inbox ADD CONSTRAINT PK_inbox PRIMARY KEY CLUSTERED( - lserver ASC, luser ASC, remote_bare_jid ASC); -GO -``` - -### MUC-light indexes - -Order of fields in `i_muc_light_blocking` has changed. - -For Postgres: - -```sql -CREATE INDEX i_muc_light_blocking_su ON muc_light_blocking (lserver, luser); -DROP INDEX i_muc_light_blocking; -``` - -For MySQL: - -```sql -CREATE INDEX i_muc_light_blocking_su USING BTREE ON muc_light_blocking (lserver, luser); -DROP INDEX i_muc_light_blocking ON muc_light_blocking;; -``` - -For MSSQL: - -```sql -CREATE INDEX i_muc_light_blocking_su ON muc_light_blocking (lserver, luser); -GO - -DROP INDEX i_muc_light_blocking ON muc_light_blocking; -GO -``` - -### mod_privacy - -Server fields are added to privacy data, as well as their primary key having been expanded: - -For Postgres: - -```sql --- Create a new index for the new primary key. -CREATE UNIQUE INDEX i_privacy_default_list_su ON privacy_default_list (server, username); -CREATE UNIQUE INDEX i_privacy_list_sun ON privacy_list (server, username, name); - --- Now enter a transaction block to replace the primary with the new one. -BEGIN; -ALTER TABLE privacy_default_list ADD COLUMN server varchar(250); -ALTER TABLE privacy_default_list DROP CONSTRAINT privacy_default_list_pkey; -ALTER TABLE privacy_default_list ADD CONSTRAINT privacy_default_list_pkey PRIMARY KEY USING INDEX i_privacy_default_list_su; - -ALTER TABLE privacy_list ADD COLUMN server varchar(250) NOT NULL; -ALTER TABLE privacy_list DROP CONSTRAINT privacy_list_pkey; -ALTER TABLE privacy_list ADD CONSTRAINT privacy_list_pkey PRIMARY KEY USING INDEX i_privacy_list_sun; -COMMIT; -``` - -For MySQL: - -```sql -BEGIN; -ALTER TABLE privacy_default_list ADD COLUMN server varchar(250); -ALTER TABLE privacy_default_list DROP PRIMARY KEY; -ALTER TABLE privacy_default_list ADD PRIMARY KEY USING BTREE(server, username); - -ALTER TABLE privacy_list ADD COLUMN server varchar(250) NOT NULL; -ALTER TABLE privacy_list DROP PRIMARY KEY; -ALTER TABLE privacy_list ADD PRIMARY KEY USING BTREE(server, username, name); -COMMIT; -``` - -For MSSQL: - -```sql -ALTER TABLE privacy_default_list ADD COLUMN server varchar(250); -ALTER TABLE privacy_default_list DROP CONSTRAINT PK_privacy_default_list; -ALTER TABLE privacy_default_list ADD CONSTRAINT PK_privacy_default_list PRIMARY KEY CLUSTERED( - server ASC, username ASC); -GO - -ALTER TABLE privacy_list ADD COLUMN server varchar(250); -ALTER TABLE privacy_list DROP CONSTRAINT PK_privacy_list; -ALTER TABLE privacy_list ADD CONSTRAINT PK_privacy_list PRIMARY KEY CLUSTERED( - server ASC, username ASC, name ASC); -GO -``` - - -### mod_private - -For Postgres: - -```sql -ALTER TABLE private_storage ADD server varchar(250); - --- Assign some server to the old entries -UPDATE private_storage SET server = "localhost"; -ALTER TABLE private_storage ALTER COLUMN server SET NOT NULL; - -CREATE UNIQUE INDEX i_private_storage_sun ON private_storage USING btree (server, username, namespace); - -DROP INDEX i_private_storage_username; -DROP INDEX i_private_storage_username_namespace; - -ALTER TABLE private_storage ADD CONSTRAINT private_storage_pkey PRIMARY KEY USING INDEX i_private_storage_sun; -``` - -For MySQL: - -```sql -ALTER TABLE private_storage ADD server varchar(250); - --- Assign some server to the old entries -UPDATE private_storage SET server = "localhost"; -ALTER TABLE private_storage MODIFY COLUMN server varchar(150) NOT NULL; - -CREATE UNIQUE INDEX i_private_storage_sun ON private_storage (server, username, namespace); - -DROP INDEX i_private_storage_username ON private_storage; -DROP INDEX i_private_storage_username_namespace ON private_storage; - -ALTER TABLE private_storage ADD PRIMARY KEY USING BTREE(server, username, namespace); -``` - -For MSSQL: - -```sql -ALTER TABLE private_storage ADD server [nvarchar](150); --- Assign some server to the old entries -UPDATE private_storage SET server = 'localhost'; -ALTER TABLE private_storage ALTER COLUMN server [nvarchar](150) NOT NULL; -ALTER TABLE private_storage DROP CONSTRAINT private_storage$i_private_storage_username_namespace; -ALTER TABLE private_storage ADD CONSTRAINT PK_private_storage PRIMARY KEY CLUSTERED (server, username, namespace); -``` - -## Hook migrations - -- `filter_room_packet` hook uses a map instead of a proplist - for the event data information. -- `room_send_packet` hook has been removed. Use `filter_room_packet` instead. -- `filter_room_packet` is called for HostType (was for MucHost). -- `forget_room` is called for HostType (was for MucHost). -- `forget_room` takes an extra argument HostType. -- `filter_room_packet` takes an extra argument HostType. -- `is_muc_room_owner` is called for HostType (was for MucHost). -- `is_muc_room_owner` takes an extra argument HostType. -- `muc_room_pid` hook removed. -- `load_permanent_rooms_at_startup` option is ignored now. -- `gen_mod:get_module_opt_by_subhost` API removed. -- `update_inbox_for_muc` is called for HostType. -- `get_mam_muc_gdpr_data` is called for HostType. -- `get_mam_pm_gdpr_data` is called for HostType. -- `get_personal_data` handlers take an extra argument: `HostType` as the second parameter. -- `get_mam_pm_gdpr_data` and `get_mam_muc_gdpr_data` take `HostType` argument. - -## Metrics REST API (obsolete) - -The API is still considered obsolete so if you are using it, -please consider using [WombatOAM](https://www.erlang-solutions.com/capabilities/wombatoam/) -or metrics reporters as described in [Logging and monitoring](../operation-and-maintenance/Logging-&-monitoring.md). - -In each endpoint, `host` has been changed to `host_type`. -This is because the metrics are now collected per host type rather than host. - - -## Users cache - -MongooseIM used to feature a cache to check whether a user exists, that was unavoidably enabled, and had no eviction policy, that is, the cache could continue growing forever. Now, MIM features a module called [`mod_cache_users`](../modules/mod_cache_users) that implements a configurable cache policy, that can be enabled, disabled, and parametrised, per `host_type`. This might not be enabled by default in your configuration, so we recommend you verify your configuration and enable it if needed. diff --git a/doc/migrations/4.2.0_5.0.0.md b/doc/migrations/4.2.0_5.0.0.md new file mode 100644 index 0000000000..c06795d864 --- /dev/null +++ b/doc/migrations/4.2.0_5.0.0.md @@ -0,0 +1,59 @@ +## DB migrations + +The migrations scripts for Postgres, MySQL, MSSQL can be found in the [`priv/migrations`](../../priv/migrations/) directory. + +### Changes in XEPs: +- `mod_last` + - Table `last` - added server column, updated primary key and indexes. +- `mod_privacy` + - Table `privacy_default_list` - added server column, updated primary key and indexes. + - Table `privacy_list` - added server column, updated primary key and indexes. +- `mod_private` + - Table `private_storage` - added server column, updated primary key and indexes, removed unused columns. +- `mod_roster` + - Table `rosterusers` - added server column, updated indexes. + - Table `rostergroups` - added server column, updated indexes. + - Table `roster_version` - added server column, updated primary key and indexes. +- `mod_muc` + - Table `i_muc_light_blocking` - updated indexes. +- `mod_inbox` + - Table `inbox` - updated primary key and indexes. + +### Other changes: +- RDBMS auth - modified `users` table. +- Added `domain_settings` table. +- Added `domain_events` table. + +## Hook migrations + +- `filter_room_packet` hook uses a map instead of a proplist + for the event data information. +- `room_send_packet` hook has been removed. Use `filter_room_packet` instead. +- `filter_room_packet` is called for HostType (was for MucHost). +- `forget_room` is called for HostType (was for MucHost). +- `forget_room` takes an extra argument HostType. +- `filter_room_packet` takes an extra argument HostType. +- `is_muc_room_owner` is called for HostType (was for MucHost). +- `is_muc_room_owner` takes an extra argument HostType. +- `muc_room_pid` hook removed. +- `load_permanent_rooms_at_startup` option is ignored now. +- `gen_mod:get_module_opt_by_subhost` API removed. +- `update_inbox_for_muc` is called for HostType. +- `get_mam_muc_gdpr_data` is called for HostType. +- `get_mam_pm_gdpr_data` is called for HostType. +- `get_personal_data` handlers take an extra argument: `HostType` as the second parameter. +- `get_mam_pm_gdpr_data` and `get_mam_muc_gdpr_data` take `HostType` argument. + +## Metrics REST API (obsolete) + +The API is still considered obsolete so if you are using it, +please consider using [WombatOAM](https://www.erlang-solutions.com/capabilities/wombatoam/) +or metrics reporters as described in [Logging and monitoring](../operation-and-maintenance/Logging-&-monitoring.md). + +In each endpoint, `host` has been changed to `host_type`. +This is because the metrics are now collected per host type rather than host. + + +## Users cache + +MongooseIM used to feature a cache to check whether a user exists, that was unavoidably enabled, and had no eviction policy, that is, the cache could continue growing forever. Now, MIM features a module called [`mod_cache_users`](../modules/mod_cache_users) that implements a configurable cache policy, that can be enabled, disabled, and parametrised, per `host_type`. This might not be enabled by default in your configuration, so we recommend you verify your configuration and enable it if needed.