How to Use PocketBase: The Beginner's Guide (First Binary, First Collection, Auth, the JS SDK, and the Backup Rule)

CodexFuse Team · 2026-10-31T03:57:27.257Z · 14 min read

Learn how to use PocketBase from scratch: install the single-binary backend, create your admin account, build your first collection, lock down API rules, add auth, and connect the JS SDK — with the backup rule before production.

How to Use PocketBase: The Beginner's Guide (First Binary, First Collection, Auth, the JS SDK, and the Backup Rule)

Learning how to use PocketBase starts with one fact: the whole backend is a single file. PocketBase is an open-source backend written in Go that ships as one executable containing an embedded SQLite database, a realtime REST API, user authentication, file storage, and an admin dashboard — no separate database server, no message broker, no dependency stack to install. If you have ever wanted a backend without provisioning a backend, this PocketBase for beginners tutorial walks the complete arc in one sitting: download the binary, start it, create your admin account, build your first collection, lock down API rules, add email/password and OAuth2 auth, connect a real app with the JavaScript SDK, subscribe to realtime updates, and learn the one backup rule that matters before anything goes live. While you work through the examples, you can fire each endpoint at a REST API tester to see exactly what every request sends and every response returns.

How Do You Use PocketBase? The 30-Second Version

You use PocketBase by downloading one binary, starting it, and doing everything else in a browser dashboard: create collections, set who can touch them, and call the auto-generated API from your app. The full beginner loop looks like this:

1. Download the binary for your platform from the download page on pocketbase.io, unzip it, and run ./pocketbase serve in a terminal.
2. Create your admin account at http://127.0.0.1:8090/_/ — on first launch PocketBase prompts you to create the initial admin (superuser) before anything else.
3. Create a collection in the dashboard — for example posts — and add fields such as text, number, relation, or file.
4. Set API rules per collection: each of the five actions (list, view, create, update, delete) gets a filter expression, or stays empty for public access.
5. Enable auth on a users collection — email/password login, one-time-password codes, and OAuth2 providers are all built in.
6. Call it from your app with the JavaScript SDK: npm install pocketbase, connect to http://127.0.0.1:8090, and use getList, create, update, and subscribe.
7. Back up pb_data before anything goes live — your entire database and uploaded files live in that one folder.

That is the whole shape of PocketBase: one binary in, a full backend out. The rest of this guide fills in each step.

What Is PocketBase?

PocketBase is an open-source backend packaged as a single executable file. Inside that one binary you get an embedded SQLite database, a realtime REST API, authentication (email/password, one-time codes, OAuth2), file storage, and a full admin dashboard — and there is nothing else to install. It is written in Go, and it was designed so that client-side apps (browser SPAs, mobile apps) talk directly to its Web APIs, with the access and filter controls for your data expressed as per-collection API rules.

It is a lightweight, self-hosted alternative to Firebase or Supabase for small and medium projects. It is not a replacement for a horizontally scaled database cluster: everything lives in one SQLite file with a single writer, so if your project needs massive concurrent writes or complex joins across huge tables, a managed Postgres service is the honest choice — the comparison section near the end draws that line for you.

What Do You Need Before You Start?

You need a computer running Windows, macOS, or Linux, a text editor, and a terminal you are comfortable typing commands into. That is genuinely all of it — there is no database to install, no cloud account to create, and no Docker knowledge required for the local part of this guide. If you want to follow the JavaScript SDK section with a real project, Node.js and npm on your machine make that smoother, and any familiarity with making HTTP requests helps you read the API examples.

How Do You Install PocketBase?

You install PocketBase by downloading a prebuilt executable from the download page on pocketbase.io and running it — there is no installer wizard and no dependency installation. The downloads cover Windows, macOS, and Linux (both Intel and ARM builds), so pick the archive for your platform, extract it into a folder, open a terminal in that folder, and start the server:

./pocketbase serve

That single command starts the web server and the admin dashboard at http://127.0.0.1:8090/_/. The current release is v0.40.6 (published October 23, 2026), and you can upgrade a running installation later with ./pocketbase update — note the release notes say this is likely the last release hosted on GitHub, with future releases moving to a new update host, so keep an eye on the official site for the new download route if update ever reports a changed host.

How Do You Create Your Admin Account?

