What Is PocketBase? A Complete Backend in a Single File

Why AI Coders Need to Know This

Think about every time you've started a new project. Before you can build a single feature, you're wrestling with: setting up a database, configuring auth, figuring out where to store uploaded files, and wiring all of it together. That's before you write one line of actual app code.

PocketBase eliminates all of that in a single step. Download one binary file, double-click it (or run it in a terminal), and you have a fully functional backend running on your machine. Open http://127.0.0.1:8090/_/ and there's a complete admin dashboard where you can create tables, manage users, and inspect your data — right now, no signup required.

That's why AI tools love recommending it. When you ask Claude or Cursor to "build me an app with user accounts and a database," PocketBase is often the fastest path to a working result. The AI scaffolds the frontend, points it at your PocketBase instance, and you have a full-stack app running locally in under ten minutes.

PocketBase ships everything you need for most apps:

• Database — SQLite under the hood. You create "collections" (think: tables) through the admin UI or the API.
• Authentication — Email/password, OAuth (Google, GitHub, etc.), anonymous auth. Built in, zero config.
• File storage — Upload files and images directly to PocketBase. It handles storage on disk.
• Real-time subscriptions — Listen to changes in your collections over a WebSocket connection. Your UI updates automatically when data changes.
• REST API — Every collection you create automatically gets CRUD endpoints. No routes to write.
• Admin dashboard — A full web UI to manage everything, included in the binary.

The whole thing — database engine, web server, admin panel, auth system, file storage — runs as one ~30MB file. It's genuinely remarkable.

The Real-World Scenario

Chuck is building a job-site inspection tool. Foremen fill out inspection reports on their phones, upload photos of issues, and the site super can review everything from the office. He needs user accounts, a database of reports, photo uploads, and maybe real-time updates when a new report comes in. He's been coding with AI for two years but has never set up a backend server from scratch.

Build a job-site inspection app using PocketBase as the backend:
- Users can log in with email and password
- Foremen can submit inspection reports (site name, date, notes, photos)
- Site supers can view all reports
- Photos upload to PocketBase storage
- Show me: how to set up PocketBase locally, the collection structure,
  and the JavaScript frontend code to create and list reports
- Use the PocketBase JS SDK

What AI Generated

The AI gives you three things: setup instructions, collection structure, and frontend code. Here's what that looks like.

# Step 1: Download and run PocketBase (Mac/Linux)
# Go to pocketbase.io, download the binary for your OS, then:
./pocketbase serve

# That's it. Your backend is running at:
# http://127.0.0.1:8090        ← API endpoint
# http://127.0.0.1:8090/_/     ← Admin dashboard

# Step 2: Open the admin dashboard, create your admin account,
# then create a Collection called "reports" with these fields:
#   site_name   (Text, required)
#   date        (Date, required)
#   notes       (Text)
#   photos      (File, multiple, images only)
# PocketBase automatically adds: id, created, updated, and the user relation

// Install the SDK
// npm install pocketbase

// lib/pocketbase.js — client setup
import PocketBase from 'pocketbase';

// Point at your running PocketBase instance
const pb = new PocketBase('http://127.0.0.1:8090');

export default pb;

// auth.js — log in a user
import pb from './lib/pocketbase';

async function login(email, password) {
  const authData = await pb.collection('users').authWithPassword(
    email,
    password
  );
  // pb.authStore.isValid is now true
  // pb.authStore.model has the user record
  console.log('Logged in as:', authData.record.email);
}

// Check if already logged in (persists across page reloads)
if (pb.authStore.isValid) {
  console.log('Already logged in:', pb.authStore.model.email);
}

// reports.js — create and list reports
import pb from './lib/pocketbase';

// Create a new inspection report with photos
async function createReport(siteName, date, notes, photoFiles) {
  const formData = new FormData();
  formData.append('site_name', siteName);
  formData.append('date', date);
  formData.append('notes', notes);
  formData.append('user', pb.authStore.model.id); // link to current user

  // Attach multiple photos
  for (const file of photoFiles) {
    formData.append('photos', file);
  }

  const record = await pb.collection('reports').create(formData);
  return record;
}

// List all reports (site supers see all; foremen see their own)
async function getReports() {
  const records = await pb.collection('reports').getList(1, 50, {
    sort: '-created',       // newest first
    expand: 'user',         // include the user record in results
  });
  return records.items;
}

// Get the URL for a photo stored in PocketBase
function getPhotoUrl(record, filename) {
  return pb.files.getUrl(record, filename);
}

// Real-time: listen for new reports as they come in
pb.collection('reports').subscribe('*', function(e) {
  console.log('Action:', e.action);   // "create", "update", or "delete"
  console.log('Record:', e.record);
  // Update your UI here
});

// Clean up subscription when done
// pb.collection('reports').unsubscribe('*');

Understanding Each Part

Collections are your tables

In a traditional database, you create tables with columns. In PocketBase, these are called "collections" with "fields" — same concept, friendlier name. You define them in the admin dashboard by clicking "New Collection" and adding fields with a point-and-click interface. No SQL required. PocketBase automatically adds id, created, and updated fields to every collection.

PocketBase has three collection types:

• Base — A regular data collection. Use this for most things.
• Auth — A collection with built-in authentication fields. The users collection is an Auth collection by default.
• View — A read-only collection based on a SQL query. Advanced use case.

