From e1819e5bcddb09edde450a0e7c88dec2933de58d Mon Sep 17 00:00:00 2001 From: "Olivier Wilkinson (reivilibre)" Date: Fri, 10 Mar 2023 17:54:09 +0000 Subject: [PATCH 1/3] Add some comments to the schema about destinations and destination_rooms --- .../74/90COMMENTS_destinations.sql.postgres | 46 +++++++++++++++++++ 1 file changed, 46 insertions(+) create mode 100644 synapse/storage/schema/main/delta/74/90COMMENTS_destinations.sql.postgres diff --git a/synapse/storage/schema/main/delta/74/90COMMENTS_destinations.sql.postgres b/synapse/storage/schema/main/delta/74/90COMMENTS_destinations.sql.postgres new file mode 100644 index 000000000000..ffefffa53b68 --- /dev/null +++ b/synapse/storage/schema/main/delta/74/90COMMENTS_destinations.sql.postgres @@ -0,0 +1,46 @@ +/* Copyright 2023 The Matrix.org Foundation C.I.C + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + + +--- destinations +COMMENT ON TABLE destinations IS + 'Information about remote homeservers and the health of our connection to them.'; + +COMMENT ON COLUMN destinations.destination IS 'server name of remote homeserver in question'; + +COMMENT ON COLUMN destinations.last_successful_stream_ordering IS + 'Stream ordering of the most recently successfully sent PDU to this server. See `destination_rooms` for more information about catch-up.'; + +COMMENT ON COLUMN destinations.retry_last_ts IS + 'The last time we tried and failed to reach the remote server, in ms.'; + +COMMENT ON COLUMN destinations.retry_interval IS + 'How long since the last time we tried to reach the remote server before trying again, in ms.'; + +COMMENT ON COLUMN destinations.failure_ts IS + 'The first time we tried and failed to reach the remote server, in ms.'; + + + +--- destination_rooms +COMMENT ON TABLE destination_rooms IS + 'Information about transmission of PDUs in a given room to a given remote homeserver.'; + +COMMENT ON COLUMN destination_rooms.destination IS 'server name of remote homeserver in question'; + +COMMENT ON COLUMN destination_rooms.room_id IS 'room ID in question'; + +COMMENT ON COLUMN destination_rooms.stream_ordering IS + 'most recent PDU in this room that needs to be sent to this homeserver'; From f0ff9fcf514b1d7e15189b93c060cc00b754338c Mon Sep 17 00:00:00 2001 From: "Olivier Wilkinson (reivilibre)" Date: Fri, 10 Mar 2023 17:54:56 +0000 Subject: [PATCH 2/3] Newsfile Signed-off-by: Olivier Wilkinson (reivilibre) --- changelog.d/15247.misc | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelog.d/15247.misc diff --git a/changelog.d/15247.misc b/changelog.d/15247.misc new file mode 100644 index 000000000000..6e2ce1d4d8bd --- /dev/null +++ b/changelog.d/15247.misc @@ -0,0 +1 @@ +Add schema comments about the `destinations` and `destination_rooms` tables. \ No newline at end of file From 4d55672a9a8b3531fcc420b49b1332fc5f39904d Mon Sep 17 00:00:00 2001 From: "Olivier Wilkinson (reivilibre)" Date: Tue, 14 Mar 2023 16:11:25 +0000 Subject: [PATCH 3/3] Update comments --- .../74/90COMMENTS_destinations.sql.postgres | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) diff --git a/synapse/storage/schema/main/delta/74/90COMMENTS_destinations.sql.postgres b/synapse/storage/schema/main/delta/74/90COMMENTS_destinations.sql.postgres index ffefffa53b68..cc7dda1a1136 100644 --- a/synapse/storage/schema/main/delta/74/90COMMENTS_destinations.sql.postgres +++ b/synapse/storage/schema/main/delta/74/90COMMENTS_destinations.sql.postgres @@ -21,16 +21,21 @@ COMMENT ON TABLE destinations IS COMMENT ON COLUMN destinations.destination IS 'server name of remote homeserver in question'; COMMENT ON COLUMN destinations.last_successful_stream_ordering IS - 'Stream ordering of the most recently successfully sent PDU to this server. See `destination_rooms` for more information about catch-up.'; +$$Stream ordering of the most recently successfully sent PDU to this server, sent through normal send (not e.g. backfill). +In Catch-Up Mode, the original PDU persisted by us is represented here, even if we sent a later forward extremity in its stead. +See `destination_rooms` for more information about catch-up.$$; COMMENT ON COLUMN destinations.retry_last_ts IS - 'The last time we tried and failed to reach the remote server, in ms.'; +$$The last time we tried and failed to reach the remote server, in ms. +This field is reset to `0` when we succeed in connecting again.$$; COMMENT ON COLUMN destinations.retry_interval IS - 'How long since the last time we tried to reach the remote server before trying again, in ms.'; +$$How long, in milliseconds, to wait since the last time we tried to reach the remote server before trying again. +This field is reset to `0` when we succeed in connecting again.$$; COMMENT ON COLUMN destinations.failure_ts IS - 'The first time we tried and failed to reach the remote server, in ms.'; +$$The first time we tried and failed to reach the remote server, in ms. +This field is reset to `NULL` when we succeed in connecting again.$$; @@ -43,4 +48,5 @@ COMMENT ON COLUMN destination_rooms.destination IS 'server name of remote homese COMMENT ON COLUMN destination_rooms.room_id IS 'room ID in question'; COMMENT ON COLUMN destination_rooms.stream_ordering IS - 'most recent PDU in this room that needs to be sent to this homeserver'; +$$`stream_ordering` of the most recent PDU in this room that needs to be sent (by us) to this homeserver. +This can only be pointing to our own PDU because we are only responsible for sending our own PDUs.$$;