PocketBase 완벽 가이드 | 오픈소스 백엔드·SQLite·실시간·Auth·파일·실전 활용

2026년 4월 7일 · 13분 읽기 · 수정 2026년 4월 7일 초급

이 글의 핵심

PocketBase로 빠른 백엔드를 구축하는 완벽 가이드입니다. 단일 파일 실행, SQLite DB, 실시간 구독, 인증, 파일 스토리지까지 실전 예제로 정리했습니다.

실무 경험 공유: 복잡한 백엔드를 PocketBase로 전환하면서, 인프라 관리가 사라지고 개발 속도가 5배 빨라진 경험을 공유합니다.

들어가며: “백엔드 설정이 복잡해요”

실무 문제 시나리오

시나리오 1: 서버 설정이 어려워요
Express + DB 설정이 복잡합니다. PocketBase는 단일 파일로 실행됩니다.

시나리오 2: Admin 패널이 필요해요
직접 만들어야 합니다. PocketBase는 내장 Admin UI를 제공합니다.

시나리오 3: 배포가 어려워요
복잡한 인프라가 필요합니다. PocketBase는 단일 바이너리로 배포됩니다.

1. PocketBase란?

핵심 특징

PocketBase는 오픈소스 백엔드입니다.

주요 장점:

단일 파일: 실행 파일 하나
SQLite: 내장 데이터베이스
Admin UI: 내장 관리 패널
실시간: 실시간 구독
인증: 이메일, OAuth
파일 스토리지: 내장

2. 설치 및 실행

다운로드

# macOS/Linux
wget https://github.com/pocketbase/pocketbase/releases/download/v0.20.0/pocketbase_0.20.0_linux_amd64.zip
unzip pocketbase_0.20.0_linux_amd64.zip

# 실행
./pocketbase serve

Admin UI

http://localhost:8090/_/

3. JavaScript SDK

설치

npm install pocketbase

초기화

// lib/pocketbase.ts
import PocketBase from 'pocketbase';

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

4. CRUD

Create

const record = await pb.collection('posts').create({
  title: 'My First Post',
  content: 'Hello PocketBase!',
  author: userId,
});

Read

// 전체 조회
const records = await pb.collection('posts').getFullList();

// 단일 조회
const record = await pb.collection('posts').getOne(recordId);

// 필터링
const records = await pb.collection('posts').getList(1, 20, {
  filter: 'published = true',
  sort: '-created',
});

Update

const record = await pb.collection('posts').update(recordId, {
  title: 'Updated Title',
});

Delete

await pb.collection('posts').delete(recordId);

5. 인증

회원가입

const record = await pb.collection('users').create({
  email: '[email protected]',
  password: 'password123',
  passwordConfirm: 'password123',
  name: 'John',
});

OAuth

const authData = await pb.collection('users').authWithOAuth2({
  provider: 'google',
});

세션 관리

// 현재 사용자
const user = pb.authStore.model;

// 로그아웃
pb.authStore.clear();

// 세션 변경 감지
pb.authStore.onChange((token, model) => {
  console.log('Auth changed:', token, model);
});

6. 실시간 구독

// 구독
pb.collection('posts').subscribe('*', (e) => {
  console.log('Event:', e.action, e.record);
});

// 특정 레코드 구독
pb.collection('posts').subscribe(recordId, (e) => {
  console.log('Record updated:', e.record);
});

// 구독 해제
pb.collection('posts').unsubscribe();

React 예제

'use client';

import { useEffect, useState } from 'react';
import { pb } from '@/lib/pocketbase';

export default function Posts() {
  const [posts, setPosts] = useState([]);

  useEffect(() => {
    fetchPosts();

    pb.collection('posts').subscribe('*', () => {
      fetchPosts();
    });

    return () => {
      pb.collection('posts').unsubscribe();
    };
  }, []);

  async function fetchPosts() {
    const records = await pb.collection('posts').getFullList();
    setPosts(records);
  }

  return (
    <ul>
      {posts.map((post) => (
        <li key={post.id}>{post.title}</li>
      ))}
    </ul>
  );
}

7. 파일 업로드

const formData = new FormData();
formData.append('title', 'Post with Image');
formData.append('image', file);

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

// 파일 URL
const url = pb.files.getUrl(record, record.image);

8. 배포

Docker

FROM alpine:latest

RUN apk add --no-cache ca-certificates

COPY pocketbase /usr/local/bin/pocketbase

EXPOSE 8090

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

정리 및 체크리스트

핵심 요약

PocketBase: 오픈소스 백엔드
단일 파일: 실행 파일 하나
SQLite: 내장 데이터베이스
Admin UI: 내장 관리 패널
실시간: 실시간 구독
인증: 이메일, OAuth

구현 체크리스트

같이 보면 좋은 글

Supabase 완벽 가이드
Convex 완벽 가이드
SQLite 가이드

이 글에서 다루는 키워드

PocketBase, Backend, SQLite, Realtime, Auth, Open Source, Go

자주 묻는 질문 (FAQ)

Q. Supabase와 비교하면 어떤가요?

A. PocketBase가 더 간단하고 셀프 호스팅이 쉽습니다. Supabase는 PostgreSQL 기반으로 더 강력합니다.

Q. 프로덕션에서 사용해도 되나요?

A. 네, 소규모 프로젝트에 적합합니다. 대규모는 PostgreSQL 기반을 권장합니다.

Q. 무료인가요?

A. 네, 완전히 오픈소스이고 무료입니다.

Q. 확장성은 어떤가요?

A. SQLite 기반이라 단일 서버에 적합합니다. 대규모는 Supabase를 권장합니다.