videoteca/docs/adr/0001-backend-pocketbase.md

0001 — Backend: PocketBase

• Stato: Accettato (con riserve, vedi R-01)
• Data: 2026-10-11

Contesto

Serve un backend locale, gratuito, con DB, API, storage file e Range. Obiettivo: poca infrastruttura e poco codice.

Decisione

PocketBase (eseguibile singolo, SQLite embedded, REST, dashboard admin, storage file, hook JS, serve anche pb_public/).

Alternative

• Python + FastAPI + SQLite: più controllo e ffmpeg più naturale, ma più codice da scrivere/mantenere (API, upload, Range, migrazioni).
• Node + Express: idem.

Conseguenze

• ✔ Un solo binario (~12 MB), nessuna dipendenza, admin UI gratuita per gestire categorie in M1.
• ✔ File serviti con Range: Serve usa http.ServeContent.
• ✔ Migrazioni in pb_migrations/ committabili.
• ⚠ Pre-1.0: la documentazione ufficiale dice che la retrocompatibilità non è garantita e che non è raccomandato per applicazioni di produzione critiche senza leggere il changelog e applicare migrazioni manuali. Per un uso locale personale è accettabile; fissare la versione (oggi v0.40.5) e aggiornare in modo consapevole.
• ⚠ Limite file: i campi file hanno max ~5 MB di default; va alzato nelle opzioni del campo (verificare in M0 anche limiti di body/upload per file grandi).
• ⚠ Il motore JS dei hook (goja) è ES5/ES6 parziale, senza setTimeout, né concorrenza dentro un handler: la transcodifica non va eseguita in modo bloccante in un handler → vedi ADR 0004.

Fonti (consultate 2026-10-11)

• https://pocketbase.io/docs/ (versione, avviso pre-1.0, directory)
• https://pocketbase.io/docs/files-handling/ (limite ~5 MB, storage locale/S3)
• https://pocketbase.io/docs/js-overview/ (goja, $os, limiti del motore)
• https://github.com/pocketbase/pocketbase/blob/master/tools/filesystem/filesystem.go (Serve → http.ServeContent)