Spring til indhold

FastAPI + PocketBase: min faste backend-stak

Når der skal bygges en backend, et internt værktøj eller en SaaS-platform, griber jeg næsten altid til FastAPI plus PocketBase. Her er arkitekturen, projekterne og de fejl, der lærte mig mest.

Det er blevet mit standardvalg, fordi det er hurtigt at komme i gang med og stadig holder, når projektet vokser. Jeg har brugt det til en energiplatform med fysiske enheder, en rejseapp med live-opdateringer, adgangskontrol til fitnesscentre, overvågning af 3D-printere og flere interne værktøjer. Mønstret er det samme hver gang, og det er det, indlægget her handler om.

De to dele

FastAPI

FastAPI er et Python-framework til API'er. Jeg skriver en route som en almindelig Python-funktion, beskriver, hvad der går ind og ud, med Pydantic-modeller og får validering, fejlbeskeder og OpenAPI-dokumentation med gratis. Frameworket er async fra bunden, bruger typehints overalt og kræver meget lidt opsætning.

Det jeg sætter mest pris på, er at API'et beskriver sig selv. OpenAPI-specifikationen bliver genereret ud fra koden, så frontenden kan få typer genereret direkte fra den. Når en route ændrer form, bliver det til en typefejl i klienten i stedet for en fejl hos brugeren.

PocketBase

PocketBase er en letvægts backend i én binær fil. Den indeholder en SQLite-database, brugere og login, filhåndtering, et admin-panel og realtime-abonnementer. Der er ingen separat databaseserver at drifte, ingen auth-tjeneste at holde opdateret og intet fillager at sætte op. Den kører i én container med én volume.

Til mange projekter er det lige præcis den mængde infrastruktur, der skal til. Man får en rigtig database med schema, adgangsregler og backup, uden at skulle bruge den første uge på at sætte Postgres, en auth-løsning og en objektlagring op.

Den vigtigste beslutning: klienter taler aldrig direkte med PocketBase

PocketBase er bygget til, at klienter kan tale direkte med den. Det er fristende, fordi det er hurtigt. Jeg gør det ikke længere, og det skyldes ét bestemt projekt.

Luggage Logs første app var bygget i Flutter og talte direkte med PocketBase. Det virkede fint, indtil projektet skulle have en webversion. Da viste det sig, at forretningslogikken lå i Dart inde i appen, og at PocketBase-kald var spredt ud over mere end 15 filer. En webversion ville betyde at skrive al den logik én gang til i et andet sprog og holde de to versioner i takt for altid.

Løsningen var at sætte FastAPI ind imellem. Appen blev skiftet over ved at udskifte implementeringen bag dens eksisterende database-interface, så den talte med det nye API i stedet for med PocketBase. Webversionen fik samme API. Siden er appen blevet bygget om i Ionic Vue, og den nye app er bare endnu en klient til det samme API.

I dag følger alle mine projekter samme regler:

  • FastAPI er den eneste offentlige indgang. Web, app, enheder og integrationer kalder FastAPI. PocketBase ligger på det interne netværk.
  • Admin-nøglen forlader aldrig backenden. FastAPI taler med PocketBase som superbruger, og klienterne ser aldrig den nøgle.
  • Forretningslogik ligger ét sted. Regler om hvem der må hvad, beregninger og integrationer bor i Python. Nye klienter genbruger dem.
  • PocketBase er datalaget. Den gemmer, validerer schema og leverer realtime. Den bestemmer ikke, hvad en bruger må.

Sådan ser en forespørgsel ud

Det hjælper at følge en enkelt forespørgsel hele vejen igennem:

  1. Brugeren logger ind i appen. Appen sender e-mail og kodeord til FastAPI, aldrig til PocketBase.
  2. FastAPI beder PocketBase om at tjekke kodeordet. PocketBase svarer bare ja eller nej.
  3. Er svaret ja, udsteder FastAPI sit eget token med de rettigheder, brugeren har.
  4. Appen sender det token med på alle efterfølgende kald. FastAPI tjekker tokenet og rettighederne, før der sker noget.
  5. FastAPI henter eller skriver data i PocketBase over en intern HTTP-forbindelse og returnerer et svar, der er formet til klienten.
  6. Skal klienten have live-opdateringer, åbner den en WebSocket mod FastAPI, og FastAPI står for abonnementet mod PocketBase bag ved.

