PocketBase: полное руководство по open-source backend в одном файле

PocketBase — это открытый backend-as-a-service, который умещается в одном исполняемом файле весом ~12 MB. Внутри: SQLite-база данных, REST API, аутентификация пользователей, файловое хранилище и административный UI — всё готово к работе через минуту после скачивания. В 2026 году PocketBase стал стандартным выбором для MVP, стартапов и indie-разработчиков, которым нужен backend без сложной настройки.

Что такое PocketBase и зачем он нужен

PocketBase — open-source проект, написанный на Go. Его ключевые принципы:

Один бинарный файл без внешних зависимостей
Встроенная SQLite база данных
REST API с автоматической генерацией по схеме коллекций
Встроенная аутентификация (email/password, OAuth2, OTP)
Административный UI по адресу /_/
Расширение кастомной логикой на Go или JavaScript

PocketBase занял уникальную нишу: функционально близок к Supabase, но развёртывается как один файл без Docker, без PostgreSQL, без Kubernetes. Для проектов, где Supabase избыточен, а самописный бэкенд — трудоёмок, PocketBase — идеальное решение.

Версия на момент написания: 0.37.5 (май 2026). PocketBase ещё не достиг v1.0.0 — разработчики предупреждают, что API может меняться между версиями.

Установка PocketBase за 5 минут

Скачать и запустить локально

# Linux / macOS
wget https://github.com/pocketbase/pocketbase/releases/download/v0.37.5/pocketbase_0.37.5_linux_amd64.zip
unzip pocketbase_0.37.5_linux_amd64.zip
chmod +x pocketbase
./pocketbase serve

# Windows
# Скачайте pocketbase_0.37.5_windows_amd64.zip с GitHub Releases
# Распакуйте и запустите pocketbase.exe serve

После запуска в терминале появится ссылка для первоначальной настройки:

Server started at http://127.0.0.1:8090
├─ REST API: http://127.0.0.1:8090/api/
└─ Admin UI: http://127.0.0.1:8090/_/

Перейдите по ссылке, создайте аккаунт superuser — и PocketBase готов к работе.

Что создаётся автоматически:

./
├── pocketbase          # исполняемый файл
├── pb_data/            # данные (БД, файлы, логи)
│   ├── data.db         # SQLite база данных
│   ├── auxiliary.db    # вспомогательные данные
│   └── storage/        # загруженные файлы
└── pb_migrations/      # файлы миграций

Запуск через Docker

# Dockerfile
FROM alpine:latest

ARG PB_VERSION=0.37.5

RUN apk add --no-cache unzip ca-certificates && \
    wget https://github.com/pocketbase/pocketbase/releases/download/v${PB_VERSION}/pocketbase_${PB_VERSION}_linux_amd64.zip && \
    unzip pocketbase_${PB_VERSION}_linux_amd64.zip && \
    rm pocketbase_${PB_VERSION}_linux_amd64.zip

EXPOSE 8090

CMD ["/pocketbase", "serve", "--http=0.0.0.0:8090"]

# docker-compose.yml
version: '3.8'
services:
  pocketbase:
    build: .
    ports:
      - "8090:8090"
    volumes:
      - ./pb_data:/pb_data
      - ./pb_migrations:/pb_migrations
    restart: unless-stopped

Создание коллекций

Коллекции в PocketBase — это таблицы базы данных с автоматически генерируемым API. Создаются через UI или через REST API.

Создание коллекции через UI

Откройте http://localhost:8090/_/
Нажмите «New collection»
Укажите название (например, posts)
Добавьте поля:
- title — type: Text, required: true
- content — type: Editor (rich text)
- author — type: Relation → users
- cover_image — type: File, Max files: 1
- tags — type: Text, Max: 5 (для массива через Select)
- published — type: Bool, default: false
Сохраните

После создания коллекции PocketBase автоматически генерирует REST API:

GET    /api/collections/posts/records      — список записей
POST   /api/collections/posts/records      — создать запись
GET    /api/collections/posts/records/:id  — одна запись
PATCH  /api/collections/posts/records/:id  — обновить
DELETE /api/collections/posts/records/:id  — удалить

Типы полей PocketBase

| Тип | Описание | Пример | |---|---|---| | Text | Строка | Заголовок, имя | | Number | Число | Цена, количество | | Bool | Boolean | Опубликован да/нет | | Email | Email с валидацией | user@example.com | | URL | URL с валидацией | https://example.com | | Date | Дата и время | 2026-05-01 | | Select | Выбор из вариантов | status: draft/published | | File | Файл/изображение | Обложка, аватар | | Relation | Связь с другой коллекцией | author → users | | Editor | Rich text (HTML) | Контент статьи | | JSON | Произвольный JSON | Настройки, метаданные |

