PocketBase — database, auth & files

PocketBase is a managed SQLite-backed backend that gives you a REST API, user auth, file storage, and realtime subscriptions — all in one. It runs as a sidecar container alongside your app.

Setup

# percher.toml
[data]
mode = "pocketbase"

# That's it. Deploy and PocketBase is ready.

Three env vars are injected automatically:

Connecting from your app

import PocketBase from 'pocketbase';

// Server-side: use internal Docker URL (no SSL overhead)
const pb = new PocketBase(process.env.POCKETBASE_URL);

// Client-side (browser): use public URL with SSL
const pb = new PocketBase(import.meta.env.VITE_POCKETBASE_URL);
// or for Next.js:
const pb = new PocketBase(process.env.NEXT_PUBLIC_POCKETBASE_URL);

CRUD operations

// Create a record
const task = await pb.collection('tasks').create({
  title: 'Buy groceries',
  done: false,
  user: pb.authStore.record?.id,
});

// List with filters
const tasks = await pb.collection('tasks').getList(1, 20, {
  filter: 'done = false',
  sort: '-created',
});

// Update
await pb.collection('tasks').update(task.id, { done: true });

// Delete
await pb.collection('tasks').delete(task.id);

Auth

// Sign up
await pb.collection('users').create({
  email: 'user@example.com',
  password: 'securepassword',
  passwordConfirm: 'securepassword',
});

// Log in
const auth = await pb.collection('users').authWithPassword(
  'user@example.com',
  'securepassword',
);
// auth.token is now set in pb.authStore

// Check auth state
if (pb.authStore.isValid) {
  console.log('Logged in as', pb.authStore.record?.email);
}

File uploads

// Upload a file
const formData = new FormData();
formData.append('title', 'My photo');
formData.append('image', fileInput.files[0]);
const record = await pb.collection('posts').create(formData);

// Get file URL
const url = pb.files.getURL(record, record.image);

Realtime subscriptions

// Subscribe to changes
pb.collection('messages').subscribe('*', (e) => {
  console.log(e.action, e.record);
  // action: 'create' | 'update' | 'delete'
});

// Unsubscribe
pb.collection('messages').unsubscribe();

Admin UI

Your PocketBase admin panel is available at pb-yourapp.percher.run/_/. Use it to create collections, set API rules, and manage data. The admin password is shown once after the first deploy — save it.