Det er et ekstra led sammenlignet med at lade klienten tale direkte med databasen. Til gengæld bliver adgang kun afgjort ét sted, i almindelig Python-kode, der kan testes.

Auth: PocketBase tjekker kodeord, FastAPI ejer sessionen

På Watt-E er auth delt op, så PocketBase kun gør det, den er god til: at gemme brugere og tjekke kodeord sikkert. Alt derefter ejer FastAPI. Den udsteder sine egne tokens, signeret med sin egen nøgle.

Med sine egne tokens kan FastAPI noget, som PocketBases tokens ikke kan. Watt-E kan fx udstede afgrænsede tokens til integrationer og AI-værktøjer. Sådan et token får kun de rettigheder, som både brugeren har og integrationen beder om. Altså fællesmængden af de to og aldrig mere. Hvis en integration kun skal kunne læse data, kan den ikke skrive, uanset hvilken bruger der har givet adgangen.

På adgangskontrol-platformen til fitnesscentre er behovet anderledes. Der er flere lejere, og hver lejer kan have sin egen måde at logge ind på: nogle via et abonnementssystem med signerede forespørgsler, andre med almindeligt login i PocketBase. Fordi auth sidder i FastAPI, er det bare forskellige implementeringer bag samme interface. Resten af systemet er ligeglad med, hvordan brugeren kom ind.

Sådan taler FastAPI med PocketBase

Der findes et Python-SDK til PocketBase, men det er uofficielt og har været ustabilt. I nyere projekter bruger jeg i stedet en tynd async HTTP-klient bygget på httpx. PocketBases REST-API er enkelt og veldokumenteret, så en lille klient med de kald, projektet faktisk bruger, er nem at skrive og nem at forstå.

Watt-E har stadig en ældre del, der bruger SDK'et, ved siden af den nye klient. Det er et godt eksempel på, at man ikke behøver skrive alt om på én gang. Ny kode bruger den nye klient, og den gamle bliver flyttet, når den alligevel skal røres.

Den dyreste fejl: synkrone kald i async kode

Den vigtigste lektie her kostede et nedbrud. Et sted i Watt-E brugte en synkron HTTP-klient inde i en async FastAPI-route. I et async-framework kører alle forespørgsler på samme event-loop. Når én route laver et blokerende kald, venter alle andre også. Health-endpointet endte med at hænge i 764 sekunder i produktion.

Rettelsen var enkel: async hele vejen ned, også i klienten mod PocketBase. Det kan være svært at opdage, fordi koden virker fint lokalt med én bruger. Derfor har jeg i dag én fælles async-klient per projekt og ingen andre måder at kalde PocketBase på.

Realtime uden at overbelaste databasen

PocketBase kan sende ændringer til abonnenter med Server-Sent Events. Den naive løsning er at lade hver klient abonnere direkte. Luggage Log gør det anderledes.

En pakkeliste til en rejse kan være åben hos mange personer på én gang. I stedet for at hver af dem har sin egen forbindelse til PocketBase, har backenden ét abonnement per rejse. Når der kommer en ændring, fordeler FastAPI den til alle tilsluttede klienter gennem asyncio-køer og WebSockets. Kører der flere backend-workers, kan Redis bruges som fælles kanal mellem dem, så en ændring når ud til alle, uanset hvilken worker klienten er forbundet til.

To detaljer gør det robust:

  • Korte stream-tokens. En WebSocket kan ikke sende headers på samme måde som et almindeligt kald. Klienten beder først om et kortlivet token til netop den forbindelse og bruger det i håndtrykket. Det almindelige login-token kommer aldrig i en URL.
  • Én kilde, mange modtagere. Antallet af forbindelser til PocketBase afhænger af antallet af aktive rejser, ikke af antallet af brugere.

På Watt-E er realtime en anden historie, fordi der er fysiske enheder involveret. Der går beskeder til og fra enhederne over MQTT, og backenden har både en publisher og en subscriber på den beskedbus. Firmwaren til enhederne ligger i samme repository, så protokollen kan ændres ét sted.