Аутентификация в PocketBase

PocketBase предоставляет готовую аутентификацию из коробки.

Встроенные пользователи (коллекция users)

PocketBase создаёт базовую коллекцию users при первом запуске. Поддерживаемые методы:

Email + Password
OAuth2 (Google, GitHub, Facebook, Apple, Twitter, Discord, GitLab, Spotify и другие)
OTP через email

Регистрация и вход через JavaScript SDK

import PocketBase from 'pocketbase';

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

// Регистрация
const user = await pb.collection('users').create({
    email: 'alex@example.com',
    password: 'securepassword123',
    passwordConfirm: 'securepassword123',
    name: 'Алексей'
});

// Вход по email/password
const authData = await pb.collection('users').authWithPassword(
    'alex@example.com',
    'securepassword123'
);

// pb.authStore.model — текущий пользователь
// pb.authStore.token — JWT-токен (автоматически добавляется в заголовки)
console.log(pb.authStore.model); // { id, email, name, ... }

// OAuth2 вход через Google
const authData = await pb.collection('users').authWithOAuth2({ 
    provider: 'google' 
});

// Обновление профиля
await pb.collection('users').update(pb.authStore.model.id, {
    name: 'Алексей Иванов',
    avatar: fileObject // File объект
});

// Выход
pb.authStore.clear();

API Rules — управление доступом

PocketBase контролирует доступ через API Rules — выражения фильтрации, которые определяют, кто может читать, создавать, обновлять и удалять записи.

# Примеры API Rules

# Список постов: публичный (видят все)
listRule: ""

# Просмотр поста: только опубликованные для публики, все для авторов
viewRule: published = true || author = @request.auth.id

# Создание: только авторизованные
createRule: @request.auth.id != ""

# Обновление: только автор своих записей
updateRule: @request.auth.id = author

# Удаление: только автор
deleteRule: @request.auth.id = author

@request.auth.id — ID текущего авторизованного пользователя. Эта система аналогична Row-Level Security в PostgreSQL, но настраивается через UI без SQL.

Работа с файлами

PocketBase поддерживает загрузку файлов и изображений из коробки:

// Создание записи с файлом
const formData = new FormData();
formData.append('title', 'Моя статья');
formData.append('cover_image', fileInput.files[0]);

const record = await pb.collection('posts').create(formData);

// URL файла
const imageUrl = pb.files.getURL(record, record.cover_image);
// Возвращает: http://localhost:8090/api/files/posts/RECORD_ID/IMAGE_NAME.jpg

// URL миниатюры (100x100)
const thumbUrl = pb.files.getURL(record, record.cover_image, { thumb: '100x100' });

PocketBase автоматически генерирует миниатюры изображений с произвольными размерами. Файлы хранятся в pb_data/storage/.

Realtime-подписки

PocketBase поддерживает realtime-обновления через Server-Sent Events:

// Подписка на изменения в коллекции
pb.collection('messages').subscribe('*', (e) => {
    console.log(e.action); // "create" | "update" | "delete"
    console.log(e.record); // изменённая запись
    
    if (e.action === 'create') {
        addMessageToUI(e.record);
    }
});

// Подписка на конкретную запись
pb.collection('orders').subscribe('ORDER_ID', (e) => {
    updateOrderStatus(e.record.status);
});

// Отписка
pb.collection('messages').unsubscribe();

JavaScript SDK: работа с коллекциями

import PocketBase from 'pocketbase';
const pb = new PocketBase('https://your-pocketbase.com');

// Список записей с фильтрацией, сортировкой, пагинацией
const posts = await pb.collection('posts').getList(1, 20, {
    filter: 'published = true && created >= "2026-01-01"',
    sort: '-created',
    expand: 'author',
    fields: 'id,title,created,expand.author.name'
});

// posts.items — массив записей
// posts.totalItems — всего записей
// posts.totalPages — всего страниц

// Все записи сразу (без пагинации)
const allTags = await pb.collection('tags').getFullList({
    sort: 'name'
});

// Одна запись
const post = await pb.collection('posts').getOne('RECORD_ID', {
    expand: 'author,tags'
});

// Первая запись по фильтру
const latestPost = await pb.collection('posts').getFirstListItem(
    'published = true',
    { sort: '-created' }
);

// Создание
const newPost = await pb.collection('posts').create({
    title: 'Новая статья',
    content: '<p>Содержимое</p>',
    author: pb.authStore.model.id,
    published: false
});

