From 9cf2a48de80b29fe66c8146390bd653a8b12a130 Mon Sep 17 00:00:00 2001
From: Junil Kim <logyourself@gmail.com>
Date: Sun, 26 Apr 2026 14:43:36 +0900
Subject: [PATCH 1/4] feat: add DB menu for runtime database switching

Add a "DB" sidebar menu that lets users switch the active database
without restarting the server. Supports file-based (directory + filename)
and in-memory modes. The server reconfigures the live connection pool
and the UI reloads the schema automatically after applying.
---
 package-lock.json                       |  29 ++-
 src/components/DBView/DBConfigModal.vue | 299 ++++++++++++++++++++++++
 src/components/MainLayout.vue           |  23 ++
 src/server/API.js                       |   2 +
 src/server/DBConfig.js                  |  23 ++
 src/server/utils/Database.js            |  35 +++
 6 files changed, 408 insertions(+), 3 deletions(-)
 create mode 100644 src/components/DBView/DBConfigModal.vue
 create mode 100644 src/server/DBConfig.js

diff --git a/package-lock.json b/package-lock.json
index f9ac74d..3fb06e2 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -453,6 +453,7 @@
       "integrity": "sha512-e7jT4DxYvIDLk1ZHmU/m/mB19rex9sv0c2ftBtjSBv+kVM/902eh0fINUzD7UwLLNR+jU585GxUJ8/EBfAM5fw==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "@babel/code-frame": "^7.27.1",
         "@babel/generator": "^7.28.5",
@@ -3066,6 +3067,7 @@
       "resolved": "https://registry.npmjs.org/@popperjs/core/-/core-2.11.8.tgz",
       "integrity": "sha512-P1st0aksCrn9sGZhp8GMYwBnQsbvAWsZAX44oXNNvLHGqAOcoVxmjZiohstwQ7SqKnbR47akdNi+uleWD8+g6A==",
       "license": "MIT",
+      "peer": true,
       "funding": {
         "type": "opencollective",
         "url": "https://opencollective.com/popperjs"
@@ -3937,6 +3939,7 @@
       "integrity": "sha512-yTX7GVyM19tEbd+y5/gA6MkVKA6K61nVYHYAivD61Hx6odVFmQsaC3/R3cWAHM1P5oVKCevBbumPljbT+tFG2w==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "@babel/helper-compilation-targets": "^7.12.16",
         "@soda/friendly-errors-webpack-plugin": "^1.8.0",
@@ -4563,6 +4566,7 @@
       "resolved": "https://registry.npmjs.org/acorn/-/acorn-8.16.0.tgz",
       "integrity": "sha512-UVJyE9MttOsBQIDKw1skb9nAwQuR5wuGD3+82K6JgJlm/Y+KI92oNsMNGZCYdDsVtRHSak0pcV5Dno5+4jh9sw==",
       "license": "MIT",
+      "peer": true,
       "bin": {
         "acorn": "bin/acorn"
       },
@@ -4656,6 +4660,7 @@
       "integrity": "sha512-IWrosm/yrn43eiKqkfkHis7QioDleaXQHdDVPKg0FSwwd/DuvyX79TZnFOnYpB7dcsFAMmtFztZuXPDvSePkFw==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "fast-deep-equal": "^3.1.1",
         "fast-json-stable-stringify": "^2.0.0",
@@ -4790,6 +4795,7 @@
       "integrity": "sha512-VBcZNDmdKkiMdj1ZNVXuPBxD9dRcxMdxuSWEjYVWYlZEWmY+01sPCN7QalK8ZOQdgbPdVwx5EIY49uiqbYFAnQ==",
       "deprecated": "This package is deprecated and will no longer be updated. Please use the new antlr-ng package instead: https://github.com/mike-lischke/antlr-ng",
       "license": "BSD-3-Clause",
+      "peer": true,
       "bin": {
         "antlr4ng": "index.js"
       }
@@ -5339,6 +5345,7 @@
         }
       ],
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "baseline-browser-mapping": "^2.10.12",
         "caniuse-lite": "^1.0.30001782",
@@ -6236,6 +6243,7 @@
       "integrity": "sha512-PlXPeEWMXMZ7sPYOHqmDyCJzcfNrUr3fGNKtezX14ykXOEIvyK81d+qydx89KY5O71FKMPaQ2vBfBFI5NHR63A==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "fast-deep-equal": "^3.1.3",
         "fast-uri": "^3.0.1",
@@ -6438,6 +6446,7 @@
       "integrity": "sha512-CTJ+AEQJjq5NzLga5pE39qdiSV56F8ywCIsqNIRF0r7BDgWsN25aazToqAFg7ZrtA/U016xudB3ffgweORxX7g==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "icss-utils": "^5.1.0",
         "postcss": "^8.4.33",
@@ -6526,6 +6535,7 @@
       "integrity": "sha512-PlXPeEWMXMZ7sPYOHqmDyCJzcfNrUr3fGNKtezX14ykXOEIvyK81d+qydx89KY5O71FKMPaQ2vBfBFI5NHR63A==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "fast-deep-equal": "^3.1.3",
         "fast-uri": "^3.0.1",
@@ -7708,6 +7718,7 @@
       "deprecated": "This version is no longer supported. Please see https://eslint.org/version-support for other options.",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "@eslint-community/eslint-utils": "^4.2.0",
         "@eslint-community/regexpp": "^4.6.1",
@@ -7855,6 +7866,7 @@
       "integrity": "sha512-PlXPeEWMXMZ7sPYOHqmDyCJzcfNrUr3fGNKtezX14ykXOEIvyK81d+qydx89KY5O71FKMPaQ2vBfBFI5NHR63A==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "fast-deep-equal": "^3.1.3",
         "fast-uri": "^3.0.1",
