PocketBase: The Lightweight, One-File Backend You Didn’t Know You Needed

There are times in development when you just wish the tooling could stay out of your way. You’re building a front-end — maybe a mobile app, maybe embedded — and all you want is to test some functionality: a login screen, some data flows, maybe a bit of access control. But before you know it, you’ve spun up yet another backend project, configured auth, debugged token issues, and lost half a day to infrastructure rather than solving your actual problem.

This happens to a lot of us. We start with a simple idea and end up building supporting systems that spiral beyond what we originally intended.

Sometimes, you don’t need the full stack. Sometimes, you just want something that works — fast, local, and lightweight.

"Everything should be made as simple as possible, but not simpler."

— Albert Einstein

That’s where PocketBase comes in.

What's PocketBase?

The Pocketbase team describes it as an open-source backend in 1 file. Yes, one single file. It's a complete (complete can be relative; keep that in mind) Backend as a Service (BaaS) solution that can be spun up to offer a fully fledged backend for mobile, desktop, web, and even embedded solutions.

Being a lightweight and performant backend solution, PocketBase makes use of SQLite as the storage database, which allows embedding the database into the final executable. For some use cases, this may be desirable, but for others, this may not be the database we desire, so there are trade-offs.

Why PocketBase?

PocketBase offers some eye-catching features out of the box without much tweaking. These are:

• Full backend in 1 file: This may not be a selling point to others, but it's a pretty big deal if you know. No messy node-modules folder and the million other files you need to run your node backend. PocketBase is written in Go, a statically typed and compiled language, which converts all user code into a single binary file. This file can be copied over to a target PC and run as is (if the architecture matches, of course), and all features are available for use.
• Real-time database: Once in a while, your project may need real-time subscription to record changes in your database. Data changes in the database emit events in which all subscribed clients are notified about.
• Authentication: By default, Pocketbase provides multiple methods of user authentication, including the standard username/password and OAuth protocols. Yes, you'll need to provide some credentials for the auth to work, but everything else is already implemented for you. Additionally, there are row-level access rules for record listing (List/Search Rules), record viewing (View rule), record creation (Create rule), record update (Update rule), and record delete (Delete rule), which allow for specifying rules users have to meet to perform the different tasks on the backend.
• File Storage: By default, PocketBase provides local storage for all files uploaded to the server and conveniently generates thumbnails where applicable. There is an additional option to connect to an S3 bucket for external file storage. File access can be regulated to public or token-based access to add a level of security to some files.
• Extensibility: PocketBase functionality can be extended using Go or JavaScript or used as is. This feature allows us to add new functionalities, modify existing ones, or even do things like provide your own database driver for specific use cases.
• APIs & SDK: By default, PocketBase creates a full CRUD API for every table (collection) you create. This allows querying the data via the API or any supported SDKs, allowing connection to front-end applications or 3rd party applications.
• Admin Dashboard: The backend comes with a beautiful admin dashboard, which allows admin management, collections, record operations, and much more!

Getting Started

So, how do you get and make use of PocketBase? First, navigate to the PocketBase documentation below, at the time of writing, latest version being v0.26.4;

PocketBase - Open Source backend in 1 file

Open Source backend in 1 file with realtime database, authentication, file storage and admin dashboard

PocketBase v0.26.4

Whether your current OS is Windows, Mac, or Linux on x86 or ARM64, download the corresponding binary zip file to your PC as shown below. Alternatively, navigate to the PocketBase release page and get the platform release binary from there.

Once downloaded, use your favorite zip tool to unzip the archive to your desired directory. This should give three files as shown below. Of concern, we'll only use the pocketbase binary file.

Starting the server

Starting the PocketBase server is pretty simple. As the docs say, execute the binary and pass the serve command argument to it as shown below. This will spin up the PocketBase server on the default port 8090 which we can override if need be. Being the first time spinning the server, a couple of directories will be created to store the database data, migration scripts, and file assets.

cd <unzipped directory>
./pocketbase serve

By default, the server in dev mode spins up the admin panel on our default browser for us to create a default admin user. This is the admin user we'll use for logging into the admin panel going forward.

From the admin panel, we can:

• Create New Collections: This is new tables in SQL terms, which will contain the record fields. Each collection can additionally specify the access rules; by default, only admins can perform CRUD on any collection data. There are 3 types of collections:
  • Base Type: Any general collection; this type adds a unique record ID and created and updated timestamps.
  • Auth Type: These records allow for logging into your applications. This template extends the Base Type with fields like password, tokenKey, email, verified, emailVisibility, etc which help in capturing user login information.
  • View Type: Analogous to the SQL View type, because it's exactly that. A read-only view created by writing an SQL statement.
• Create/Update/Delete Records: We can perform CRUD operations on data on existing collections.
• Manage Access Rules: The create collections drawer has two tabs or more, the second being API Rules in which we define conditional statements that are evaluated for the 5 rules (listRule, viewRule, createRule, updateRule, and deleteRule). Pocketbase offers some handy macros to access other collections and records, as well as request information to determine access metrics for the current user request. Check here for more information and syntax.
• Access Logs: PocketBase provides a view to check logs with a default 5-day retention period. You can change the log level from the gear icon here to set the kind of information to be logged.

• Application Settings: Application configuration like application name, URL, SMTP settings, and backup jobs as well as collection import/export are all housed here.

• Admin Accounts: We can also manage admin accounts from this pane on the bottom left side menu icon.

So how does it all work?

When we spin up the PocketBase server, the following directories will be created:

• /pb_data : This directory will have the data.db file to store the application data, an auxiliary.db file to store log data, and a/storage/ folder to store record files if we are keeping them in the local directory.
• /pb_migrations : Created once we modify collections while running in development mode. Here, any changes on the collections are recorded into a *.js file which can be pushed to a GitHub repo, and when we pull on another server/PC, starting the server recreates the collections from the migration scripts here.
• /pb_public : Not created by default, but we can create and put any static files we want the server to serve. For instance, put here the .html and .css files to have them served.
• /pb_hooks : Not created by default, but here we can write *.pb.js scripts that extend the functionality of PocketBase. These scripts can add new routes, perform specific actions before writing data to the database, etc. Check on extending PocketBase in the docs on the full feature list we can do here.

With such a setup, we can copy the whole structure into a new computer and have the same functionality on the go.

How does it compare?

Of course, in the world of BaaS , there are several offerings. Of notable mentions:

• Google Firebase: Owned by Google, offering a free tier to some level, then a pay-per-consumption model kicks in. Uses two database kinds, Firestore and real-time database (JSON database). In terms of usability, you'll get lots of integration with the tons of Google services, which might be desirable but, of course, will be vendor-locked, and you can't host it yourself.
• AppWrite: A self-hostable BaaS offering a NoSQL database API but running MariaDB/MySQL under the hood. Has most of the features, but direct database access is a bit lacking, and I believe it's for a reason.
• SupaBase: Similar to PocketBase in terms of using a relational database and being self-hostable. The difference here is that SupaBase uses a PostgreSQL database, which can come in handy in cases where we need horizontal scaling and not just vertical scaling. If you feel PocketBase is not enough for you, this can be a better go-to for self-hosted options. Of course, it's more resource-hungry compared to PocketBase.

There are tons of choices, but it all depends on the task at hand. A balance between the effort needed, features desired, processing, etc. For instance, hosting AppWrite and SupaBase requires containerization, which adds a layer of complexity to set up but also hides a whole lot of mess when setting it up. Both are massive projects; as such, there are lots of moving pieces to consider, so containerization helps in such cases.

So, if you just needed a quick spin-up, I guess you are best sticking with PocketBase. Quick prototyping and fiddling do not need the painful hassle of looking for a hosting provider, learning a bit of Docker, or even messing with Firebase rules; maybe just get the <40mb pocketbase binary, and you are all set.

To every problem, there is a most simple solution.
Agatha Christie

What Next?

We'll soon do a walkthrough of setting up collections, record rules, API tests, and lastly extending PocketBase with JavaScript/Go. Meanwhile, play around with the docs, experiment a bit and discover the potential PocketBase can offer to your development journey.

I hope this was helpful; let me know your thoughts! Cheers!