// Обновление
const updated = await pb.collection('posts').update('RECORD_ID', {
    published: true
});

// Удаление
await pb.collection('posts').delete('RECORD_ID');

Расширение PocketBase кастомной логикой

PocketBase поддерживает хуки и кастомные роуты через JavaScript (встроенный JSVM на goja) или Go.

// pb_hooks/main.pb.js

// Хук перед созданием записи
onRecordCreateRequest((e) => {
    // Устанавливаем автора автоматически
    e.record.set('author', e.requestInfo().auth.id);
    e.next();
}, 'posts');

// Хук после создания — отправить email
onRecordAfterCreateSuccess((e) => {
    const user = e.record.expandedOne('author');
    const mailer = $app.newMailClient();
    
    mailer.send({
        to: [{ address: user.email() }],
        subject: 'Статья опубликована',
        html: `<p>Ваша статья "${e.record.getString('title')}" создана.</p>`
    });
}, 'posts');

// Кастомный API-роут
routerAdd('POST', '/api/custom/send-notification', (e) => {
    const data = e.requestInfo().body;
    
    // Кастомная логика
    return e.json(200, { status: 'sent' });
});

Деплой PocketBase на VPS

Деплой на Ubuntu/Debian сервер

# 1. Скачать PocketBase
wget https://github.com/pocketbase/pocketbase/releases/download/v0.37.5/pocketbase_0.37.5_linux_amd64.zip
unzip pocketbase_0.37.5_linux_amd64.zip -d /opt/pocketbase
chmod +x /opt/pocketbase/pocketbase

# 2. Создать systemd сервис
cat > /etc/systemd/system/pocketbase.service << 'EOF'
[Unit]
Description=PocketBase Service
After=network.target

[Service]
Type=simple
User=www-data
WorkingDirectory=/opt/pocketbase
ExecStart=/opt/pocketbase/pocketbase serve --http=127.0.0.1:8090
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF

# 3. Включить и запустить
systemctl enable pocketbase
systemctl start pocketbase

# 4. Настроить Nginx реверс-прокси
cat > /etc/nginx/sites-available/pocketbase << 'EOF'
server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://127.0.0.1:8090;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }
}
EOF

ln -s /etc/nginx/sites-available/pocketbase /etc/nginx/sites-enabled/
systemctl reload nginx

# 5. SSL через Certbot
certbot --nginx -d your-domain.com

Деплой через Coolify (рекомендуется)

Если у вас уже установлен Coolify на VPS, деплой PocketBase ещё проще:

Создайте новый сервис → Docker Image
Укажите образ: ghcr.io/muchobello/pocketbase:latest
Добавьте volume: /pb_data
Укажите порт: 8090
Настройте домен → SSL автоматически

Автоматический бэкап PocketBase

SQLite база PocketBase — это один файл pb_data/data.db. Критически важно настроить автоматические бэкапы, особенно в production.

Встроенные бэкапы PocketBase (через UI): Administration → Backups. PocketBase умеет создавать резервные копии вручную или по расписанию через dashboard. Но для надёжного production-решения рекомендуется внешний бэкап.

dbsend.ru — сервис автоматических бэкапов баз данных с поддержкой SQLite. Настройка занимает 5 минут:

# Установка dbsend CLI
curl -sSL https://dbsend.ru/install.sh | bash

# Настройка бэкапа PocketBase
dbsend backup \
  --db=sqlite:///opt/pocketbase/pb_data/data.db \
  --destination=s3://my-bucket/pocketbase \
  --schedule="*/30 * * * *" \
  --keep=100

# Бэкап всей директории pb_data (включая файлы)
dbsend backup \
  --path=/opt/pocketbase/pb_data \
  --destination=s3://my-bucket/pocketbase-files \
  --schedule=daily

dbsend.ru хранит бэкапы с версионированием: вы можете восстановить данные на любой момент времени за последние N дней. Это защищает от случайного удаления данных — частой проблемы при разработке.

PocketBase vs Supabase vs Firebase: когда что выбрать

| Параметр | PocketBase | Supabase | Firebase | |---|---|---|---| | База данных | SQLite | PostgreSQL | Firestore (NoSQL) | | Деплой | Один файл | Docker или Cloud | Только Cloud | | Self-hosted | Легко | Сложнее | Нет | | Масштабируемость | Ограниченная (SQLite) | Высокая | Высокая | | Бесплатный тариф | Полностью бесплатный (self-host) | Ограниченный cloud | Щедрый | | Аутентификация | Встроенная | Встроенная | Встроенная | | Realtime | SSE | WebSocket | Нативный | | SDK | JS, Dart | JS, Dart, Python, Swift и др. | iOS, Android, Web | | Платежи | Нет (self-host) | Иностранная карта | Иностранная карта | | Данные в России | Да (self-host на российском VPS) | Нет (cloud) / Да (self-host) | Нет |

