opencats · anonymoususer72041 · Jun 6, 2026 · Jun 6, 2026 · Jun 6, 2026 · Jun 6, 2026
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -71,6 +71,8 @@ jobs:
           [ -n "$integrationtestdb_container" ] || { echo "integrationtestdb container ID not found"; exit 1; }
           timeout 180s bash -c "until [ \"\$(docker inspect --format '{{.State.Health.Status}}' \"${integrationtestdb_container}\" 2>/dev/null)\" = \"healthy\" ]; do sleep 3; done"
 
+          docker compose -f docker-compose-test.yml exec -T --workdir /var/www/public php php test/scripts/finalizeInstallSchemaVersion.php
+
           # 2. Pre-clean the integration database
           docker compose -f docker-compose-test.yml exec -T integrationtestdb mysql -udev -pdev -e "DROP DATABASE IF EXISTS cats_integrationtest; CREATE DATABASE cats_integrationtest;"
 

diff --git a/ajax.php b/ajax.php
@@ -41,6 +41,7 @@
 include_once(LEGACY_ROOT . '/lib/Session.php'); /* Depends: MRU, Users, DatabaseConnection. */
 include_once(LEGACY_ROOT . '/lib/AJAXInterface.php');
 include_once(LEGACY_ROOT . '/lib/CATSUtility.php');
+include_once(LEGACY_ROOT . '/lib/SchemaMigrationStatus.php');
 
 
 header('Last-Modified: ' . gmdate('D, d M Y H:i:s') . ' GMT');
@@ -117,6 +118,8 @@
     }
 }
 
+$module = '';
+
 if (strpos($_REQUEST['f'], ':') === false)
 {
     $function = preg_replace("/[^A-Za-z0-9]/", "", $_REQUEST['f']);
@@ -134,6 +137,30 @@
     $filename = sprintf('modules/%s/ajax/%s.php', $module, $function);
 }
 
+/* Fresh installer AJAX remains available. On installed systems, only the
+ * existing maintenance action may pass the pending-migration AJAX gate.
+ */
+$maintenanceAJAXAllowed =
+    $installerActive ||
+    ($module === 'install' && $function === 'maint');
+
+if (isset($_SESSION['CATS']) &&
+    $_SESSION['CATS']->isLoggedIn() &&
+    !$maintenanceAJAXAllowed &&
+    SchemaMigrationStatus::hasPendingInstallMigrations())
+{
+    header('Content-type: text/xml; charset=' . AJAX_ENCODING);
+    echo '<?xml version="1.0" encoding="', AJAX_ENCODING, '"?>', "\n";
+    echo(
+        "<data>\n" .
+        "    <errorcode>-1</errorcode>\n" .
+        "    <errormessage>Database maintenance is required.</errormessage>\n" .
+        "</data>\n"
+    );
+
+    die();
+}
+
 if (!is_readable($filename))
 {
     header('Content-type: text/xml; charset=' . AJAX_ENCODING);

diff --git a/index.php b/index.php
@@ -162,10 +162,46 @@
     }
 }
 
+$isPublicRequest =
+    (isset($careerPage) && $careerPage) ||
+    (isset($_GET['showCareerPortal']) && $_GET['showCareerPortal'] == '1') ||
+    (isset($rssPage) && $rssPage) ||
+    (isset($xmlPage) && $xmlPage);
+$isMigrationGateExcluded =
+    (isset($_GET['m']) && $_GET['m'] === 'install' &&
+        isset($_GET['a']) && $_GET['a'] === 'maint') ||
+    (isset($_GET['m']) && ($_GET['m'] === 'login' || $_GET['m'] === 'logout'));
+
+if ($_SESSION['CATS']->isLoggedIn() &&
+    !$isPublicRequest &&
+    !$isMigrationGateExcluded &&
+    SchemaMigrationStatus::hasPendingInstallMigrations())
+{
+    $template = new Template();
+    $template->assign(
+        'isAdministrator',
+        $_SESSION['CATS']->getAccessLevel(ACL::SECOBJ_ROOT) >= ACCESS_LEVEL_SA
+    );
+    $template->display('./modules/login/PendingMigrations.tpl');
+    die();
+}
+
 /* Check to see if we are supposed to display the career page. */
 if (((isset($careerPage) && $careerPage) ||
     (isset($_GET['showCareerPortal']) && $_GET['showCareerPortal'] == '1')))
 {
+    if (SchemaMigrationStatus::hasPendingInstallMigrations())
+    {
+        header('HTTP/1.1 503 Service Unavailable');
+        header('Content-Type: text/html; charset=UTF-8');
+
+        echo '<!DOCTYPE html>',
+             '<html><head><title>Career Portal Maintenance</title></head><body>',
+             '<p>The career portal is temporarily unavailable while system maintenance is in progress. Please try again later.</p>',
+             '</body></html>';
+        die();
+    }
+
     ModuleUtility::loadModule('careers');
 }
 