@@ -10699,6 +10711,7 @@
       "integrity": "sha512-PlXPeEWMXMZ7sPYOHqmDyCJzcfNrUr3fGNKtezX14ykXOEIvyK81d+qydx89KY5O71FKMPaQ2vBfBFI5NHR63A==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "fast-deep-equal": "^3.1.3",
         "fast-uri": "^3.0.1",
@@ -11010,7 +11023,8 @@
       "version": "0.41.0",
       "resolved": "https://registry.npmjs.org/monaco-editor/-/monaco-editor-0.41.0.tgz",
       "integrity": "sha512-1o4olnZJsiLmv5pwLEAmzHTE/5geLKQ07BrGxlF4Ri/AXAc2yyDGZwHjiTqD8D/ROKUZmwMA28A+yEowLNOEcA==",
-      "license": "MIT"
+      "license": "MIT",
+      "peer": true
     },
     "node_modules/monaco-editor-webpack-plugin": {
       "version": "7.1.1",
@@ -12347,6 +12361,7 @@
         }
       ],
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "nanoid": "^3.3.11",
         "picocolors": "^1.1.1",
@@ -15364,6 +15379,7 @@
       "resolved": "https://registry.npmjs.org/ajv/-/ajv-8.18.0.tgz",
       "integrity": "sha512-PlXPeEWMXMZ7sPYOHqmDyCJzcfNrUr3fGNKtezX14ykXOEIvyK81d+qydx89KY5O71FKMPaQ2vBfBFI5NHR63A==",
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "fast-deep-equal": "^3.1.3",
         "fast-uri": "^3.0.1",
@@ -15587,6 +15603,7 @@
       "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-4.0.4.tgz",
       "integrity": "sha512-QP88BAKvMam/3NxH6vj2o21R6MjxZUAd6nlwAS/pnGvN9IVLocLHxGYIzFhg6fUQ+5th6P4dv4eW9jX3DSIj7A==",
       "license": "MIT",
+      "peer": true,
       "engines": {
         "node": ">=12"
       },
@@ -15772,6 +15789,7 @@
       "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==",
       "devOptional": true,
       "license": "Apache-2.0",
+      "peer": true,
       "bin": {
         "tsc": "bin/tsc",
         "tsserver": "bin/tsserver"
@@ -16007,6 +16025,7 @@
       "resolved": "https://registry.npmjs.org/vue/-/vue-3.5.24.tgz",
       "integrity": "sha512-uTHDOpVQTMjcGgrqFPSb8iO2m1DUvo+WbGqoXQz8Y1CeBYQ0FXf2z1gLRaBtHjlRz7zZUBHxjVB5VTLzYkvftg==",
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "@vue/compiler-dom": "3.5.24",
         "@vue/compiler-sfc": "3.5.24",
@@ -16212,6 +16231,7 @@
       "resolved": "https://registry.npmjs.org/webpack/-/webpack-5.106.1.tgz",
       "integrity": "sha512-EW8af29ak8Oaf4T8k8YsajjrDBDYgnKZ5er6ljWFJsXABfTNowQfvHLftwcepVgdz+IoLSdEAbBiM9DFXoll9w==",
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "@types/eslint-scope": "^3.7.7",
         "@types/estree": "^1.0.8",
@@ -16359,6 +16379,7 @@
       "integrity": "sha512-PlXPeEWMXMZ7sPYOHqmDyCJzcfNrUr3fGNKtezX14ykXOEIvyK81d+qydx89KY5O71FKMPaQ2vBfBFI5NHR63A==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "fast-deep-equal": "^3.1.3",
         "fast-uri": "^3.0.1",
@@ -16476,6 +16497,7 @@
       "integrity": "sha512-PlXPeEWMXMZ7sPYOHqmDyCJzcfNrUr3fGNKtezX14ykXOEIvyK81d+qydx89KY5O71FKMPaQ2vBfBFI5NHR63A==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "fast-deep-equal": "^3.1.3",
         "fast-uri": "^3.0.1",
@@ -16557,6 +16579,7 @@
       "resolved": "https://registry.npmjs.org/webpack-sources/-/webpack-sources-3.3.4.tgz",
       "integrity": "sha512-7tP1PdV4vF+lYPnkMR0jMY5/la2ub5Fc/8VQrrU+lXkiM6C4TjVfGw7iKfyhnTQOsD+6Q/iKw0eFciziRgD58Q==",
       "license": "MIT",
+      "peer": true,
       "engines": {
         "node": ">=10.13.0"
       }
@@ -16573,6 +16596,7 @@
       "resolved": "https://registry.npmjs.org/ajv/-/ajv-8.18.0.tgz",
       "integrity": "sha512-PlXPeEWMXMZ7sPYOHqmDyCJzcfNrUr3fGNKtezX14ykXOEIvyK81d+qydx89KY5O71FKMPaQ2vBfBFI5NHR63A==",
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "fast-deep-equal": "^3.1.3",
         "fast-uri": "^3.0.1",
@@ -16754,7 +16778,6 @@
       "resolved": "https://registry.npmjs.org/workerize-loader/-/workerize-loader-2.0.2.tgz",
       "integrity": "sha512-HoZ6XY4sHWxA2w0WpzgBwUiR3dv1oo7bS+oCwIpb6n54MclQ/7KXdXsVIChTCygyuHtVuGBO1+i3HzTt699UJQ==",
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "loader-utils": "^2.0.0"
       },
@@ -16767,7 +16790,6 @@
       "resolved": "https://registry.npmjs.org/loader-utils/-/loader-utils-2.0.4.tgz",
       "integrity": "sha512-xXqpXoINfFhgua9xiqD8fPFHgkoq1mmmpE92WlDbm9rNRd/EbRb+Gqf908T2DMfuHjjJlksiK2RbHVOdD/MqSw==",
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "big.js": "^5.2.2",
         "emojis-list": "^3.0.0",
@@ -16824,6 +16846,7 @@
       "integrity": "sha512-PEIGCY5tSlUt50cqyMXfCzX+oOPqN0vuGqWzbcJ2xvnkzkq46oOpz7dQaTDBdfICb4N14+GARUDw2XV2N4tvzg==",
       "devOptional": true,
       "license": "MIT",
