semaphoreui · fabiofilz · Aug 7, 2026 · Aug 7, 2026
diff --git a/stable/semaphore/README.md b/stable/semaphore/README.md
@@ -74,6 +74,41 @@ customCertificates:
 ```
 ```
 
+### SQLite (recommended lightweight database, replaces the deprecated BoltDB)
+
+```console
+database:
+  type: sqlite
+  path: /var/lib/semaphore/database.sqlite3
+
+  persistence:
+    enabled: true
+    size: 5G
+```
+
+### Migrating from BoltDB
+
+BoltDB is deprecated. If you're running Semaphore **v2.17 or v2.18**, you can migrate your existing data to SQLite (or MySQL/PostgreSQL) with the built-in migration command before switching `database.type`:
+
+```console
+semaphore migrate --from-boltdb /var/lib/semaphore/database.boltdb --config /etc/semaphore/config.json
+```
+
+This imports all projects, templates, inventories, repositories, keys, users, and task history into the new database without modifying the original BoltDB file. Useful flags: `--skip-task-output` (skip migrating task output logs) and `--merge-existing-users` (reuse existing users by username instead of failing on conflicts).
+
+In Kubernetes, you can trigger this automatically on first startup by setting the `SEMAPHORE_MIGRATE_FROM_BOLTDB` environment variable to the in-container path of your existing BoltDB file, via `extraEnvVariables`:
+
+```console
+database:
+  type: sqlite
+  path: /var/lib/semaphore/database.sqlite3
+
+extraEnvVariables:
+  SEMAPHORE_MIGRATE_FROM_BOLTDB: /var/lib/semaphore/database.boltdb
+```
+
+> **Note:** this migration command was removed in Semaphore v2.19. If you're already running v2.19+ without having migrated, you'll need a community tool such as [bolt2json](https://github.com/oncloudops/bolt2json) plus [semaphore-migration](https://github.com/oncloudops/semaphore-migration) to export/convert your BoltDB data manually.
+
 ### Bundled MariaDB
 
 ```console
@@ -175,14 +210,14 @@ oidc:
 | database.options | object | `{}` | Options for database connection |
 | database.password | string | `nil` | Password for database |
 | database.passwordKey | string | `"password"` | Key used within secret for password |
-| database.path | string | `"/var/lib/semaphore/database.boltdb"` | Path for the boltdb |
-| database.persistence.accessModes | list | `["ReadWriteOnce"]` | Access modes used for boltdb volume |
-| database.persistence.enabled | bool | `true` | Enable persistence for boltdb |
+| database.path | string | `"/var/lib/semaphore/database.boltdb"` | Path for the database file (used by the "bolt" and "sqlite" dialects) |
+| database.persistence.accessModes | list | `["ReadWriteOnce"]` | Access modes used for the database file volume |
+| database.persistence.enabled | bool | `true` | Enable persistence for the database file (used by the "bolt" and "sqlite" dialects) |
 | database.persistence.existingClaim | string | `nil` | Name of an already existing claim |
-| database.persistence.size | string | `"5G"` | Size for boltdb volume |
-| database.persistence.storageClass | string | `nil` | Storage class used for boltdb volume |
+| database.persistence.size | string | `"5G"` | Size for the database file volume |
+| database.persistence.storageClass | string | `nil` | Storage class used for the database file volume |
 | database.port | string | `nil` | Port for database connection |
-| database.type | string | `"bolt"` | Type of database backend |
+| database.type | string | `"bolt"` | Type of database backend. One of "bolt" (deprecated), "sqlite", "mysql", "postgres" |
 | database.username | string | `"semaphore"` | Username for database |
 | database.usernameFromSecret | bool | `true` | Read username from secret |
 | database.usernameKey | string | `"username"` | Key used within secret for username |

diff --git a/stable/semaphore/README.md.gotmpl b/stable/semaphore/README.md.gotmpl
@@ -76,6 +76,41 @@ customCertificates:
 ```
 ```
 
+### SQLite (recommended lightweight database, replaces the deprecated BoltDB)
+
+```console
+database:
+  type: sqlite
+  path: /var/lib/semaphore/database.sqlite3
+
+  persistence:
+    enabled: true
+    size: 5G
+```
+
+### Migrating from BoltDB
+
+BoltDB is deprecated. If you're running Semaphore **v2.17 or v2.18**, you can migrate your existing data to SQLite (or MySQL/PostgreSQL) with the built-in migration command before switching `database.type`:
+
+```console
+semaphore migrate --from-boltdb /var/lib/semaphore/database.boltdb --config /etc/semaphore/config.json
+```
+
+This imports all projects, templates, inventories, repositories, keys, users, and task history into the new database without modifying the original BoltDB file. Useful flags: `--skip-task-output` (skip migrating task output logs) and `--merge-existing-users` (reuse existing users by username instead of failing on conflicts).
+
+In Kubernetes, you can trigger this automatically on first startup by setting the `SEMAPHORE_MIGRATE_FROM_BOLTDB` environment variable to the in-container path of your existing BoltDB file, via `extraEnvVariables`:
+
+```console
+database:
+  type: sqlite
+  path: /var/lib/semaphore/database.sqlite3
+
+extraEnvVariables:
+  SEMAPHORE_MIGRATE_FROM_BOLTDB: /var/lib/semaphore/database.boltdb
+```
+
+> **Note:** this migration command was removed in Semaphore v2.19. If you're already running v2.19+ without having migrated, you'll need a community tool such as [bolt2json](https://github.com/oncloudops/bolt2json) plus [semaphore-migration](https://github.com/oncloudops/semaphore-migration) to export/convert your BoltDB data manually.
+
 ### Bundled MariaDB
 
 ```console

diff --git a/stable/semaphore/templates/deployment.yaml b/stable/semaphore/templates/deployment.yaml
@@ -32,7 +32,7 @@ spec:
         {{- if and (not .Values.admin.existingSecret) (.Values.admin.create) }}
         checksum/secret-admin: {{ (include (print $.Template.BasePath "/secret-admin.yaml") . | fromYaml).data | toYaml | sha256sum }}
         {{- end }}
-        {{- if and (not .Values.database.existingSecret) (ne .Values.database.type "bolt") }}
+        {{- if and (not .Values.database.existingSecret) (ne .Values.database.type "bolt") (ne .Values.database.type "sqlite") }}
         checksum/secret-database: {{ (include (print $.Template.BasePath "/secret-database.yaml") . | fromYaml).data | toYaml | sha256sum }}
         {{- end }}
         {{- if and (not .Values.email.existingSecret) (.Values.email.alert) }}
@@ -174,7 +174,7 @@ spec:
               value: {{ .Values.general.useRemoteRunner | quote }}
             - name: SEMAPHORE_DB_DIALECT
               value: {{ .Values.database.type | quote }}
-            {{- if eq .Values.database.type "bolt" }}
+            {{- if or (eq .Values.database.type "bolt") (eq .Values.database.type "sqlite") }}
             - name: SEMAPHORE_DB_HOST
               value: {{ .Values.database.path | quote }}
             {{- else }}
@@ -342,8 +342,8 @@ spec:
             {{- end }}
             - name: workdir
               mountPath: {{ .Values.general.tmpPath }}
-            {{- if eq .Values.database.type "bolt" }}
-            - name: boltdb
+            {{- if or (eq .Values.database.type "bolt") (eq .Values.database.type "sqlite") }}
+            - name: dbfile
               mountPath: {{ .Values.database.path | dir }}
             {{- end }}
             {{- if .Values.general.additionalPythonPackages }}
@@ -391,7 +391,7 @@ spec:
               value: {{ .Values.general.useRemoteRunner | quote }}
             - name: SEMAPHORE_DB_DIALECT
               value: {{ .Values.database.type | quote }}
-            {{- if eq .Values.database.type "bolt" }}
+            {{- if or (eq .Values.database.type "bolt") (eq .Values.database.type "sqlite") }}
             - name: SEMAPHORE_DB_HOST
               value: {{ .Values.database.path | quote }}
             {{- else }}
@@ -576,8 +576,8 @@ spec:
             {{- end }}
             - name: workdir
               mountPath: {{ .Values.general.tmpPath }}
-            {{- if eq .Values.database.type "bolt" }}
-            - name: boltdb
+            {{- if or (eq .Values.database.type "bolt") (eq .Values.database.type "sqlite") }}
+            - name: dbfile
               mountPath: {{ .Values.database.path | dir }}
             {{- end }}
             {{- if .Values.general.additionalPythonPackages }}
@@ -632,11 +632,11 @@ spec:
           {{- else }}
           emptyDir: {}
           {{- end }}
-        {{- if eq .Values.database.type "bolt" }}
-        - name: boltdb
+        {{- if or (eq .Values.database.type "bolt") (eq .Values.database.type "sqlite") }}
+        - name: dbfile
           {{- if .Values.database.persistence.enabled }}
           persistentVolumeClaim:
-            claimName: {{ .Values.database.persistence.existingClaim | default (printf "%s-boltdb" (include "semaphoreui.fullname" .)) }}
+            claimName: {{ .Values.database.persistence.existingClaim | default (printf "%s-dbfile" (include "semaphoreui.fullname" .)) }}
           {{- else }}
           emptyDir: {}
           {{- end }}

diff --git a/stable/semaphore/templates/pvc.yaml b/stable/semaphore/templates/pvc.yaml
@@ -1,10 +1,10 @@
-{{- if and (not .Values.database.persistence.existingClaim) (.Values.database.persistence.enabled) (eq .Values.database.type "bolt") }}
+{{- if and (not .Values.database.persistence.existingClaim) (.Values.database.persistence.enabled) (or (eq .Values.database.type "bolt") (eq .Values.database.type "sqlite")) }}
 ---
 apiVersion: v1
 kind: PersistentVolumeClaim
 
 metadata:
-  name: {{ include "semaphoreui.fullname" . }}-boltdb
+  name: {{ include "semaphoreui.fullname" . }}-dbfile
   namespace: {{ .Release.Namespace }}
   labels:
     {{- include "semaphoreui.labels" . | nindent 4 }}

diff --git a/stable/semaphore/templates/secret-database.yaml b/stable/semaphore/templates/secret-database.yaml
@@ -1,4 +1,4 @@
-{{- if and (not .Values.database.existingSecret) (ne .Values.database.type "bolt") }}
+{{- if and (not .Values.database.existingSecret) (ne .Values.database.type "bolt") (ne .Values.database.type "sqlite") }}
 ---
 apiVersion: v1
 kind: Secret

diff --git a/stable/semaphore/values.schema.json b/stable/semaphore/values.schema.json
@@ -86,7 +86,7 @@
       "properties": {
         "type": {
           "type": "string",
-          "enum": ["bolt", "mysql", "postgres"],
+          "enum": ["bolt", "mysql", "postgres", "sqlite"],
           "description": "Type of database backend"
         },
         "usernameFromSecret": {

diff --git a/stable/semaphore/values.yaml b/stable/semaphore/values.yaml
@@ -203,7 +203,7 @@ general:
   additionalPythonPackages: []
 
 database:
-  # -- Type of database backend
+  # -- Type of database backend. One of "bolt" (deprecated), "sqlite", "mysql", "postgres"
   type: bolt
 
   # -- Read username from secret
@@ -236,20 +236,20 @@ database:
   # -- Options for database connection
   options: {}
 
-  # -- Path for the boltdb
+  # -- Path for the database file (used by the "bolt" and "sqlite" dialects)
   path: /var/lib/semaphore/database.boltdb
 
   persistence:
-    # -- Enable persistence for boltdb
+    # -- Enable persistence for the database file (used by the "bolt" and "sqlite" dialects)
     enabled: true
 
-    # -- Size for boltdb volume
+    # -- Size for the database file volume
     size: 5G
 
-    # -- Storage class used for boltdb volume
+    # -- Storage class used for the database file volume
     storageClass:
 
-    # -- Access modes used for boltdb volume
+    # -- Access modes used for the database file volume
     accessModes:
       - ReadWriteOnce