feat: show admin UI warning for SQLite on networked filesystem (#1713)

Co-authored-by: Elias Schneider <login@eliasschneider.com>
This commit is contained in:
Alessandro (Ale) Segala
2026-08-24 15:03:31 -07:00
committed by GitHub
parent d258d952b1
commit 29a6fd6c29
17 changed files with 278 additions and 91 deletions

View File

@@ -25,7 +25,7 @@ require (
github.com/google/uuid v1.6.0
github.com/italypaleale/francis v0.1.0-beta.23
github.com/italypaleale/go-kit v1.0.0
github.com/italypaleale/go-sql-utils v0.3.5
github.com/italypaleale/go-sql-utils v0.3.6
github.com/jackc/pgx/v5 v5.10.0
github.com/jinzhu/copier v0.4.0
github.com/joho/godotenv v1.5.1

View File

@@ -247,6 +247,8 @@ github.com/italypaleale/go-kit v1.0.0 h1:c+SaYHTaoZzTgbPXhSbNVdNRkNdNhE0YljBWWoP
github.com/italypaleale/go-kit v1.0.0/go.mod h1:wg4UsIbsbtDiVqUjJdo/tO9lXo0OXBuwPOpSJ+u+1jI=
github.com/italypaleale/go-sql-utils v0.3.5 h1:kkrhIo1tVJvcsjRc1kePWE9Cqdm26+Et5XZYSNmv764=
github.com/italypaleale/go-sql-utils v0.3.5/go.mod h1:STWS4qGjiGKt2tf9OdRUlf025FhKZvUA31siUOnejj0=
github.com/italypaleale/go-sql-utils v0.3.6 h1:ND14osePZFhn717qqI+nuH2blxKLTcYqWYSAG9anVDg=
github.com/italypaleale/go-sql-utils v0.3.6/go.mod h1:STWS4qGjiGKt2tf9OdRUlf025FhKZvUA31siUOnejj0=
github.com/jackc/pgerrcode v0.0.0-20250907135507-afb5586c32a6 h1:D/V0gu4zQ3cL2WKeVNVM4r2gLxGGf6McLwgXzRTo2RQ=
github.com/jackc/pgerrcode v0.0.0-20250907135507-afb5586c32a6/go.mod h1:a/s9Lp5W7n/DD0VrVoyJ00FbP2ytTPDVOivvn2bMlds=
github.com/jackc/pgpassfile v1.0.0 h1:/6Hmqy13Ss2zCq62VdNG8tM1wchn8zjSGOBJ6icpsIM=

View File

@@ -27,6 +27,10 @@ import (
sqliteutil "github.com/pocket-id/pocket-id/backend/internal/utils/sqlite"
)
// Records whether the SQLite database was found on a networked filesystem
// It's always false when using Postgres
var sqliteOnNetworkedFilesystem bool
func NewDatabase(ctx context.Context) (db *gorm.DB, pg *pgxpool.Pool, err error) {
db, pg, err = ConnectDatabase(ctx)
if err != nil {
@@ -68,6 +72,9 @@ func ConnectDatabase(ctx context.Context) (db *gorm.DB, pg *pgxpool.Pool, err er
return nil, nil, err
}
// Detect whether the database lives on a networked filesystem to show a warning in the admin UI
sqliteOnNetworkedFilesystem = connector.IsNetworked()
// We open the connection ourselves, rather than letting Gorm do it, so it goes through the instrumented driver
// It also caps in-memory databases to a single connection, which they need to see the whole data
sqliteDB, err := sqliteinstrument.Open(connector, sqlInstrumentOptions())

View File

@@ -176,7 +176,7 @@ func registerRoutes(r *gin.Engine, db *gorm.DB, svc *services, rateLimitServices
controller.NewUserGroupController(apiGroup, authMiddleware, svc.appConfigService, svc.userGroupService)
svc.apiModule.RegisterRoutes(apiGroup, authMiddleware.Add())
controller.NewCustomClaimController(apiGroup, authMiddleware, svc.customClaimService)
controller.NewVersionController(apiGroup, authMiddleware, svc.versionService)
svc.environmentModule.RegisterRoutes(apiGroup, authMiddleware.WithAdminNotRequired().Add())
svc.scimSyncModule.RegisterRoutes(apiGroup, authMiddleware.Add())
svc.userSignUpModule.RegisterRoutes(apiGroup,
authMiddleware.Add(),

View File

@@ -14,6 +14,7 @@ import (
"github.com/pocket-id/pocket-id/backend/internal/devicelogin"
"github.com/pocket-id/pocket-id/backend/internal/email"
"github.com/pocket-id/pocket-id/backend/internal/emailverification"
"github.com/pocket-id/pocket-id/backend/internal/environment"
"github.com/pocket-id/pocket-id/backend/internal/geolite"
"github.com/pocket-id/pocket-id/backend/internal/ldapsync"
"github.com/pocket-id/pocket-id/backend/internal/oidc"
@@ -37,7 +38,6 @@ type services struct {
customClaimService *service.CustomClaimService
oidcService *service.OidcService
userGroupService *service.UserGroupService
versionService *service.VersionService
fileStorage storage.FileStorage
apiKeyModule *apikey.Module
@@ -51,6 +51,7 @@ type services struct {
oneTimeAccessModule *onetimeaccess.Module
emailVerificationModule *emailverification.Module
apiModule *api.Module
environmentModule *environment.Module
actors *local.Host
}
@@ -247,7 +248,10 @@ func initServices(
return nil, fmt.Errorf("failed to create email verification module: %w", err)
}
svc.versionService = service.NewVersionService(httpClient)
svc.environmentModule = environment.New(environment.Dependencies{
HTTPClient: httpClient,
SQLiteOnNetworkedFilesystem: sqliteOnNetworkedFilesystem,
})
return svc, nil
}

View File

@@ -16,15 +16,20 @@ import (
_ "github.com/joho/godotenv/autoload"
)
type AppEnv string
type DbProvider string
type TrustProxyConfig []string
type (
AppEnv string
DbProvider string
TrustProxyConfig []string
DismissSQLiteStorageWarningConfig bool
)
const (
// TracerName should be passed to otel.Tracer, trace.SpanFromContext when creating custom spans.
TracerName = "github.com/pocket-id/pocket-id/backend/tracing"
// MeterName should be passed to otel.Meter when create custom metrics.
MeterName = "github.com/pocket-id/pocket-id/backend/metrics"
// dismissSQLiteStorageWarningPhrase is the exact phrase DISMISS_SQLITE_STORAGE_WARNING must be set to to suppress the warning (matched case-insensitive)
dismissSQLiteStorageWarningPhrase = "i accept the risks"
)
const (
@@ -99,6 +104,10 @@ type EnvConfigSchema struct {
// LogQueryArgs includes the values of SQL query parameters in traces and in the query logs printed when LogLevel is "debug"
// Note that these may can contain sensitive data
LogQueryArgs bool `env:"LOG_QUERY_ARGS"`
// This is true when DISMISS_SQLITE_STORAGE_WARNING is the exact confirmation phrase set in the constant above
// Note: this is omitted from the general list of environment variables in the docs, and documented only in the SQLite-specific section
DismissSQLiteStorageWarning DismissSQLiteStorageWarningConfig `env:"DISMISS_SQLITE_STORAGE_WARNING"`
}
var EnvConfig = defaultConfig()
@@ -422,6 +431,15 @@ func (a AppEnv) IsTest() bool {
return a == AppEnvTest
}
func (config *DismissSQLiteStorageWarningConfig) UnmarshalText(text []byte) error {
// Make lowercase, then replace all - and _ with spaces
value := strings.ToLower(strings.TrimSpace(string(text)))
value = strings.ReplaceAll(value, "_", " ")
value = strings.ReplaceAll(value, "-", " ")
*config = DismissSQLiteStorageWarningConfig(value == dismissSQLiteStorageWarningPhrase)
return nil
}
func (config *TrustProxyConfig) UnmarshalText(text []byte) error {
value := strings.TrimSpace(string(text))

View File

@@ -337,6 +337,49 @@ func TestParseEnvConfig(t *testing.T) {
assert.ErrorContains(t, err, "TLS_CERT_FILE not found")
})
t.Run("should not dismiss the SQLite storage warning by default", func(t *testing.T) {
EnvConfig = defaultConfig()
t.Setenv("DB_CONNECTION_STRING", "file:test.db")
t.Setenv("APP_URL", "http://localhost:3000")
err := parseAndValidateEnvConfig(t)
require.NoError(t, err)
assert.False(t, bool(EnvConfig.DismissSQLiteStorageWarning))
})
t.Run("should not dismiss the SQLite storage warning with an unrelated value", func(t *testing.T) {
EnvConfig = defaultConfig()
t.Setenv("DB_CONNECTION_STRING", "file:test.db")
t.Setenv("APP_URL", "http://localhost:3000")
t.Setenv("DISMISS_SQLITE_STORAGE_WARNING", "true")
err := parseAndValidateEnvConfig(t)
require.NoError(t, err)
assert.False(t, bool(EnvConfig.DismissSQLiteStorageWarning))
})
t.Run("should dismiss the SQLite storage warning with the confirmation phrase", func(t *testing.T) {
EnvConfig = defaultConfig()
t.Setenv("DB_CONNECTION_STRING", "file:test.db")
t.Setenv("APP_URL", "http://localhost:3000")
t.Setenv("DISMISS_SQLITE_STORAGE_WARNING", " I Accept The Risks ")
err := parseAndValidateEnvConfig(t)
require.NoError(t, err)
assert.True(t, bool(EnvConfig.DismissSQLiteStorageWarning))
})
t.Run("should dismiss the SQLite storage warning with the confirmation phrase with dashes", func(t *testing.T) {
EnvConfig = defaultConfig()
t.Setenv("DB_CONNECTION_STRING", "file:test.db")
t.Setenv("APP_URL", "http://localhost:3000")
t.Setenv("DISMISS_SQLITE_STORAGE_WARNING", " I-Accept_The_Risks ")
err := parseAndValidateEnvConfig(t)
require.NoError(t, err)
assert.True(t, bool(EnvConfig.DismissSQLiteStorageWarning))
})
t.Run("should fail when TLS key file does not exist", func(t *testing.T) {
EnvConfig = defaultConfig()
t.Setenv("DB_CONNECTION_STRING", "file:test.db")

View File

@@ -1,60 +0,0 @@
package controller
import (
"net/http"
"time"
"github.com/gin-gonic/gin"
"github.com/pocket-id/pocket-id/backend/internal/common"
_ "github.com/pocket-id/pocket-id/backend/internal/dto"
"github.com/pocket-id/pocket-id/backend/internal/httpserver"
"github.com/pocket-id/pocket-id/backend/internal/middleware"
"github.com/pocket-id/pocket-id/backend/internal/service"
"github.com/pocket-id/pocket-id/backend/internal/utils"
)
// NewVersionController registers version-related routes.
func NewVersionController(group *gin.RouterGroup, authMiddleware *middleware.AuthMiddleware, versionService *service.VersionService) {
vc := &VersionController{versionService: versionService}
group.GET("/version/latest", httpserver.Handle(vc.getLatestVersionHandler))
group.GET("/version/current", authMiddleware.WithAdminNotRequired().Add(), httpserver.Handle(vc.getCurrentVersionHandler))
}
type VersionController struct {
versionService *service.VersionService
}
// getLatestVersionHandler godoc
// @Summary Get latest available version of Pocket ID
// @Tags Version
// @Produce json
// @Success 200 {object} map[string]string "Latest version information"
// @Failure default {object} dto.ErrorDto "Error"
// @Router /api/version/latest [get]
func (vc *VersionController) getLatestVersionHandler(c *gin.Context) error {
tag, err := vc.versionService.GetLatestVersion(c.Request.Context())
if err != nil {
return err
}
utils.SetCacheControlHeader(c, 5*time.Minute, 15*time.Minute)
c.JSON(http.StatusOK, gin.H{
"latestVersion": tag,
})
return nil
}
// getCurrentVersionHandler godoc
// @Summary Get current deployed version of Pocket ID
// @Tags Version
// @Produce json
// @Success 200 {object} map[string]string "Current version information"
// @Failure default {object} dto.ErrorDto "Error"
// @Router /api/version/current [get]
func (vc *VersionController) getCurrentVersionHandler(c *gin.Context) error {
c.JSON(http.StatusOK, gin.H{
"currentVersion": common.Version,
})
return nil
}

View File

@@ -0,0 +1,70 @@
package environment
import (
"net/http"
"time"
"github.com/gin-gonic/gin"
"github.com/pocket-id/pocket-id/backend/internal/common"
_ "github.com/pocket-id/pocket-id/backend/internal/dto"
"github.com/pocket-id/pocket-id/backend/internal/utils"
)
type handler struct {
service *Service
}
func newHandler(service *Service) *handler {
return &handler{service: service}
}
// getLatestVersion godoc
// @Summary Get latest available version of Pocket ID
// @Tags Version
// @Produce json
// @Success 200 {object} map[string]string "Latest version information"
// @Failure default {object} dto.ErrorDto "Error"
// @Router /api/version/latest [get]
func (h *handler) getLatestVersion(c *gin.Context) error {
tag, err := h.service.GetLatestVersion(c.Request.Context())
if err != nil {
return err
}
utils.SetCacheControlHeader(c, 5*time.Minute, 15*time.Minute)
c.JSON(http.StatusOK, gin.H{
"latestVersion": tag,
})
return nil
}
// getCurrentVersion godoc
// @Summary Get current deployed version of Pocket ID
// @Tags Version
// @Produce json
// @Success 200 {object} map[string]string "Current version information"
// @Failure default {object} dto.ErrorDto "Error"
// @Router /api/version/current [get]
func (h *handler) getCurrentVersion(c *gin.Context) error {
c.JSON(http.StatusOK, gin.H{
"currentVersion": common.Version,
})
return nil
}
// getSqliteStorageWarning godoc
// @Summary Get whether the SQLite storage warning should be shown
// @Description Reports whether Pocket ID found its SQLite database on a networked filesystem, which is unsupported and can lead to database corruption
// @Tags Storage
// @Produce json
// @Success 200 {object} map[string]bool "SQLite storage warning state"
// @Failure default {object} dto.ErrorDto "Error"
// @Router /api/storage/sqlite-warning [get]
func (h *handler) getSqliteStorageWarning(c *gin.Context) error {
c.JSON(http.StatusOK, gin.H{
"showWarning": h.service.ShowSQLiteStorageWarning(),
})
return nil
}

View File

@@ -0,0 +1,38 @@
package environment
import (
"net/http"
"github.com/gin-gonic/gin"
"github.com/pocket-id/pocket-id/backend/internal/httpserver"
)
type Dependencies struct {
HTTPClient *http.Client
// SQLiteOnNetworkedFilesystem is true when the SQLite database was found on a networked filesystem
// It's always false when using Postgres
SQLiteOnNetworkedFilesystem bool
}
// Module exposes read-only facts about the environment Pocket ID runs in, such as its version and where its database is stored
type Module struct {
service *Service
handler *handler
}
func New(deps Dependencies) *Module {
service := newService(deps)
return &Module{
service: service,
handler: newHandler(service),
}
}
// RegisterRoutes mounts the environment endpoints
func (m *Module) RegisterRoutes(apiGroup *gin.RouterGroup, auth gin.HandlerFunc) {
apiGroup.GET("/version/latest", httpserver.Handle(m.handler.getLatestVersion))
apiGroup.GET("/version/current", auth, httpserver.Handle(m.handler.getCurrentVersion))
apiGroup.GET("/storage/sqlite-warning", auth, httpserver.Handle(m.handler.getSqliteStorageWarning))
}

View File

@@ -1,4 +1,4 @@
package service
package environment
import (
"context"
@@ -19,19 +19,22 @@ const (
versionCheckURL = "https://api.github.com/repos/pocket-id/pocket-id/releases/latest"
)
type VersionService struct {
type Service struct {
httpClient *http.Client
cache *utils.Cache[string]
sqliteOnNetworkedFilesystem bool
}
func NewVersionService(httpClient *http.Client) *VersionService {
return &VersionService{
httpClient: httpClient,
cache: utils.New[string](versionTTL),
func newService(deps Dependencies) *Service {
return &Service{
httpClient: deps.HTTPClient,
cache: utils.New[string](versionTTL),
sqliteOnNetworkedFilesystem: deps.SQLiteOnNetworkedFilesystem,
}
}
func (s *VersionService) GetLatestVersion(ctx context.Context) (string, error) {
func (s *Service) GetLatestVersion(ctx context.Context) (string, error) {
if common.EnvConfig.VersionCheckDisabled {
return "", nil
}
@@ -76,3 +79,8 @@ func (s *VersionService) GetLatestVersion(ctx context.Context) (string, error) {
return version, err
}
// ShowSQLiteStorageWarning reports whether admins should be warned that the SQLite database is on a networked filesystem
func (s *Service) ShowSQLiteStorageWarning() bool {
return s.sqliteOnNetworkedFilesystem && !bool(common.EnvConfig.DismissSQLiteStorageWarning)
}

View File

@@ -0,0 +1,36 @@
package environment
import (
"testing"
"github.com/stretchr/testify/assert"
"github.com/pocket-id/pocket-id/backend/internal/common"
)
func TestShowSQLiteStorageWarning(t *testing.T) {
tests := []struct {
name string
sqliteOnNetworkedFilesystem bool
dismissed bool
want bool
}{
{name: "warns when the database is on a networked filesystem", sqliteOnNetworkedFilesystem: true, want: true},
{name: "does not warn when the database is on a local filesystem", sqliteOnNetworkedFilesystem: false, want: false},
{name: "does not warn when the warning has been dismissed", sqliteOnNetworkedFilesystem: true, dismissed: true, want: false},
{name: "does not warn when dismissed and the database is on a local filesystem", sqliteOnNetworkedFilesystem: false, dismissed: true, want: false},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
prevConfig := common.EnvConfig
t.Cleanup(func() {
common.EnvConfig = prevConfig
})
common.EnvConfig.DismissSQLiteStorageWarning = common.DismissSQLiteStorageWarningConfig(tt.dismissed)
svc := newService(Dependencies{SQLiteOnNetworkedFilesystem: tt.sqliteOnNetworkedFilesystem})
assert.Equal(t, tt.want, svc.ShowSQLiteStorageWarning())
})
}
}

View File

@@ -99,6 +99,7 @@
"application_configuration": "Application Configuration",
"settings": "Settings",
"update_pocket_id": "Update Pocket ID",
"sqlite_storage_warning": "We detected that your SQLite database is stored on a network-attached drive like NFS, SMB, or FUSE. This is unsupported and can lead to your database getting corrupted. {#link href=|https://pocket-id.org/docs/configuration/environment-variables#sqlite|}See docs.{/link}",
"powered_by": "Powered by",
"see_your_recent_account_activities": "See your account activities within the configured retention period.",
"time": "Time",

View File

@@ -1,5 +1,5 @@
<script lang="ts" module>
import { type VariantProps, tv } from 'tailwind-variants';
import { tv, type VariantProps } from 'tailwind-variants';
export const alertVariants = tv({
base: "grid gap-0.5 rounded-2xl border px-4 py-3 text-left text-sm has-data-[slot=alert-action]:relative has-data-[slot=alert-action]:pr-18 has-[>svg]:grid-cols-[auto_1fr] has-[>svg]:gap-x-2.5 *:[svg]:row-span-2 *:[svg]:translate-y-0.5 *:[svg]:text-current *:[svg:not([class*='size-'])]:size-4 group/alert relative w-full",
@@ -7,7 +7,7 @@
variant: {
default: 'bg-card text-card-foreground',
destructive:
'text-destructive bg-card *:data-[slot=alert-description]:text-destructive/90 *:[svg]:text-current',
'bg-red-200 text-red-900 dark:bg-red-900 dark:text-red-100 *:[svg]:text-current',
success:
'bg-green-100 text-green-900 dark:bg-green-900 dark:text-green-100 *:[svg]:text-current',
info: 'bg-blue-100 text-blue-900 dark:bg-blue-900 dark:text-blue-100 *:[svg]:text-current',
@@ -23,10 +23,10 @@
</script>
<script lang="ts">
import type { HTMLAttributes } from 'svelte/elements';
import { cn, type WithElementRef } from '$lib/utils/style.js';
import { LucideX } from '@lucide/svelte';
import { onMount } from 'svelte';
import type { HTMLAttributes } from 'svelte/elements';
let {
ref = $bindable(null),

View File

@@ -0,0 +1,8 @@
import APIService from './api-service';
export default class StorageService extends APIService {
getSqliteStorageWarning = async () => {
const response = await this.api.get('/storage/sqlite-warning').then((res) => res.data);
return response.showWarning as boolean;
};
}

View File

@@ -1,9 +1,12 @@
<script lang="ts">
import EmailVerificationStateBox from '$lib/components/email-verification-state-box.svelte';
import FadeWrapper from '$lib/components/fade-wrapper.svelte';
import FormattedMessage from '$lib/components/formatted-message.svelte';
import Sidebar from '$lib/components/sidebar.svelte';
import * as Alert from '$lib/components/ui/alert';
import { m } from '$lib/paraglide/messages';
import userStore from '$lib/stores/user-store';
import { LucideTriangleAlert } from '@lucide/svelte';
import type { Snippet } from 'svelte';
import { fade, fly } from 'svelte/transition';
import type { LayoutData } from './$types';
@@ -16,7 +19,7 @@
data: LayoutData;
} = $props();
const { versionInformation, user } = data;
const { versionInformation, sqliteStorageWarning, user } = data;
type NavItem = {
href?: string;
@@ -55,7 +58,7 @@
in:fade={{ duration: 200 }}
class="mx-auto flex w-full max-w-[1720px] flex-col gap-x-8 gap-y-8 p-4 md:p-8 lg:flex-row"
>
<div class="min-w-[200px] xl:min-w-[250px]">
<div class="w-full lg:w-[200px] lg:shrink-0 xl:w-[250px]">
<div in:fly={{ x: -15, duration: 200 }} class="sticky top-6">
<Sidebar
{items}
@@ -68,6 +71,14 @@
<div class="flex w-full flex-col gap-4 overflow-hidden pb-2 px-2">
<FadeWrapper>
{#if sqliteStorageWarning && ($userStore?.isAdmin || user?.isAdmin)}
<Alert.Root variant="destructive">
<LucideTriangleAlert />
<Alert.Description>
<FormattedMessage message={m.sqlite_storage_warning} />
</Alert.Description>
</Alert.Root>
{/if}
<EmailVerificationStateBox />
{@render children()}
</FadeWrapper>

View File

@@ -1,22 +1,22 @@
import StorageService from '$lib/services/storage-service';
import VersionService from '$lib/services/version-service';
import type { AppVersionInformation } from '$lib/types/application-configuration.type';
import type { LayoutLoad } from './$types';
export const load: LayoutLoad = async () => {
const versionService = new VersionService();
const storageService = new StorageService();
const currentVersion = versionService.getCurrentVersion();
let newestVersion = null;
let isUpToDate: boolean;
try {
newestVersion = await versionService.getNewestVersion();
// If newestVersion is empty, it means the check is disabled or failed.
// In this case, we assume the version is up to date.
isUpToDate = newestVersion === '' || newestVersion === currentVersion;
} catch {
// If the request fails, assume up-to-date to avoid showing a warning.
isUpToDate = true;
}
const [newestVersion, sqliteStorageWarning] = await Promise.all([
versionService.getNewestVersion().catch(() => null),
storageService.getSqliteStorageWarning().catch(() => false)
]);
// If newestVersion is empty, it means the check is disabled or failed.
// In this case, we assume the version is up to date.
const isUpToDate =
newestVersion === null || newestVersion === '' || newestVersion === currentVersion;
const versionInformation: AppVersionInformation = {
currentVersion: versionService.getCurrentVersion(),
@@ -25,6 +25,7 @@ export const load: LayoutLoad = async () => {
};
return {
versionInformation
versionInformation,
sqliteStorageWarning
};
};