Migrationer og schema

Schema er der, hvor PocketBase har overrasket mig mest. Der er tre ting, man skal vide.

Admin-panelet kan skrive filer, der forsvinder

PocketBase kan automatisk skrive migrationsfiler, når man ændrer schema i admin-panelet. Det lyder praktisk, men på en server kører PocketBase i en container. De filer bliver skrevet inde i containeren og forsvinder ved næste deploy. Så har man en database, hvis schema ikke findes i git.

På Watt-E er den automatik slået fra. Schemaet bliver i stedet sat op af et script, når backenden starter. Luggage Log går den anden vej og har sine migrationer som JavaScript-filer i git, 39 af dem indtil videre. Begge dele virker. Pointen er, at schemaet skal ligge i koden og ikke kun findes som noget, nogen har klikket sig frem til på serveren.

Migrationer, der stod som kørt, men ikke virkede

Luggage Log havde en hændelse, der stadig undrer mig lidt. Migrationerne stod som kørt, filerne lå på disken, men fire collections var aldrig blevet registreret i den kørende PocketBase. API'et svarede, som om de ikke fandtes. En genstart hjalp ikke. Et redeploy hjalp heller ikke.

Løsningen blev at importere schemaet eksplicit gennem PocketBases API, med en indstilling der sikrer, at eksisterende collections ikke bliver slettet. Siden har jeg haft en fast regel: efter hver schema-ændring tjekker jeg med et rigtigt kald mod API'et, at det nye faktisk findes. At migrationen melder succes, er ikke nok.

Lås versionen

En anden lektie fra samme projekt: PocketBase-imaget var sat til :latest. En dag var produktionen stille gledet op på en nyere version. Det er ikke bare et spørgsmål om at rulle tilbage, for når databasefilen først er åbnet af en nyere version, kan den være opgraderet. At gå tilbage ville betyde at nedgradere en database.

I dag er imaget låst til et præcist digest, og opgraderinger er en bevidst handling med backup før og test efter.

Hooks: når noget skal ske præcis én gang

PocketBase understøtter hooks skrevet i JavaScript, der kører inde i databasen. Jeg bruger dem sparsomt, fordi logik helst skal ligge i FastAPI. Men der er én type problem, hvor de er det rigtige værktøj: når noget skal ske præcis én gang, selvom flere prøver på samme tid.

På behandlingsplatformen kommer opgaver ind via en beskedkø. Køen kan levere den samme besked mere end én gang, og det er normal opførsel for mange beskedkøer. Hvis to workers tager den samme opgave, sker den to gange. Løsningen er et hook, der i én transaktion tjekker, om opgaven stadig er ledig, og markerer den som taget. Den første vinder, den anden får et nej. Adgangskontrol-platformen bruger samme teknik til at sikre, at noget kun kan gøres krav på én gang.

Man kunne godt lave det i FastAPI med låse, men det er sikrest at gøre det der, hvor data bor, i samme transaktion.

Clean architecture på behandlingsplatformen

Behandlingsplatformen er bygget med clean architecture. Domænelaget, der indeholder reglerne for behandlinger og forløb, importerer aldrig FastAPI eller PocketBase. FastAPI er den eneste offentlige indgang, og PocketBase er gemt bag repository-interfaces.

Det kan lyde akademisk, men det har to meget praktiske fordele. Domænelogikken kan testes uden en database. Og den dag et projekt vokser ud af PocketBase, er det adapteren, der skal skiftes, og forretningslogikken bliver stående.

Hvor jeg har brugt den

Watt-E

Watt-E har FastAPI og PocketBase som kernen i platformen, sammen med Redis og MQTT til de fysiske enheder. FastAPI håndterer login, adgang, tokens og integrationer. PocketBase gemmer data. Platformen kører på sin egen Hetzner-server via Coolify.

Luggage Log

Luggage Log bruger samme kombination, med Redis, en baggrundsworker til opgaver der ikke skal blokere et kald, og rate limiting på API'et. Det er her, realtime-arkitekturen med ét abonnement per rejse er bygget.

Adgangskontrol til fitnesscentre

En platform med flere lejere, flere måder at logge ind på og integration til smarte låse og faste PIN-koder. PocketBase-hooks sikrer, at ting der kun må ske én gang, også kun sker én gang.