+      "peer": true,
       "engines": {
         "node": ">=10.0.0"
       },
diff --git a/src/components/DBView/DBConfigModal.vue b/src/components/DBView/DBConfigModal.vue
new file mode 100644
index 0000000..48eb45a
--- /dev/null
+++ b/src/components/DBView/DBConfigModal.vue
@@ -0,0 +1,299 @@
+<template>
+  <div
+    ref="modal"
+    class="modal"
+    tabindex="-1"
+  >
+    <div class="modal-dialog modal-lg">
+      <div class="modal-content bg-transparent border-0">
+        <div class="db-modal-body">
+          <h2>Database</h2>
+          <hr>
+
+          <div
+            v-if="currentConfig"
+            class="db-current"
+          >
+            <span class="db-label">Current</span>
+            <code class="db-path">{{ currentConfig.isInMemory ? 'In-memory' : currentConfig.dbPath }}</code>
+          </div>
+
+          <div class="db-options">
+            <label class="db-option-card">
+              <input
+                v-model="mode"
+                type="radio"
+                value="file"
+              >
+              <span>
+                <i class="fa-solid fa-hard-drive" />&nbsp; File-based
+              </span>
+            </label>
+            <label class="db-option-card">
+              <input
+                v-model="mode"
+                type="radio"
+                value="memory"
+              >
+              <span>
+                <i class="fa-solid fa-memory" />&nbsp; In-memory
+              </span>
+            </label>
+          </div>
+
+          <div
+            v-if="mode === 'file'"
+            class="db-fields"
+          >
+            <div class="db-field-row">
+              <label>Directory</label>
+              <input
+                v-model="dbDir"
+                type="text"
+                class="form-control db-input"
+                placeholder="/path/to/database/directory"
+              >
+            </div>
+            <div class="db-field-row">
+              <label>File name</label>
+              <input
+                v-model="dbFile"
+                type="text"
+                class="form-control db-input"
+                placeholder="database.kz"
+              >
+            </div>
+          </div>
+
+          <div
+            v-if="mode === 'memory'"
+            class="db-info-text"
+          >
+            <i class="fa-solid fa-circle-info" />&nbsp;
+            Data will not be persisted. All changes are lost when the server restarts.
+          </div>
+
+          <div
+            v-if="errorMessage"
+            class="db-error"
+          >
+            <i class="fa-solid fa-triangle-exclamation" />&nbsp; {{ errorMessage }}
+          </div>
+        </div>
+
+        <div class="modal-footer db-modal-footer d-flex justify-content-end">
+          <button
+            type="button"
+            class="btn btn-outline-secondary rounded-pill px-4 py-2"
+            @click="hideModal()"
+          >
+            Cancel
+          </button>
+          <button
+            type="button"
+            class="btn-apply rounded-pill"
+            :disabled="isApplying"
+            @click="apply()"
+          >
+            <span
+              v-if="isApplying"
+              class="spinner-border spinner-border-sm me-1"
+              role="status"
+            />
+            {{ isApplying ? 'Applying…' : 'Apply' }}
+          </button>
+        </div>
+      </div>
+    </div>
+  </div>
+</template>
+
+<script lang="js">
+import { Modal } from 'bootstrap';
+import Axios from "@/utils/AxiosWrapper";
+
+export default {
+  name: "DBConfigModal",
+  emits: ["reload-schema"],
+  data: () => ({
+    modal: null,
+    currentConfig: null,
+    mode: "file",
+    dbDir: "",
+    dbFile: "",
+    isApplying: false,
+    errorMessage: "",
+  }),
+  mounted() {
+    this.modal = new Modal(this.$refs.modal);
+    this.$refs.modal.addEventListener("hidden.bs.modal", this.onHide);
+  },
+  beforeUnmount() {
+    this.$refs.modal.removeEventListener("hidden.bs.modal", this.onHide);
+    this.modal.dispose();
+  },
+  methods: {
+    async showModal() {
+      this.errorMessage = "";
+      try {
+        const res = await Axios.get("/api/db");
+        this.currentConfig = res.data;
+        this.mode = res.data.isInMemory ? "memory" : "file";
+        this.dbDir = res.data.dbDir || "";
+        this.dbFile = res.data.dbFile || "";
+      } catch (err) {
+        this.currentConfig = null;
+      }
+      this.modal.show();
+    },
+    hideModal() {
+      this.modal.hide();
+    },
+    onHide() {
+      this.errorMessage = "";
+      this.isApplying = false;
+    },
+    async apply() {
+      this.errorMessage = "";
+      this.isApplying = true;
+      try {
+        const payload = this.mode === "memory"
+          ? { inMemory: true }
+          : { dbDir: this.dbDir, dbFile: this.dbFile || "database.kz", inMemory: false };
+        await Axios.post("/api/db", payload);
+        this.$emit("reload-schema");
+        this.hideModal();
+      } catch (err) {
+        this.errorMessage = err.response?.data?.error || err.message || "Failed to apply configuration.";
+      } finally {
+        this.isApplying = false;
+      }
+    },
+  },
+};
+</script>
+
+<style lang="scss" scoped>
+.db-modal-body {
+  border-radius: 1rem 1rem 0 0;
+  background-color: var(--bs-body-bg-secondary);
+  border: 1px solid var(--bs-body-inactive);
+  padding: 2rem;
+
+  h2 {
+    font-weight: 500;
+    font-size: 1.5rem;
+  }
+
+  hr {
+    height: 1px;
+    margin: 1rem 0;
+    background-color: var(--bs-body-inactive);
+    border: none;
+  }
+}
+
+.db-current {
+  display: flex;
+  align-items: center;
+  gap: 0.75rem;
+  background-color: var(--bs-body-bg);
+  border-radius: 0.5rem;
+  padding: 0.6rem 1rem;
+  margin-bottom: 1.5rem;
+  font-size: 0.875rem;
+}
+
+.db-label {
+  color: var(--bs-body-inactive);
+  white-space: nowrap;
+}
+
+.db-path {
+  color: var(--bs-body-text);
+  word-break: break-all;
+}
+
+.db-options {
+  display: flex;
+  gap: 1rem;
+  margin-bottom: 1.5rem;
+}
+
+.db-option-card {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  background-color: var(--bs-body-bg);
+  border: 1px solid var(--bs-body-inactive);
+  border-radius: 0.5rem;
+  padding: 0.6rem 1.2rem;
+  cursor: pointer;
+  font-size: 0.875rem;
+
+  input[type="radio"] {
+    accent-color: var(--bs-body-bg-accent);
+  }
+}
+
+.db-fields {
+  display: flex;
+  flex-direction: column;
+  gap: 0.75rem;
+}
+
+.db-field-row {
+  display: flex;
+  align-items: center;
+  gap: 1rem;
+
+  label {
+    min-width: 90px;
+    font-size: 0.875rem;
+    font-weight: 300;
+    color: var(--bs-body-text);
+  }
+}
+
+.db-input {
+  background-color: var(--bs-body-bg);
+  border: 1px solid var(--bs-body-inactive);
+  color: var(--bs-body-text);
+  font-size: 0.875rem;
+  border-radius: 0.5rem;
+}
+
+.db-info-text {
+  font-size: 0.875rem;
+  color: var(--bs-body-inactive);
+  padding: 0.5rem 0;
+}
+
+.db-error {
+  margin-top: 1rem;
+  font-size: 0.875rem;
+  color: #dc3545;
+}
+
+.db-modal-footer {
+  background-color: var(--bs-body-bg-secondary);
+  border: 1px solid var(--bs-body-inactive);
+  border-top: none;
+  border-radius: 0 0 1rem 1rem;
+  display: flex;
+  gap: 0.75rem;
+}
+
+.btn-apply {
+  background-color: var(--bs-body-bg-accent);
+  color: white;
+  padding: 0.5rem 1.5rem;
+  border: 0;
+  border-radius: 9999px;
+
+  &:disabled {
+    opacity: 0.6;
+    cursor: not-allowed;
+  }
+}
+</style>
diff --git a/src/components/MainLayout.vue b/src/components/MainLayout.vue
index 77963c3..ad991da 100644
--- a/src/components/MainLayout.vue
+++ b/src/components/MainLayout.vue
@@ -57,6 +57,19 @@
             <hr>
           </li>
 