API rules control who sees what

This is PocketBase's equivalent of Supabase's Row Level Security — and it's the part AI most often gets wrong. Every collection has API rules for List, View, Create, Update, and Delete operations. These are simple expressions like:

// Only the record's owner can view it
@request.auth.id = user

// Any authenticated user can create
@request.auth.id != ""

// Only admins can delete
@request.auth.id = @collection.admins.user

If you leave a rule empty, that operation is locked down — no one can do it through the API. If you set it to an empty string "", that operation is open to everyone, including unauthenticated visitors. This is the opposite of what many people expect. Always check your API rules before shipping.

File uploads live on disk

When you mark a field as "File" type, PocketBase stores uploads in a pb_data/storage/ folder on the server's disk. That's it — no S3, no cloud storage to configure. The pb.files.getUrl(record, filename) call generates a URL that PocketBase serves directly. Simple, but it means your files live on the same server as your database. Back that folder up.

Real-time is built in

The .subscribe() method opens a Server-Sent Events connection to PocketBase. When any record in that collection changes — create, update, delete — your callback fires with the change. No extra infrastructure, no WebSocket server to manage. This makes PocketBase excellent for building dashboards, live feeds, and collaborative tools where you want the UI to update automatically.

The SDK persists auth automatically

When a user logs in, pb.authStore saves their token to localStorage in the browser. Next time they visit, pb.authStore.isValid is already true and you can make authenticated requests immediately. You do not need to write auth persistence logic yourself — the SDK handles it.

PocketBase vs Supabase vs Firebase

All three give you a database, auth, and file storage. The differences matter depending on what you're building.

The honest answer: for a first project or a quick prototype, PocketBase is the fastest path from zero to running app. For anything you expect to grow past a few hundred users, or where you need your data in a proper relational database with concurrent writes, Supabase is worth the extra setup. Firebase is the right call if you're building a mobile app that needs to work offline.

What AI Gets Wrong About PocketBase

Leaving API rules blank (open or locked)

This is the #1 mistake. AI often generates PocketBase code without specifying API rules, leaving collections in one of two dangerous states: completely locked (returns 403 errors for everything) or completely open (anyone on the internet can read, write, and delete your data). Always open the admin dashboard, click your collection, go to API Rules, and set explicit rules for each operation after AI scaffolds your app.

Treating SQLite like PostgreSQL

AI sometimes generates SQL queries or patterns that work in PostgreSQL but not in SQLite. SQLite has a smaller feature set — no native UUID type, limited ALTER TABLE support, no stored procedures. PocketBase's collection builder abstracts most of this away, but if you use PocketBase's "View" collections (which use raw SQL), you need SQLite-compatible queries.

Not accounting for the single-writer limitation

SQLite is a single-writer database. When one write operation is happening, all other writes wait in line. For an app where 500 users might submit a form at the same moment, this creates a write queue that can cause timeouts. AI rarely mentions this. PocketBase works well for read-heavy apps and apps where writes are infrequent, but it is not the right choice for high-concurrency write workloads.

Forgetting that the binary needs to run somewhere

PocketBase runs locally on your machine during development. When you want to share your app with real users, you need to deploy the PocketBase binary to a server. AI sometimes skips this part. You can run PocketBase on a $5/mo VPS (DigitalOcean, Hetzner, Fly.io), a Raspberry Pi, or any Linux server. It is one of the easiest backends to self-host, but you do need to host it somewhere.

Confusing the API URL for dev vs. production

Development uses http://127.0.0.1:8090. Production uses your server's domain, like https://api.myapp.com. AI often hardcodes the localhost URL. Use environment variables (VITE_PB_URL or NEXT_PUBLIC_PB_URL) so you can switch between dev and production without changing code.

When PocketBase Makes Sense (and When It Doesn't)

Use PocketBase when:

• You're building a prototype or MVP. Nothing is faster. No accounts to create, no config to wrestle with. Download, run, build.
• It's an internal tool. A tool for your team, your job site, or your small business. Low concurrent usage, simple data model — PocketBase is perfect.
• You're learning backend concepts. PocketBase's admin dashboard makes it easy to see what's happening. Great for understanding how auth, databases, and file storage actually work before you go deeper.
• You want full data ownership. No third party has your data. Your database lives on your server. You can inspect the raw SQLite file any time.
• Your app is read-heavy. A blog with comments, a product catalog, a reporting dashboard — lots of reads, occasional writes. PocketBase handles this comfortably.

Skip PocketBase when:

• You expect thousands of simultaneous users writing data. SQLite's single-writer limit becomes a bottleneck. Use Supabase (PostgreSQL) instead.
• You don't want to manage a server. PocketBase is self-hosted. If you want someone else to handle uptime, backups, and scaling, a managed service like Supabase is the better call.
• You need a team to collaborate on the database schema. PocketBase has no built-in migration system or team workflow. For a multi-developer team, a managed database with proper migrations is safer.
• You're building a mobile app that needs offline support. Firebase is built for this. PocketBase is not.
• You need complex SQL queries, joins, or stored procedures. PocketBase's SQLite foundation handles straightforward queries well, but if you're writing complex relational queries, PostgreSQL (via Supabase) is a better fit.

FAQ

What to Learn Next

PocketBase is a great entry point. Once you're comfortable, these are the next concepts to understand: