From a86789be6c69a43ab6bebd49c91457ba3682fe78 Mon Sep 17 00:00:00 2001
From: Diego <11472973+UnwishingMoon@users.noreply.github.com>
Date: Sun, 18 Jan 2026 16:44:43 +0100
Subject: [PATCH] feat: Add path to socket for external mariadb database
 (#6670)

Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
Co-authored-by: Frank Elsinga <frank@elsinga.de>
---
 server/database.js          |  6 ++++--
 server/setup-database.js    | 27 ++++++++++++++++++---------
 src/lang/en.json            |  1 +
 src/pages/SetupDatabase.vue | 15 +++++++++++++--
 4 files changed, 36 insertions(+), 13 deletions(-)

diff --git a/server/database.js b/server/database.js
index 23923679f..a2a0dd20b 100644
--- a/server/database.js
+++ b/server/database.js
@@ -165,7 +165,7 @@ class Database {
      * Read the database config
      * @throws {Error} If the config is invalid
      * @typedef {string|undefined} envString
-     * @returns {{type: "sqlite"} | {type:envString, hostname:envString, port:envString, database:envString, username:envString, password:envString}} Database config
+     * @returns {{type: "sqlite"} | {type:envString, hostname:envString, port:envString, database:envString, username:envString, password:envString, socketPath:envString}} Database config
      */
     static readDBConfig() {
         let dbConfig;
@@ -185,7 +185,7 @@ class Database {
 
     /**
      * @typedef {string|undefined} envString
-     * @param {{type: "sqlite"} | {type:envString, hostname:envString, port:envString, database:envString, username:envString, password:envString}} dbConfig the database configuration that should be written
+     * @param {{type: "sqlite"} | {type:envString, hostname:envString, port:envString, database:envString, username:envString, password:envString, socketPath:envString}} dbConfig the database configuration that should be written
      * @returns {void}
      */
     static writeDBConfig(dbConfig) {
@@ -284,6 +284,7 @@ class Database {
                 port: dbConfig.port,
                 user: dbConfig.username,
                 password: dbConfig.password,
+                socketPath: dbConfig.socketPath,
                 ...(dbConfig.ssl
                     ? {
                           ssl: {
@@ -309,6 +310,7 @@ class Database {
                     user: dbConfig.username,
                     password: dbConfig.password,
                     database: dbConfig.dbName,
+                    socketPath: dbConfig.socketPath,
                     timezone: "Z",
                     typeCast: function (field, next) {
                         if (field.type === "DATETIME") {
diff --git a/server/setup-database.js b/server/setup-database.js
index 81554c160..4f1065307 100644
--- a/server/setup-database.js
+++ b/server/setup-database.js
@@ -102,6 +102,7 @@ class SetupDatabase {
             dbConfig.dbName = process.env.UPTIME_KUMA_DB_NAME;
             dbConfig.username = getEnvOrFile("UPTIME_KUMA_DB_USERNAME");
             dbConfig.password = getEnvOrFile("UPTIME_KUMA_DB_PASSWORD");
+            dbConfig.socketPath = process.env.UPTIME_KUMA_DB_SOCKET?.trim();
             dbConfig.ssl = getEnvOrFile("UPTIME_KUMA_DB_SSL")?.toLowerCase() === "true";
             dbConfig.ca = getEnvOrFile("UPTIME_KUMA_DB_CA");
             Database.writeDBConfig(dbConfig);
@@ -160,6 +161,7 @@ class SetupDatabase {
                     runningSetup: this.runningSetup,
                     needSetup: this.needSetup,
                     isEnabledEmbeddedMariaDB: this.isEnabledEmbeddedMariaDB(),
+                    isEnabledMariaDBSocket: process.env.UPTIME_KUMA_DB_SOCKET?.trim().length > 0,
                 });
             });
 
@@ -202,16 +204,22 @@ class SetupDatabase {
 
                 // External MariaDB
                 if (dbConfig.type === "mariadb") {
-                    if (!dbConfig.hostname) {
-                        response.status(400).json("Hostname is required");
-                        this.runningSetup = false;
-                        return;
-                    }
+                    // If socketPath is provided and not empty, validate it
+                    if (process.env.UPTIME_KUMA_DB_SOCKET?.trim().length > 0) {
+                        dbConfig.socketPath = process.env.UPTIME_KUMA_DB_SOCKET.trim();
+                    } else {
+                        // socketPath not provided, hostname and port are required
+                        if (!dbConfig.hostname) {
+                            response.status(400).json("Hostname is required");
+                            this.runningSetup = false;
+                            return;
+                        }
 
-                    if (!dbConfig.port) {
-                        response.status(400).json("Port is required");
-                        this.runningSetup = false;
-                        return;
+                        if (!dbConfig.port) {
+                            response.status(400).json("Port is required");
+                            this.runningSetup = false;
+                            return;
+                        }
                     }
 
                     if (!dbConfig.dbName) {
@@ -241,6 +249,7 @@ class SetupDatabase {
                             user: dbConfig.username,
                             password: dbConfig.password,
                             database: dbConfig.dbName,
+                            socketPath: dbConfig.socketPath,
                             ...(dbConfig.ssl
                                 ? {
                                       ssl: {
diff --git a/src/lang/en.json b/src/lang/en.json
index 5bcc6b59a..1736167c8 100644
--- a/src/lang/en.json
+++ b/src/lang/en.json
@@ -1369,6 +1369,7 @@
     "None (Successful Connection)": "None (Successful Connection)",
     "expectedTlsAlertDescription": "Select the TLS alert you expect the server to return. Use {code} to verify mTLS endpoints reject connections without client certificates. See {link} for details.",
     "TLS Alert Spec": "RFC 8446",
+    "mariadbSocketPathDetectedHelptext": "Connecting to the database as specified via the {0} environment variable.",
     "Expand All Groups": "Expand All Groups",
     "Collapse All Groups": "Collapse All Groups"
 }
diff --git a/src/pages/SetupDatabase.vue b/src/pages/SetupDatabase.vue
index 47c50a6e9..264bf8288 100644
--- a/src/pages/SetupDatabase.vue
+++ b/src/pages/SetupDatabase.vue
@@ -79,7 +79,7 @@
                 </div>
 
                 <template v-if="dbConfig.type === 'mariadb'">
-                    <div class="form-floating mt-3 short">
+                    <div v-if="!isProvidedMariaDBSocket" class="form-floating mt-3 short">
                         <input
                             id="floatingInput"
                             v-model="dbConfig.hostname"
@@ -90,11 +90,19 @@
                         <label for="floatingInput">{{ $t("Hostname") }}</label>
                     </div>
 
-                    <div class="form-floating mt-3 short">
+                    <div v-if="!isProvidedMariaDBSocket" class="form-floating mt-3 short">
                         <input id="floatingInput" v-model="dbConfig.port" type="text" class="form-control" required />
                         <label for="floatingInput">{{ $t("Port") }}</label>
                     </div>
 
+                    <div v-if="isProvidedMariaDBSocket" class="mt-1 short text-start">
+                        <i18n-t keypath="mariadbSocketPathDetectedHelptext" tag="div" class="form-text">
+                            <code>UPTIME_KUMA_DB_SOCKET</code>
+                        </i18n-t>
+                    </div>
+
+                    <hr v-if="isProvidedMariaDBSocket" class="mt-3 mb-2 short" />
+
                     <div class="form-floating mt-3 short">
                         <input
                             id="floatingInput"
@@ -198,6 +206,9 @@ export default {
         disabledButton() {
             return this.dbConfig.type === undefined || this.info.runningSetup;
         },
+        isProvidedMariaDBSocket() {
+            return this.info.isEnabledMariaDBSocket;
+        },
     },
     async mounted() {
         let res = await axios.get("/setup-database-info");