From 18ba16aaac7fcd98e642af87d9c9e399ea715493 Mon Sep 17 00:00:00 2001 From: Heikki Linnakangas Date: Thu, 22 Apr 2021 09:25:18 +0300 Subject: [PATCH] Fix and improve comment on ZTimelineId. The comment was incorrect, claiming that ZTimelineId is a 32-byte value. It is actually 16 bytes wide. While we're at it, improve the comment, explaining what a zenith timeline is, and why it's different from PostgreSQL timelines. --- pageserver/src/lib.rs | 25 ++++++++++++++++++++++++- 1 file changed, 24 insertions(+), 1 deletion(-) diff --git a/pageserver/src/lib.rs b/pageserver/src/lib.rs index 4c344749f5..efe92c67ee 100644 --- a/pageserver/src/lib.rs +++ b/pageserver/src/lib.rs @@ -21,7 +21,30 @@ pub struct PageServerConf { pub listen_addr: SocketAddr, } -// Zenith Timeline ID is a 32-byte random ID. +/// Zenith Timeline ID is a 128-bit random ID. +/// +/// Zenith timeline IDs are different from PostgreSQL timeline +/// IDs. They serve a similar purpose though: they differentiate +/// between different "histories" of the same cluster. However, +/// PostgreSQL timeline IDs are a bit cumbersome, because they are only +/// 32-bits wide, and they must be in ascending order in any given +/// timeline history. Those limitations mean that we cannot generate a +/// new PostgreSQL timeline ID by just generating a random number. And +/// that in turn is problematic for the "pull/push" workflow, where you +/// have a local copy of a zenith repository, and you periodically sync +/// the local changes with a remote server. When you work "detached" +/// from the remote server, you cannot create a PostgreSQL timeline ID +/// that's guaranteed to be different from all existing timelines in +/// the remote server. For example, if two people are having a clone of +/// the repository on their laptops, and they both create a new branch +/// with different name. What timeline ID would they assign to their +/// branches? If they pick the same one, and later try to push the +/// branches to the same remote server, they will get mixed up. +/// +/// To avoid those issues, Zenith has its own concept of timelines that +/// is separate from PostgreSQL timelines, and doesn't have those +/// limitations. A zenith timeline is identified by a 128-bit ID, which +/// is usually printed out as a hex string. #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] pub struct ZTimelineId([u8; 16]);