diff --git a/js/install.js b/js/install.js
@@ -28,6 +28,7 @@
 
 var response;
 var maxSteps;
+var maintenanceOnly = false;
 
 
 function setActiveStep(step)
@@ -119,9 +120,30 @@
 
         response = http.responseText;
 
+        if (maintenanceOnly &&
+            (http.status < 200 ||
+             http.status >= 300 ||
+             AJAX_isPHPError(response) ||
+             response.indexOf("<errorcode>-1</errorcode>") != -1 ||
+             response.indexOf("Query Error") != -1 ||
+             response.indexOf("Access denied.") != -1))
+        {
+            document.getElementById("maintenanceProgress").style.display = "none";
+            document.getElementById("maintenanceError").style.display = "";
+            document.getElementById("startMaintenance").disabled = false;
+            return;
+        }
+
         if (response.indexOf("setProgressUpdating") == -1)
- 		{	
-	        Installpage_populate("a=reindexResumes");
+        {
+            if (maintenanceOnly)
+            {
+                window.location = "index.php";
+            }
+            else
+            {
+                Installpage_populate("a=reindexResumes");
+            }
         }
         else
         {

diff --git a/lib/ModuleUtility.php b/lib/ModuleUtility.php
@@ -35,6 +35,8 @@
  *  @package    CATS
  *  @subpackage Library
  */
+include_once(LEGACY_ROOT . '/lib/SchemaMigrationStatus.php');
+
 class ModuleUtility
 {
     /* Prevent this class from being instantiated. */
@@ -441,6 +443,14 @@
      */
     private static function processModuleSchema($moduleName, $schema)
     {
+        global $maintPage;
+
+        if ($moduleName === 'install' &&
+            (!isset($maintPage) || $maintPage !== true))
+        {
+            return;
+        }
+
         if( ini_get('safe_mode') )
         {
 			//don't do anything in safe mode
@@ -501,7 +511,11 @@
 
         if ($moduleName === 'install' && ($currentVersion === NULL || $currentVersion === ''))
         {
-            /* A NULL install module version means the database came from cats_schema.sql and should not replay historical install migrations. */
+            /* This explicit installer/maintenance finalization is only for
+             * snapshot databases whose schema already matches the bundled
+             * baseline. It must not run during normal requests and is not
+             * proof that an unknown historical database state is current.
+             */
             $sql = sprintf(
                 "UPDATE
                     module_schema
@@ -514,6 +528,7 @@
             );
             $db->query($sql);
 
+            SchemaMigrationStatus::clearCache();
             return;
         }
 
@@ -532,7 +547,6 @@
             }
 
 			/* if maintPage, execute 1 query, output the next query and progress, and terminate. */
-			global $maintPage;
 			if ((isset($maintPage) && $maintPage === true))
 			{
 				if ($executedQuery == false)
@@ -586,6 +600,11 @@
             $rs = $db->query($sql);
 
             $currentVersion = $version;
+
+            if ($moduleName === 'install')
+            {
+                SchemaMigrationStatus::clearCache();
+            }
         }
     }
 }

diff --git a/lib/SchemaMigrationStatus.php b/lib/SchemaMigrationStatus.php
@@ -0,0 +1,128 @@
+<?php
+/**
+ * CATS
+ * Schema Migration Status Library
+ *
+ * @package    CATS
+ * @subpackage Library
+ */
+
+include_once(LEGACY_ROOT . '/modules/install/Schema.php');
+
+class SchemaMigrationStatus
+{
+    private static $_latestInstallSchemaVersion = NULL;
+    private static $_storedInstallSchemaVersion = NULL;
+    private static $_storedInstallSchemaVersionLoaded = false;
+    private static $_hasPendingInstallMigrations = NULL;
+
+    /* Prevent this class from being instantiated. */
+    private function __construct() {}
+    private function __clone() {}
+
+    /**
+     * Returns the latest install schema version available in the code.
+     *
+     * @return integer
+     */
+    public static function getLatestInstallSchemaVersion()
+    {
+        if (self::$_latestInstallSchemaVersion !== NULL)
+        {
+            return self::$_latestInstallSchemaVersion;
+        }
+
+        $schemaVersions = array_keys(CATSSchema::get());
+        self::$_latestInstallSchemaVersion = empty($schemaVersions) ? 0 : (int) max($schemaVersions);
+
+        return self::$_latestInstallSchemaVersion;
+    }
+
+    /**
+     * Returns the install schema version stored in the database.
+     *
+     * NULL or an empty string is not a known applied schema version. It must
+     * remain unresolved until an explicit installer or maintenance flow
+     * finalizes it; this read-only checker must not normalize it.
+     *
+     * @return mixed Integer version, NULL or empty string if unresolved,
+     *               or false if the row does not exist.
+     */
+    public static function getStoredInstallSchemaVersion()
+    {
+        if (self::$_storedInstallSchemaVersionLoaded)
+        {
+            return self::$_storedInstallSchemaVersion;
+        }
+
+        $db = DatabaseConnection::getInstance();
+
+        $sql = sprintf(
+            "SELECT
+                version AS version
+            FROM
+                module_schema
+            WHERE
+                name = %s",
+            $db->makeQueryString('install')
+        );
+        $rs = $db->getAssoc($sql);
+
+        if (empty($rs))
+        {
+            self::$_storedInstallSchemaVersion = false;
+        }
+        else
+        {
+            self::$_storedInstallSchemaVersion = $rs['version'];
+        }
+
+        self::$_storedInstallSchemaVersionLoaded = true;
+
+        return self::$_storedInstallSchemaVersion;
+    }
+
+    /**
+     * Returns whether install schema migrations are pending.
+     *
+     * @return boolean
+     */
+    public static function hasPendingInstallMigrations()
+    {
+        if (self::$_hasPendingInstallMigrations !== NULL)
+        {
+            return self::$_hasPendingInstallMigrations;
+        }
+
+        $storedVersion = self::getStoredInstallSchemaVersion();
+
+        if ($storedVersion === false ||
+            $storedVersion === NULL ||
+            $storedVersion === '')
+        {
+            /* Unknown versions require explicit install or maintenance finalization. */
+            self::$_hasPendingInstallMigrations = true;
+            return true;
+        }
+
+        self::$_hasPendingInstallMigrations =
+            (int) $storedVersion < self::getLatestInstallSchemaVersion();
+
+        return self::$_hasPendingInstallMigrations;
+    }
+
+    /**
+     * Clears cached migration status after explicit maintenance updates.
+     *
+     * @return void
+     */
+    public static function clearCache()
+    {
+        self::$_latestInstallSchemaVersion = NULL;
+        self::$_storedInstallSchemaVersion = NULL;
+        self::$_storedInstallSchemaVersionLoaded = false;
+        self::$_hasPendingInstallMigrations = NULL;
+    }
+}
+
+?>
diff --git a/modules/install/CATSUI.php b/modules/install/CATSUI.php
@@ -41,6 +41,34 @@
 
     public function handleRequest()
     {
+        if ($this->getAction() !== 'maint')
+        {
+            return;
+        }
+
+        if (!isset($_SESSION['CATS']) || !$_SESSION['CATS']->isLoggedIn())
+        {
+            CATSUtility::transferRelativeURI('m=login');
+            die();
+        }
+
+        if ($_SESSION['CATS']->getAccessLevel(ACL::SECOBJ_ROOT) < ACCESS_LEVEL_SA)
+        {
+            header('HTTP/1.1 403 Forbidden');
+            CommonErrors::fatal(COMMONERROR_PERMISSION, $this);
+        }
+
+        if (!SchemaMigrationStatus::hasPendingInstallMigrations())
+        {
+            CATSUtility::transferRelativeURI('');
+            die();
+        }
+
+        $this->_template->assign(
+            'csrfToken',
+            $_SESSION['CATS']->getCSRFToken()
+        );
+        $this->_template->display('./modules/install/Maintenance.tpl');
     }
 }