You create your admin account in the browser: open http://127.0.0.1:8090/_/ and, on the very first launch, PocketBase asks you to create the initial admin (superuser) account before it lets you do anything else. Pick a strong email and password — this account can read and write everything, and the collection API rules are ignored for superusers, so treat these credentials the way you would treat root access to a server.

Once you are in, the dashboard is where your whole backend life happens: creating collections and fields, browsing and editing records, managing users and uploaded files, reading the request logs, and changing settings. Everything you are about to learn in this guide happens here, in the browser, with no SQL and no config files.

What Is a Collection in PocketBase?

A collection is PocketBase's word for a table — it is the structure that holds your records, and creating one instantly exposes CRUD endpoints and realtime subscriptions for it. There are two kinds: base collections for your own data (posts, products, messages) and auth collections for anything that logs in (users, members, admins). An auth collection gets extra options: email/password login, one-time-password codes, multi-factor authentication, and OAuth2 providers.

To build your first collection, click New collection in the dashboard, name it posts, and add fields — text for a title, number for a view count, relation to link a post to its author, file for an upload. Field names become the keys in your API responses, so choose them the way you would choose variable names: lowercase, no spaces, descriptive.

How Do API Rules Work?

API rules are the security model: every collection has five actions — list, view, create, update, delete — and each action carries a filter expression that decides who may perform it. An empty rule means public access; a rule like @request.auth.id != "" means only a logged-in user may perform that action. The rules are evaluated per collection, per action, on every request, so you grant the minimum each action needs and nothing more.

Here is the cheat sheet to keep beside your first project — the most common rule for each action, and what it means in plain English:

The beginner mistake to avoid is leaving every rule empty because "it is just a prototype." Empty rules are public API endpoints that anyone on the internet can read and write to the moment your server is reachable. Write the strictest rules that still let your app work, and loosen them only when a feature genuinely requires it.

How Do You Add Authentication?

You add authentication by creating an auth collection — usually called users — and enabling the login methods you want in its options. The simplest path is the Identity/Password option: once enabled, users register and log in with an email and password through the collection's auth API. PocketBase's Web APIs are fully stateless — there are no server-side sessions, and even the tokens are not stored in the database — so the client authenticates by sending a valid Authorization:YOUR_AUTH_TOKEN header with each request.

With the JavaScript SDK the login flow is three lines:

import PocketBase from 'pocketbase';

const pb = new PocketBase('http://127.0.0.1:8090');

const authData = await pb.collection('users').authWithPassword('[email protected]', '1234567890');

// the login state lives in the auth store from here on
console.log(pb.authStore.isValid);   // true
console.log(pb.authStore.token);     // the auth token
console.log(pb.authStore.record.id); // the logged-in user's id

// there is no server-side logout endpoint — clear the local state
pb.authStore.clear();

