From 17ca05f2481350b3523588ea89a757d47f93ae95 Mon Sep 17 00:00:00 2001
From: Sean Klein <seanmarionklein@gmail.com>
Date: Mon, 7 Jul 2025 15:13:38 -0700
Subject: [PATCH] Add schema changes for quiescing

---
 nexus/db-model/src/db_metadata.rs | 10 +++++++++
 nexus/db-schema/src/schema.rs     |  2 ++
 schema/crdb/dbinit.sql            | 35 +++++++++++++++++++++++++++++--
 3 files changed, 45 insertions(+), 2 deletions(-)

diff --git a/nexus/db-model/src/db_metadata.rs b/nexus/db-model/src/db_metadata.rs
index de7e2862eb7..293addb72d0 100644
--- a/nexus/db-model/src/db_metadata.rs
+++ b/nexus/db-model/src/db_metadata.rs
@@ -18,6 +18,8 @@ pub struct DbMetadata {
     time_modified: DateTime<Utc>,
     version: SemverVersion,
     target_version: Option<SemverVersion>,
+    quiesce_started: bool,
+    quiesce_completed: bool,
 }
 
 impl DbMetadata {
@@ -32,4 +34,12 @@ impl DbMetadata {
     pub fn version(&self) -> &SemverVersion {
         &self.version
     }
+
+    pub fn quiesce_started(&self) -> bool {
+        self.quiesce_started
+    }
+
+    pub fn quiesce_completed(&self) -> bool {
+        self.quiesce_completed
+    }
 }
diff --git a/nexus/db-schema/src/schema.rs b/nexus/db-schema/src/schema.rs
index 3d8f2d2fd7f..286060185cb 100644
--- a/nexus/db-schema/src/schema.rs
+++ b/nexus/db-schema/src/schema.rs
@@ -2251,6 +2251,8 @@ table! {
         time_modified -> Timestamptz,
         version -> Text,
         target_version -> Nullable<Text>,
+        quiesce_started -> Bool,
+        quiesce_completed -> Bool,
     }
 }
 
diff --git a/schema/crdb/dbinit.sql b/schema/crdb/dbinit.sql
index 3d35ceffc11..cd1b371785c 100644
--- a/schema/crdb/dbinit.sql
+++ b/schema/crdb/dbinit.sql
@@ -5434,6 +5434,35 @@ CREATE TABLE IF NOT EXISTS omicron.public.db_metadata (
     -- (Optional) Semver representation of the DB version to which we're upgrading
     target_version STRING(64),
 
+    -- During the nexus boot process, it must check this table to understand the
+    -- state of the Schema.
+    --
+    -- There are a handful of states to consider:
+    --
+    -- - "db.version = version in binary" + "quiesce_started = true": An
+    --   upgrade is in-progress, and the underlying database should not be used.
+    --   This Nexus should coordinate with other Nexus instances at this version
+    --   (via internal DNS) to set "quiesce_completed" to true.
+    -- - "db.version = version in binary" + "quiesce_completed = true" OR
+    --   "db.version > version in binary"
+    --   This Nexus should avoid accessing the database, but has no need to coordinate
+    --   with other Nexuses.
+    -- - "db.version < version in binary":
+    --   This Nexus should upgrade to the new schema, but only once "quiesce_completed"
+    --   is set to true.
+    --   Once the upgrade is complete, "quiesce_started" and "quiesce_completed"
+    --   should both be set to false. Note that multiple Nexuses may be attempting this
+    --   schema upgrade operation concurrently.
+
+
+    -- Identifies that a schema migration has started.
+    -- Nexuses with "db.version = version in binary" should not access the database any longer.
+    quiesce_started BOOL NOT NULL,
+
+    -- Identifies that a schema migration is ready to hand-off from Old Nexus versions
+    -- to newer Nexus versions.
+    quiesce_completed BOOL NOT NULL,
+
     CHECK (singleton = true)
 );
 
@@ -6218,9 +6247,11 @@ INSERT INTO omicron.public.db_metadata (
     time_created,
     time_modified,
     version,
-    target_version
+    target_version,
+    quiesce_started,
+    quiesce_completed
 ) VALUES
-    (TRUE, NOW(), NOW(), '157.0.0', NULL)
+    (TRUE, NOW(), NOW(), '158.0.0', NULL, FALSE, FALSE)
 ON CONFLICT DO NOTHING;
 
 COMMIT;