Используйте PocketBase если:

MVP или прототип, нужно запустить быстро
Один сервер, предсказуемая нагрузка
Нет опыта с PostgreSQL
Хотите self-hosted backend за ~500 ₽/мес
Разрабатываете с вайбкодингом (AI хорошо знает PocketBase)

Используйте Supabase если:

Нужен PostgreSQL с полноценным SQL
Команда знает PostgreSQL и RLS
Планируете горизонтальное масштабирование
Нужен GraphQL или богатый SQL-API

Используйте Firebase если:

Мобильное приложение iOS/Android (зрелые SDK)
Нужна глубокая интеграция с Google Analytics, Crashlytics
Реалтайм — главная функция приложения

Ограничения PocketBase

Честный разговор о минусах:

SQLite не масштабируется горизонтально. При нагрузке свыше 50,000-100,000 запросов в день или базе данных более 50 GB нужно мигрировать на PostgreSQL (Supabase или self-hosted).

Нет встроенных очередей задач. Для фоновых задач (email-рассылки, обработка изображений) нужно добавлять внешнее решение (BullMQ, pg-boss, Temporal).

API ещё не v1.0. PocketBase предупреждает, что до v1.0 возможны breaking changes при обновлениях. Читайте changelog перед каждым обновлением.

Кастомная логика на JavaScript имеет ограничения. Встроенный JSVM (goja) — не полноценный Node.js. Некоторые npm-пакеты не работают. Для сложной логики нужно расширять на Go.

Нет встроенного full-text поиска на русском языке. Для поиска по русскоязычному контенту нужно добавить Meilisearch или Elasticsearch.

FAQ

Подходит ли PocketBase для production?

PocketBase используется в production тысячами проектов, но официально предупреждает о возможных breaking changes до v1.0.0. Для некритичных приложений (инструменты, внутренние сервисы, MVP) — отличный выбор. Для высоконагруженных или mission-critical систем рекомендуется подождать v1.0.0 или выбрать PostgreSQL-based альтернативы.

Как обновлять PocketBase без потери данных?

Скачайте новую версию бинарного файла, замените старый. Данные в pb_data/ сохраняются. PocketBase запускает необходимые миграции автоматически при старте. Перед обновлением всегда создавайте бэкап pb_data/data.db.

Можно ли использовать PocketBase как фреймворк для Go?

Да. PocketBase можно встроить в собственное Go-приложение как библиотеку, добавив кастомные роуты, хуки и логику. Это позволяет использовать весь функционал PocketBase, сохранив полный контроль над приложением.

Как подключить PocketBase к React/Next.js?

Установите SDK: npm install pocketbase. Создайте singleton клиент в отдельном файле (lib/pocketbase.ts) и импортируйте его в компоненты. Для Next.js с SSR используйте PocketBase на серверной стороне для запросов во время render, клиентскую аутентификацию — через client components.

Поддерживает ли PocketBase загрузку видео?

Да, поле File поддерживает любые типы файлов включая видео. По умолчанию максимальный размер файла — 5 MB, но это настраивается через параметр запуска --maxRequestBodySize. Для больших файлов рекомендуется внешнее S3-хранилище (Selectel Object Storage, Яндекс Object Storage).

Как работает расширение PocketBase на JavaScript?

Файлы с расширением .pb.js помещаются в директорию pb_hooks/. PocketBase загружает их при старте. Доступны глобальные объекты: $app (основной экземпляр PocketBase), функции хуков (onRecordCreateRequest, onRecordAfterCreateSuccess и другие), routerAdd для кастомных роутов. JavaScript выполняется через goja — встроенный интерпретатор, совместимый с ES2015+.

Как настроить бэкап PocketBase автоматически?

Три варианта: 1) Встроенные бэкапы через Admin UI (Administration → Backups → Schedule) — простейший способ, хранит в pb_data/backups/. 2) cron-скрипт для копирования pb_data/data.db в S3 через aws cli или s3cmd. 3) dbsend.ru — автоматический бэкап SQLite в облако с версионированием, уведомлениями и восстановлением. Рекомендую третий вариант для production: автоматизирован, надёжен, восстановление за один клик.