Beyond passwords, you can enable one-time-password (email code) login, OAuth2 sign-in with providers like Google, GitHub, and Microsoft (you create the OAuth2 app in the provider's dashboard and register https://yourdomain.com/api/oauth2-redirect as the callback URL), and multi-factor authentication, which asks the user to authenticate with any two different methods. Remember two caveats from the official docs: OAuth2 is not available for the _superusers admin collection, and superusers bypass every collection API rule — another reason the admin credentials never belong in client-side code.

One honest limitation to plan for: email-based flows (verification emails, password resets, one-time codes) only send mail after you configure PocketBase's SMTP mail settings in the dashboard. Until then, register accounts and test logins locally, and wire up a mail provider before you invite real users.

How Do You Use the JavaScript SDK?

You use the JavaScript SDK by installing the pocketbase npm package and pointing one client instance at your server — on the client side a single global instance for the whole app lifecycle is the recommended pattern. The SDK wraps auth, CRUD, file uploads, and realtime subscriptions, and the same patterns work in the browser, Node.js, and React Native.

npm install pocketbase

With the client connected, every collection instantly gives you a typed-feeling CRUD surface:

import PocketBase from 'pocketbase';

const pb = new PocketBase('http://127.0.0.1:8090');

// list with filter, sort, and a joined relation
const list = await pb.collection('posts').getList(1, 100, {
  filter: 'published = true',
  sort: '-created,title',
  expand: 'author',
});

// fetch one record
const record = await pb.collection('posts').getOne('RECORD_ID');

// create a record (the logged-in user becomes its author)
const newPost = await pb.collection('posts').create({
  title: 'My first post',
  published: true,
});

// update it, then delete it
await pb.collection('posts').update(newPost.id, { title: 'Updated title' });
await pb.collection('posts').delete(newPost.id);

Filter syntax is worth learning early: it is a plain expression language (published = true, title != "", created > "2026-01-01"), and the same expressions power your API rules, so time spent here pays off twice. File uploads go through FormData on create, and you can get a public URL for an uploaded file from the returned record.

How Does Realtime Work in PocketBase?

Realtime works over server-sent events: you subscribe to a collection (or a single record) and PocketBase pushes a callback every time a record is created, updated, or deleted. The SDK makes it one line, and you unsubscribe the same way when the component unmounts or the page closes:

// live updates for every change in the collection
pb.collection('messages').subscribe('*', (e) => {
  console.log(e.action, e.record); // 'create' | 'update' | 'delete'
});

// or watch one specific record
pb.collection('posts').subscribe('RECORD_ID', (e) => {
  console.log('Post updated:', e.record);
});

// stop listening
pb.collection('messages').unsubscribe();

This is the feature that makes PocketBase feel magical in demos: a chat message, a live comment feed, or a collaborative todo list works with no websocket server of your own, no pub/sub broker, and no extra code beyond the subscribe call. For a chat app, one subscribed collection plus the auth rules from the earlier section is the entire backend.

What Are PocketBase's Limits?

The honest limits are three: it is a single SQLite file with a single writer, it is one server process, and it sends no email until you configure SMTP. Everything — users, records, file metadata — lives in one embedded SQLite database, which means PocketBase does not horizontally scale: you cannot run five instances against the same data the way you would with Postgres. For small and medium projects, prototypes, internal tools, and indie apps this is a non-issue and actually a feature (one file to back up); for high-write workloads or true multi-region scale, it is the wrong tool.

The other two limits are operational, not architectural. Superusers ignore all API rules, so a leaked admin token is a total compromise — keep admin credentials server-side only, and use regular auth-collection users for everything the app does. And remember that verification emails, password resets, and one-time codes queue up silently until SMTP is configured, so test the mail path before launch day, not on it.

How Do You Back Up PocketBase?

You back up PocketBase by copying the pb_data folder — that is the whole rule, and it should become a habit before anything goes live. The folder holds the SQLite database file, the uploaded files in storage, and the logs; copy it while the server is stopped (or copy the database with SQLite's own backup tooling while it runs), and a restore is simply putting the folder back where it was.

On a server this becomes a cron job: stop the process or use an atomic copy, rsync the folder to another machine or object storage, and verify the copy restores. The nightmare scenario is discovering your backup strategy the day after the disk dies — with a single-folder backend there is no excuse for not having one from day one.

How Do You Deploy PocketBase to a Server?

You deploy PocketBase the way you deploy any single binary: copy it to a server, run it, and put it behind HTTPS. Any VPS works — if the concept is new to you, start with what is VPS hosting — then run ./pocketbase serve on the server inside a process manager so it restarts if it crashes, and front it with a reverse proxy (or a CDN like Cloudflare — see the Cloudflare beginner guide) so your API and the /_/ dashboard are served over TLS. The dashboard port is 8090 by default; in production you typically proxy your domain to it and never expose the port directly.

Two alternative routes exist. There is a Docker route — PocketBase ships container images, and if you already run containers the Docker beginner guide covers the concepts — just remember to mount pb_data as a persistent volume, or your database evaporates with the container. And one-click platforms such as Coolify and Railway offer PocketBase templates if you would rather not touch a terminal on the server at all. Whichever route you take, the deploy checklist is the same: locked-down API rules, SMTP configured, pb_data backups running, HTTPS on, and the superuser credentials stored somewhere safe and server-side.

PocketBase vs Supabase: Which Should You Pick?

Pick PocketBase when you want to own your backend as one self-hosted binary; pick Supabase when you want a hosted Postgres with managed scale. They solve the same beginner pain — "give me a backend without building one" — from opposite directions, and the Supabase beginner guide walks the hosted side of the same arc. Here is the honest trade-off:

Neither choice is permanent: PocketBase exports your data as ordinary files and JSON, so starting self-hosted and migrating later is a weekend project, not a rewrite.

What Are the Beginner Mistakes with PocketBase?

Frequently Asked Questions

Is PocketBase really free?

Yes — PocketBase is open-source software, so there is no license fee and no per-user pricing. Your only cost is wherever you run it: your own laptop for development, or a VPS or container host for production. That is the whole business model of self-hosting — you trade the convenience of a managed service for a server bill you control.

Can PocketBase replace Firebase or Supabase?

For small and medium projects, yes — it covers the same surface: database, auth, file storage, realtime updates, and an admin dashboard. It cannot replace the managed scale of Firebase or Supabase's hosted Postgres; if your roadmap includes millions of users or heavy concurrent writes, start with the managed service. For prototypes, indie apps, and internal tools, PocketBase is often the faster and cheaper path.

Do I need a separate database with PocketBase?

No. The database is embedded SQLite inside the binary — your data lives in a single file inside the pb_data folder, and there is nothing else to install, configure, or tune. That is what makes the backup rule so simple: copy one folder and you have copied everything.

How do I update PocketBase?

Run ./pocketbase update from the folder containing the binary — it downloads and applies the current release, which is v0.40.6 as of October 2026. Back up pb_data first, as with any update. Note the release notes flag that future releases are moving off GitHub to a new update host, so if the command ever reports a changed host, follow the download instructions on pocketbase.io instead.

Is PocketBase production-ready?

Yes, with the operational basics in place: API rules locked down per collection and action, SMTP configured for auth emails, automated off-server pb_data backups, HTTPS in front of the server, and the superuser credentials kept strictly server-side. It powers real indie and small-business apps today — production-ready means the setup around it is ready, not just the binary.

Sources

• PocketBase official site (single-executable concept, embedded SQLite, realtime REST API, auth, file storage, admin dashboard; JS SDK examples: getList with filter/sort, getOne, create, delete, subscribe/unsubscribe) — https://pocketbase.io/ — crawled October 30, 2026
• PocketBase docs: How to use PocketBase (client-side SPA recommendation, per-collection API rules, official JS/Dart SDKs, Go/JS extension points) — https://pocketbase.io/docs/how-to-use/ — crawled October 30, 2026
• PocketBase docs: Authentication (stateless tokens not stored server-side, no logout endpoint — pb.authStore.clear(), authWithPassword, OTP, OAuth2 redirect URL pattern, MFA in v0.23+, _superusers bypass API rules and cannot use OAuth2) — https://pocketbase.io/docs/authentication/ — crawled October 30, 2026
• PocketBase GitHub releases (v0.40.6 current, published October 23, 2026; ./pocketbase update command; likely last GitHub-hosted release — future updates from a new host) — https://github.com/pocketbase/pocketbase/releases and https://api.github.com/repos/pocketbase/pocketbase/releases/latest — checked October 30, 2026
• KBVE PocketBase guide (Docker/CLI/Coolify install routes, first-launch admin account at /_/ on port 8090, collection creation, API rules list/view/create/update/delete with @request.auth.id != "" example, realtime over server-sent events, /api/collections/{name}/records REST paths) — https://kbve.com/application/pocketbase/ — crawled October 30, 2026
• HackerNoon: A Lightweight, Open-Source Backend You Can Set Up in Minutes (prebuilt executables for Windows/macOS/Linux, ./pocketbase serve one-command start, Go module mode, JSVM extension) — https://hackernoon.com/a-lightweight-open-source-backend-you-can-set-up-in-minutes — crawled October 30, 2026
• dev.to: PocketBase Has a Free API You Should Know About (single-binary full backend, instant REST CRUD, JS SDK authWithPassword/getFullList/create, realtime subscribe actions create/update/delete, SQLite single-writer and no built-in email sending limits) — https://dev.to/0012303/pocketbase-has-a-free-api-you-should-know-about-33e6 — crawled October 30, 2026
• BytesizeGo: PocketBase is written in Go (Go framework mode, hooks chain, all data in a single SQLite database file) — https://www.bytesizego.com/blog/pocketbase-is-written-in-go-and-you-can-use-it-as-a-framewor — crawled October 30, 2026
• BrightCoding: PocketBase — The Modern Backend Solution for Developers (fresh setup arc: download → serve → admin dashboard → Go-framework branch) — https://www.blog.brightcoding.dev/2026/06/30/pocketbase-the-modern-backend-solution-for-developers — intent reference, crawled October 29, 2026