+          <li
+            v-if="!modeStore.isWasm"
+            class="nav-item"
+          >
+            <a
+              aria-hidden="true"
+              href="#db"
+              @click.prevent="showDBModal()"
+            >
+              <i class="fa-solid fa-database" />
+              <span class="hide-on-collapse">DB</span>
+            </a>
+          </li>
           <li :class="['nav-item', { active: showShell }]">
             <a
               aria-hidden="true"
@@ -183,6 +196,11 @@
       </div>
     </div>
 
+    <DBConfigModal
+      ref="dbConfigModal"
+      @reload-schema="reloadSchema"
+    />
+
     <div
       ref="modal"
       class="modal"
@@ -265,6 +283,7 @@ import ShellMainView from "./ShellView/ShellMainView.vue";
 import SettingsMainView from "./SettingsView/SettingsMainView.vue"
 import DatasetMainView from "./DatasetView/DatasetMainView.vue"
 import ImporterMainView from "./ImporterView/ImporterMainView.vue";
+import DBConfigModal from "./DBView/DBConfigModal.vue";
 import Axios from "@/utils/AxiosWrapper";
 import { useSettingsStore } from "../store/SettingsStore";
 import { useModeStore } from "../store/ModeStore";
@@ -282,6 +301,7 @@ export default {
     SettingsMainView,
     DatasetMainView,
     ImporterMainView,
+    DBConfigModal,
   },
   data: () => ({
     accessModeModal: null,
@@ -514,6 +534,9 @@ export default {
         this.$refs.settings.showModal();
       });
     },
+    showDBModal() {
+      this.$refs.dbConfigModal.showModal();
+    },
     toggleSidebar() {
       this.isSidebarCollapsed = !this.isSidebarCollapsed;
       window.dispatchEvent(new Event('resize'));
diff --git a/src/server/API.js b/src/server/API.js
index 44ef7d2..6d441bf 100644
--- a/src/server/API.js
+++ b/src/server/API.js
@@ -20,11 +20,13 @@ if (!isWasmMode) {
     const importApi = require("./Import");
     const gpt = require("./Gpt");
 
+    const dbConfig = require("./DBConfig");
     router.use("/schema", schema);
     router.use("/cypher", cypher);
     router.use("/session", session);
     router.use("/", state);
     router.use("/gpt", gpt);
+    router.use("/db", dbConfig);
     if (currentMode === MODES.READ_WRITE) {
         router.use("/reset", reset);
         router.use("/import", importApi);
diff --git a/src/server/DBConfig.js b/src/server/DBConfig.js
new file mode 100644
index 0000000..7955139
--- /dev/null
+++ b/src/server/DBConfig.js
@@ -0,0 +1,23 @@
+const express = require("express");
+const router = express.Router();
+const database = require("./utils/Database");
+
+router.get("/", (_, res) => {
+  try {
+    res.send(database.getCurrentConfig());
+  } catch (err) {
+    res.status(500).send({ error: err.message });
+  }
+});
+
+router.post("/", async (req, res) => {
+  try {
+    const { dbDir, dbFile, inMemory } = req.body;
+    await database.reconfigure({ dbDir, dbFile, inMemory });
+    res.send(database.getCurrentConfig());
+  } catch (err) {
+    res.status(400).send({ error: err.message });
+  }
+});
+
+module.exports = router;
diff --git a/src/server/utils/Database.js b/src/server/utils/Database.js
index bd6c3c4..7ef1b2d 100644
--- a/src/server/utils/Database.js
+++ b/src/server/utils/Database.js
@@ -185,6 +185,41 @@ class Database {
       });
   }
 
+  getCurrentConfig() {
+    const isInMemory = this.dbPath === ":memory:";
+    return {
+      dbPath: this.dbPath,
+      isInMemory,
+      dbDir: isInMemory ? "" : path.dirname(this.dbPath),
+      dbFile: isInMemory ? "" : path.basename(this.dbPath),
+    };
+  }
+
+  async reconfigure({ dbDir, dbFile, inMemory }) {
+    const isAllConnectionsReleased = this.connectionPool.every(
+      (conn) => conn.useCount === 0
+    );
+    if (!isAllConnectionsReleased) {
+      throw new Error("Please make sure no queries are running before reconfiguring.");
+    }
+    const oldConnectionPool = this.connectionPool;
+    const oldDb = this.db;
+    this.connectionPool = [];
+    this.db = null;
+    await Promise.all(oldConnectionPool.map((conn) => conn.connection.close()));
+    oldDb.close();
+    if (inMemory) {
+      this.dbPath = ":memory:";
+    } else {
+      if (!dbDir) {
+        throw new Error("dbDir is required for file-based mode.");
+      }
+      const fileName = dbFile || "database.kz";
+      this.dbPath = path.resolve(path.join(dbDir, fileName));
+    }
+    this.init();
+  }
+
   async getSchema() {
     const conn = this.getConnection();
     try {

From 1084ca0e5a92bfb348f8185048696a3e140f11d3 Mon Sep 17 00:00:00 2001
From: Junil Kim <logyourself@gmail.com>
Date: Sun, 26 Apr 2026 14:51:12 +0900
Subject: [PATCH 2/4] feat: add SSH remote database support in DB menu

Add a "Remote (SSH)" option to the DB configuration modal. The server
mounts the remote directory via sshfs into a local temp path and opens
the database from there, so the connection is live (read-write, no
manual sync needed). Supports password auth (requires sshpass) and
private key file auth. The active SSH config (minus password) is
returned by GET /api/db and pre-populates the modal on re-open.
Switching away from SSH mode automatically unmounts the filesystem.
---
 src/components/DBView/DBConfigModal.vue | 244 ++++++++++++++++++++++--
 src/server/DBConfig.js                  |  25 ++-
 src/server/utils/SSHManager.js          | 133 +++++++++++++
 3 files changed, 384 insertions(+), 18 deletions(-)
 create mode 100644 src/server/utils/SSHManager.js

diff --git a/src/components/DBView/DBConfigModal.vue b/src/components/DBView/DBConfigModal.vue
index 48eb45a..1de5832 100644
--- a/src/components/DBView/DBConfigModal.vue
+++ b/src/components/DBView/DBConfigModal.vue
@@ -10,14 +10,16 @@
           <h2>Database</h2>
           <hr>
 
+          <!-- Current connection summary -->
           <div
             v-if="currentConfig"
             class="db-current"
           >
             <span class="db-label">Current</span>
-            <code class="db-path">{{ currentConfig.isInMemory ? 'In-memory' : currentConfig.dbPath }}</code>
+            <code class="db-path">{{ currentSummary }}</code>
           </div>
 
+          <!-- Mode selection -->
           <div class="db-options">
             <label class="db-option-card">
               <input
@@ -25,9 +27,7 @@
                 type="radio"
                 value="file"
               >
-              <span>
-                <i class="fa-solid fa-hard-drive" />&nbsp; File-based
-              </span>
+              <span><i class="fa-solid fa-hard-drive" />&nbsp; File-based</span>
             </label>
             <label class="db-option-card">
               <input
@@ -35,12 +35,19 @@
                 type="radio"
                 value="memory"
               >
-              <span>
-                <i class="fa-solid fa-memory" />&nbsp; In-memory
-              </span>
+              <span><i class="fa-solid fa-memory" />&nbsp; In-memory</span>
+            </label>
+            <label class="db-option-card">
+              <input
+                v-model="mode"
+                type="radio"
+                value="ssh"
+              >
+              <span><i class="fa-solid fa-server" />&nbsp; Remote (SSH)</span>
             </label>
           </div>
 
+          <!-- File-based fields -->
           <div
             v-if="mode === 'file'"
             class="db-fields"
@@ -65,14 +72,131 @@
             </div>
           </div>
 
+          <!-- In-memory info -->
           <div
-            v-if="mode === 'memory'"
+            v-else-if="mode === 'memory'"
             class="db-info-text"
           >
             <i class="fa-solid fa-circle-info" />&nbsp;
             Data will not be persisted. All changes are lost when the server restarts.
           </div>
 
+          <!-- SSH fields -->
+          <div
+            v-else-if="mode === 'ssh'"
+            class="db-fields"
+          >
+            <div class="db-ssh-section-label">
+              Connection
+            </div>
+            <div class="db-field-row">
+              <label>Host</label>
+              <input
+                v-model="ssh.host"
+                type="text"
+                class="form-control db-input"
+                placeholder="192.168.1.100 or hostname"
+              >
+            </div>
+            <div class="db-field-row">
+              <label>Port</label>
+              <input
+                v-model.number="ssh.port"
+                type="number"
+                class="form-control db-input db-input--short"
+                placeholder="22"
+                min="1"
+                max="65535"
+              >
+            </div>
+            <div class="db-field-row">
+              <label>User</label>
+              <input
+                v-model="ssh.user"
+                type="text"
+                class="form-control db-input"
+                placeholder="username"
+              >
+            </div>
+
+            <div class="db-ssh-section-label db-ssh-section-label--mt">
+              Authentication
+            </div>
+            <div class="db-field-row">
+              <label>Auth type</label>
+              <div class="db-auth-options">
+                <label class="db-auth-option">
+                  <input
+                    v-model="ssh.authType"
+                    type="radio"
+                    value="password"
+                  >
+                  Password
+                </label>
+                <label class="db-auth-option">
+                  <input
+                    v-model="ssh.authType"
+                    type="radio"
+                    value="key"
+                  >
+                  Private key file
+                </label>
+              </div>
+            </div>
+            <div
+              v-if="ssh.authType === 'password'"
+              class="db-field-row"
+            >
+              <label>Password</label>
+              <input
+                v-model="ssh.password"
+                type="password"
+                class="form-control db-input"
+                placeholder="SSH password"
+                autocomplete="current-password"
+              >
+            </div>
+            <div
+              v-else
+              class="db-field-row"
+            >
+              <label>Key file</label>
+              <input
+                v-model="ssh.privateKeyPath"
+                type="text"
+                class="form-control db-input"
+                placeholder="/home/user/.ssh/id_rsa"
+              >
+            </div>
+
+            <div class="db-ssh-section-label db-ssh-section-label--mt">
+              Remote database
+            </div>
+            <div class="db-field-row">
+              <label>Directory</label>
+              <input
+                v-model="ssh.remoteDir"
+                type="text"
+                class="form-control db-input"
+                placeholder="/path/to/database/directory"
+              >
+            </div>
+            <div class="db-field-row">
+              <label>File name</label>
+              <input
+                v-model="ssh.remoteFile"
+                type="text"
+                class="form-control db-input"
+                placeholder="database.kz"
+              >
+            </div>
+            <div class="db-info-text db-info-text--mt">
+              <i class="fa-solid fa-circle-info" />&nbsp;
+              Requires <code>sshfs</code> on the server.
+              Password auth additionally requires <code>sshpass</code>.
+            </div>
+          </div>
+
           <div
             v-if="errorMessage"
             class="db-error"
@@ -112,6 +236,17 @@
 import { Modal } from 'bootstrap';
 import Axios from "@/utils/AxiosWrapper";
 
+const defaultSSH = () => ({
+  host: "",
+  port: 22,
+  user: "",
+  authType: "password",
+  password: "",
+  privateKeyPath: "",
+  remoteDir: "",
+  remoteFile: "",
+});
+
 export default {
   name: "DBConfigModal",
   emits: ["reload-schema"],
@@ -121,9 +256,21 @@ export default {
     mode: "file",
     dbDir: "",
     dbFile: "",
+    ssh: defaultSSH(),
     isApplying: false,
     errorMessage: "",
   }),
+  computed: {
+    currentSummary() {
+      if (!this.currentConfig) return "";
+      const { mode, ssh, isInMemory, dbPath } = this.currentConfig;
+      if (mode === "ssh" && ssh) {
+        return `${ssh.user}@${ssh.host}:${ssh.remoteDir}`;
+      }
+      if (isInMemory) return "In-memory";
+      return dbPath;
+    },
+  },
   mounted() {
     this.modal = new Modal(this.$refs.modal);
     this.$refs.modal.addEventListener("hidden.bs.modal", this.onHide);
@@ -138,10 +285,15 @@ export default {
       try {
         const res = await Axios.get("/api/db");
         this.currentConfig = res.data;
-        this.mode = res.data.isInMemory ? "memory" : "file";
+        this.mode = res.data.mode || (res.data.isInMemory ? "memory" : "file");
         this.dbDir = res.data.dbDir || "";
         this.dbFile = res.data.dbFile || "";
-      } catch (err) {
+        // Pre-populate SSH fields (password is never returned from server)
+        const s = res.data.ssh;
+        this.ssh = s
+          ? { ...defaultSSH(), host: s.host, port: s.port, user: s.user, authType: s.authType, remoteDir: s.remoteDir, privateKeyPath: s.privateKeyPath || "" }
+          : defaultSSH();
+      } catch {
         this.currentConfig = null;
       }
       this.modal.show();
@@ -153,14 +305,33 @@ export default {
       this.errorMessage = "";
       this.isApplying = false;
     },
+    buildPayload() {
+      if (this.mode === "memory") {
+        return { mode: "memory" };
+      }
+      if (this.mode === "ssh") {
+        const s = this.ssh;
+        const sshPayload = {
+          host: s.host,
+          port: s.port || 22,
+          user: s.user,
+          remoteDir: s.remoteDir,
+          remoteFile: s.remoteFile || "database.kz",
+        };
+        if (s.authType === "password") {
+          sshPayload.password = s.password;
+        } else {
+          sshPayload.privateKeyPath = s.privateKeyPath;
+        }
+        return { mode: "ssh", ssh: sshPayload };
+      }
+      return { mode: "file", dbDir: this.dbDir, dbFile: this.dbFile || "database.kz" };
+    },
     async apply() {
       this.errorMessage = "";
       this.isApplying = true;
       try {
-        const payload = this.mode === "memory"
-          ? { inMemory: true }
-          : { dbDir: this.dbDir, dbFile: this.dbFile || "database.kz", inMemory: false };
-        await Axios.post("/api/db", payload);
+        await Axios.post("/api/db", this.buildPayload());
         this.$emit("reload-schema");
         this.hideModal();
       } catch (err) {
@@ -218,6 +389,7 @@ export default {
   display: flex;
   gap: 1rem;
   margin-bottom: 1.5rem;
+  flex-wrap: wrap;
 }
 
 .db-option-card {
@@ -242,6 +414,19 @@ export default {
   gap: 0.75rem;
 }
 
+.db-ssh-section-label {
+  font-size: 0.75rem;
+  font-weight: 500;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  color: var(--bs-body-inactive);
+  padding-top: 0.25rem;
+
+  &--mt {
+    margin-top: 0.5rem;
+  }
+}
+
 .db-field-row {
   display: flex;
   align-items: center;
@@ -261,12 +446,43 @@ export default {
   color: var(--bs-body-text);
   font-size: 0.875rem;
   border-radius: 0.5rem;
+
+  &--short {
+    max-width: 100px;
+  }
+}
+
+.db-auth-options {
+  display: flex;
+  gap: 1.5rem;
+}
+
+.db-auth-option {
+  display: flex;
+  align-items: center;
+  gap: 0.4rem;
+  font-size: 0.875rem;
+  font-weight: 300;
+  cursor: pointer;
+
+  input[type="radio"] {
+    accent-color: var(--bs-body-bg-accent);
+  }
 }
 
 .db-info-text {
   font-size: 0.875rem;
   color: var(--bs-body-inactive);
   padding: 0.5rem 0;
+
+  &--mt {
+    margin-top: 0.25rem;
+  }
+
+  code {
+    font-size: 0.8rem;
+    color: var(--bs-body-text);
+  }
 }
 
 .db-error {
diff --git a/src/server/DBConfig.js b/src/server/DBConfig.js
index 7955139..07bbe56 100644
--- a/src/server/DBConfig.js
+++ b/src/server/DBConfig.js
@@ -1,10 +1,18 @@
 const express = require("express");
 const router = express.Router();
 const database = require("./utils/Database");
+const sshManager = require("./utils/SSHManager");
+
+function buildResponse() {
+  const dbConfig = database.getCurrentConfig();
+  const sshConfig = sshManager.getConfig();
+  const mode = sshConfig ? "ssh" : (dbConfig.isInMemory ? "memory" : "file");
+  return { ...dbConfig, mode, ssh: sshConfig };
+}
 
 router.get("/", (_, res) => {
   try {
-    res.send(database.getCurrentConfig());
+    res.send(buildResponse());
   } catch (err) {
     res.status(500).send({ error: err.message });
   }
@@ -12,9 +20,18 @@ router.get("/", (_, res) => {
 
 router.post("/", async (req, res) => {
   try {
-    const { dbDir, dbFile, inMemory } = req.body;
-    await database.reconfigure({ dbDir, dbFile, inMemory });
-    res.send(database.getCurrentConfig());
+    const { mode, dbDir, dbFile, ssh } = req.body;
+
+    if (mode === "ssh") {
+      const { host, port = 22, user, password, privateKeyPath, remoteDir, remoteFile } = ssh;
+      const mountPoint = sshManager.mount({ host, port, user, password, privateKeyPath, remoteDir });
+      await database.reconfigure({ dbDir: mountPoint, dbFile: remoteFile || "database.kz", inMemory: false });
+    } else {
+      sshManager.unmountAll();
+      await database.reconfigure({ dbDir, dbFile, inMemory: mode === "memory" });
+    }
+
+    res.send(buildResponse());
   } catch (err) {
     res.status(400).send({ error: err.message });
   }
diff --git a/src/server/utils/SSHManager.js b/src/server/utils/SSHManager.js
new file mode 100644
index 0000000..ec8eb6c
--- /dev/null
+++ b/src/server/utils/SSHManager.js
@@ -0,0 +1,133 @@
+const { execSync } = require("child_process");
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+const logger = require("./Logger");
+
+class SSHManager {
+  constructor() {
+    this.activeMountPoint = null;
+    this.activeConfig = null; // stored without password
+
+    const cleanup = () => {
+      this.unmountAll();
+      process.exit();
+    };
+    process.on("exit", () => this.unmountAll());
+    process.on("SIGINT", cleanup);
+    process.on("SIGTERM", cleanup);
+  }
+
+  isActive() {
+    return this.activeMountPoint !== null;
+  }
+
+  getConfig() {
+    return this.activeConfig ? { ...this.activeConfig } : null;
+  }
+
+  getMountPoint() {
+    return this.activeMountPoint;
+  }
+
+  _hasCmd(cmd) {
+    try {
+      execSync(`which ${cmd}`, { stdio: "pipe" });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  mount({ host, port = 22, user, password, privateKeyPath, remoteDir }) {
+    if (!this._hasCmd("sshfs")) {
+      throw new Error(
+        "sshfs is not installed. Please install sshfs to use remote SSH databases."
+      );
+    }
+
+    // Unmount any existing mount first
+    if (this.activeMountPoint) {
+      this._doUnmount(this.activeMountPoint);
+    }
+
+    const mountPoint = fs.mkdtempSync(path.join(os.tmpdir(), "lbug-ssh-"));
+
+    const sshOpts = [
+      `port=${port}`,
+      "StrictHostKeyChecking=no",
+      "UserKnownHostsFile=/dev/null",
+      "reconnect",
+    ];
+
+    let cmd;
+    let passFile = null;
+
+    if (password) {
+      if (!this._hasCmd("sshpass")) {
+        try { fs.rmdirSync(mountPoint); } catch {}
+        throw new Error(
+          "sshpass is not installed. Install sshpass for password-based auth, or use a private key file instead."
+        );
+      }
+      passFile = path.join(os.tmpdir(), `lbug-pass-${Date.now()}`);
+      fs.writeFileSync(passFile, password, { mode: 0o600 });
+      cmd = `sshpass -f ${passFile} sshfs -o ${sshOpts.join(",")} ${user}@${host}:${remoteDir} ${mountPoint}`;
+    } else if (privateKeyPath) {
+      sshOpts.push(`IdentityFile=${privateKeyPath}`);
+      cmd = `sshfs -o ${sshOpts.join(",")} ${user}@${host}:${remoteDir} ${mountPoint}`;
+    } else {
+      try { fs.rmdirSync(mountPoint); } catch {}
+      throw new Error("Either password or privateKeyPath is required.");
+    }
+
+    try {
+      execSync(cmd, { stdio: "pipe" });
+    } catch (err) {
+      try { fs.rmdirSync(mountPoint); } catch {}
+      const stderr = err.stderr?.toString().trim() || err.message;
+      throw new Error(`SSHFS mount failed: ${stderr}`);
+    } finally {
+      if (passFile) try { fs.unlinkSync(passFile); } catch {}
+    }
+
+    this.activeMountPoint = mountPoint;
+    this.activeConfig = {
+      host,
+      port: Number(port),
+      user,
+      remoteDir,
+      authType: password ? "password" : "key",
+      privateKeyPath: password ? undefined : privateKeyPath,
+    };
+
+    logger.info(`SSH mounted: ${user}@${host}:${remoteDir} → ${mountPoint}`);
+    return mountPoint;
+  }
+
+  _doUnmount(mountPoint) {
+    try {
+      try {
+        execSync(`fusermount -u "${mountPoint}"`, { stdio: "pipe" });
+      } catch {
+        execSync(`umount "${mountPoint}"`, { stdio: "pipe" });
+      }
+    } catch (err) {
+      logger.warn(`Unmount warning for ${mountPoint}: ${err.message}`);
+    }
+    try { fs.rmdirSync(mountPoint); } catch {}
+    if (this.activeMountPoint === mountPoint) {
+      this.activeMountPoint = null;
+      this.activeConfig = null;
+    }
+    logger.info(`SSH unmounted: ${mountPoint}`);
+  }
+
+  unmountAll() {
+    if (this.activeMountPoint) {
+      this._doUnmount(this.activeMountPoint);
+    }
+  }
+}
+
+module.exports = new SSHManager();

From 4db0109829a401a5caed45b22e575a6d772db4cb Mon Sep 17 00:00:00 2001
From: Junil Kim <logyourself@gmail.com>
Date: Sun, 26 Apr 2026 15:12:02 +0900
Subject: [PATCH 3/4] docs: document runtime DB switching and SSH remote mode
 requirements

---
 README.md | 37 +++++++++++++++++++++++++++++++++++++
 1 file changed, 37 insertions(+)

diff --git a/README.md b/README.md
index 98c12d9..d85faf6 100644
--- a/README.md
+++ b/README.md
@@ -151,6 +151,43 @@ podman run -p 8000:8000 \
 
 Please refer to the official Podman docs for [mounting external volumes](https://docs.podman.io/en/latest/markdown/podman-run.1.html#mounting-external-volumes) and [user namespace mode](https://https://docs.podman.io/en/latest/markdown/podman-run.1.html#userns-mode) for more information.
 
+## Switching databases at runtime
+
+The **DB** menu in the sidebar lets you switch the active database without restarting the server. Three modes are supported:
+
+- **File-based** — open a database file on the local filesystem
+- **In-memory** — temporary database; all data is lost on restart
+- **Remote (SSH)** — mount a database from a remote machine over SSH
+
+### Remote (SSH) mode
+
+SSH mode uses `sshfs` to mount the remote directory on the machine running Ladybug Explorer and opens the database from the mount point directly. Changes are written through to the remote machine in real time.
+
+**Requirements on the machine running Ladybug Explorer:**
+
+| Dependency | Required when | How to install |
+|---|---|---|
+| `sshfs` | Always for SSH mode | `sudo apt install sshfs` or `sudo dnf install fuse-sshfs` |
+| `/dev/fuse` | Always for SSH mode | Kernel FUSE module — present by default on most Linux systems |
+| `sshpass` | Password authentication only | `sudo apt install sshpass` or `sudo dnf install sshpass` |
+
+Private key authentication does not require `sshpass`.
+
+**Requirements on the remote machine:**
+
+Only an SSH daemon (`sshd`) is needed. No additional software is required.
+
+**When running via Docker**, grant the container access to FUSE:
+
+```bash
+docker run -p 8000:8000 \
+           --cap-add SYS_ADMIN \
+           --device /dev/fuse \
+           --rm lbugdb/explorer:latest
+```
+
+`sshfs` and (if using password auth) `sshpass` must also be present inside the container image.
+
 ## Documentation
 
 For more information regarding launching and using Ladybug Explorer, please refer to the [documentation](https://docs.ladybugdb.com/visualization/lbug-explorer/).

From 075ccf9ad1981cda943b5bcc9488add0a0adbfa5 Mon Sep 17 00:00:00 2001
From: Junil Kim <logyourself@gmail.com>
Date: Sun, 26 Apr 2026 15:37:49 +0900
Subject: [PATCH 4/4] docs: add macOS macFUSE requirements for SSH remote mode

---
 README.md | 18 +++++++++++++++---
 1 file changed, 15 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index d85faf6..2c249e1 100644
--- a/README.md
+++ b/README.md
@@ -165,13 +165,25 @@ SSH mode uses `sshfs` to mount the remote directory on the machine running Ladyb
 
 **Requirements on the machine running Ladybug Explorer:**
 
+*Linux*
+
 | Dependency | Required when | How to install |
 |---|---|---|
 | `sshfs` | Always for SSH mode | `sudo apt install sshfs` or `sudo dnf install fuse-sshfs` |
-| `/dev/fuse` | Always for SSH mode | Kernel FUSE module — present by default on most Linux systems |
-| `sshpass` | Password authentication only | `sudo apt install sshpass` or `sudo dnf install sshpass` |
+| `/dev/fuse` | Always for SSH mode | Kernel FUSE module — present by default on most distributions |
+| `sshpass` | Password auth only | `sudo apt install sshpass` or `sudo dnf install sshpass` |
+
+*macOS*
+
+macOS does not include FUSE support by default. Install [macFUSE](https://osxfuse.github.io/) first, then allow its kernel extension in **System Settings → Privacy & Security** (a reboot may be required). On Apple Silicon, disabling SIP may additionally be needed — see the [macFUSE FAQ](https://github.com/osxfuse/osxfuse/wiki/FAQ).
+
+```bash
+brew install --cask macfuse
+brew install gromgit/fuse/sshfs-mac          # sshfs
+brew install hudochenkov/sshpass/sshpass     # only needed for password auth
+```
 
-Private key authentication does not require `sshpass`.
+Private key authentication does not require `sshpass` on any platform.
 
 **Requirements on the remote machine:**