IoT-overvågning af 3D-printere

En Raspberry Pi ved printerne fungerer som proxy og sender data over Tailscale til en server med FastAPI, MQTT og en tidsseriedatabase. Data fra printerne går gennem en ingest-tjeneste, og en React-frontend viser status.

Kontorplanlægning

Et internt værktøj til planlægning på et laboratorium, bygget i FastAPI og PocketBase som afløser for en ældre løsning i Google Apps Script. Et godt eksempel på, at stakken også passer til små værktøjer, hvor der næsten ikke må være noget at drifte.

Hvornår jeg ikke vælger PocketBase

PocketBase passer ikke til alt. Jeg vælger noget andet, når:

  • Der er mange samtidige skrivninger. SQLite er hurtig, men skriver én ting ad gangen. Til systemer med tung, samtidig skrivning er Postgres et bedre valg.
  • Data skal deles af flere tjenester. Hvis flere systemer skal læse og skrive i samme database direkte, passer en klassisk databaseserver bedre.
  • Der skal bruges avancerede SQL-funktioner, som tunge rapporter, komplekse joins på tværs af store tabeller eller udvidelser til tidsserie- eller geodata.
  • Kunden allerede har Postgres og et team, der kender det.

I de tilfælde beholder jeg FastAPI og skifter datalaget ud, typisk med Postgres. Fordi klienterne aldrig har talt med PocketBase direkte, og fordi domænet ligger bag interfaces, er det bare en udskiftning af en adapter. Mine hjemmesider og webshops kører i øvrigt på Postgres via Payload og Medusa, fordi de behov er anderledes.

Drift på egen server

Mange af de sværeste fejl, jeg har mødt, var ikke i koden. Watt-E har lært mig en håndfuld ting om at drifte en platform på egen server:

  • Build-cache fylder disken. Docker gemmer lag fra hvert build. På et tidspunkt fyldte de disken op, og databasen gik ned. Diskforbrug og oprydning i build-cache er nu en fast del af driften.
  • Deploys kan sætte sig fast. Et deploy, der hang i status "i gang", blokerede køen for alle efterfølgende. Så skal man vide, hvordan man afbryder det.
  • Pladsholdere i miljøvariabler. Tekster som "Set VAR" endte som rigtige værdier. Validér konfiguration ved opstart, så en manglende nøgle giver en tydelig fejl i stedet for mærkelig opførsel.
  • Brug PocketBases egen backup. Da platformen flyttede til sin egen server, blev data flyttet med PocketBases backup- og restore-API. Det var den mest smertefri del af flytningen.

Min tjekliste før et deploy

  1. Er PocketBase-imaget låst til en præcis version?
  2. Ligger alle schema-ændringer i git, og er automatisk migrationsgenerering slået fra på serveren?
  3. Er der taget backup før en migration eller en opgradering?
  4. Bruger al kode mod PocketBase den fælles async-klient?
  5. Er PocketBase kun tilgængelig på det interne netværk?
  6. Svarer health-endpointet hurtigt?
  7. Er alle miljøvariabler sat til rigtige værdier, og fejler opstarten tydeligt, hvis en mangler?
  8. Er der plads på disken?
  9. Efter deploy: findes de nye collections og felter faktisk, når man kalder API'et?

Hvad du får ud af det

  • Hurtig udvikling. Fra idé til kørende API på timer, ikke uger.
  • Lav driftskompleksitet. Én PocketBase-container i stedet for database, auth-tjeneste og fillager hver for sig.
  • Realtime uden ekstra infrastruktur. Live-opdateringer er indbygget, og en arkitektur der skalerer med antal rejser, enheder eller rum frem for antal brugere.
  • Én indgang for alle klienter. Alle klienter går gennem samme API, så en ny app eller en webversion ikke kræver en ny backend.
  • Mulighed for at skifte database. Vokser projektet ud af PocketBase, skiftes datalaget, og resten bliver stående.

Arbejder du i samme stak?

Bruger du selv FastAPI og PocketBase, eller overvejer du det til et projekt? Jeg deler gerne erfaringer om auth, realtime, migrationer og drift på egen server. Skriv til mig.