PocketBase

PocketBase가 실제로 무엇인가

대부분의 백엔드는 조립 작업이다. 어딘가에 데이터베이스, 그 옆에 인증 서비스, 업로드용 오브젝트 스토리지, 늘 만들려고만 하는 작은 관리 화면, 그리고 그 사이를 잇는 접착제. PocketBase는 이것을 프로세스 하나와 디스크의 파일 하나로 줄인다. 자기 플랫폼용 실행 파일을 내려받아 실행하고, 브라우저로 대시보드를 열어 컬렉션을 정의하면 그 순간 앱에 API가 생긴다. 컨테이너 오케스트레이션도, 관리형 데이터베이스도, 별도의 인증 업체도 없고, 첫 요청이 통하기 전에 설정해야 할 것도 없다

맞바꾸는 것은 눈에 보이고 의도된 것이다. 데이터베이스가 네트워크 너머가 아니라 내장이기 때문에 백엔드 전체가 SQLite 파일 하나를 쥔 프로세스 하나가 된다. 운영이 이렇게까지 단순한 이유가 바로 그것이고, 수평 확장이 다른 구성과는 다른 논의가 되는 이유도 그것이다. 이 글을 읽는 대부분이 서 있는 단계, 즉 아직 사용자가 없는 앱이거나 수백 명 규모의 앱이라면 이 거래는 확실히 당신 쪽에 유리하고, 사람들이 예상하는 것보다 훨씬 오래 그 상태로 남는다

• 실시간 구독을 갖춘 내장 데이터베이스 바이너리 안에 SQLite가 있고, 여기에 구독 API가 더해져 클라이언트가 계속 물어보는 대신 변경이 일어나는 대로 받아 본다. 저절로 갱신되는 화면이 프로젝트가 아니라 기본값이 된다
• 사용자와 파일이 처음부터 들어 있다 인증과 사용자 관리가 함께 오고 파일 처리도 마찬가지다. 첫날부터 외부 서비스를 끌어들이게 만드는 두 가지 기능이 이미 거기 있다
• 관리 대시보드와 REST에 가까운 API 컬렉션을 정의하고 레코드를 고치고 데이터를 살펴보는 웹 UI가 있고, 그 아래에 공식 SDK가 감싸는 HTTP API가 있다. 자바스크립트 SDK는 브라우저와 Node.js, React Native를 아우르고, 플러터와 데스크톱을 위한 Dart SDK가 따로 있다
• 이식 가능한 실행 파일 하나 배포되는 바이너리는 순수 Go로 작성된 SQLite 드라이버를 쓰고 CGO를 끈 채 빌드되므로, 공개된 리눅스, macOS, 윈도우, FreeBSD, OpenBSD, NetBSD 대상 목록으로 교차 컴파일된다. 배포는 파일 하나를 복사해 실행하는 일이다

돌리는 방법이 두 가지이고, 그 선택은 나중에 효과를 낸다

첫째는 독립 실행 앱으로 쓰는 방법이다. 자기 플랫폼용 릴리스를 받아 풀고 serve 명령을 실행하면 끝이다. 배포 바이너리에는 자바스크립트 VM도 들어 있어서 Go를 건드리거나 다시 빌드하지 않고도 훅과 자체 엔드포인트를 자바스크립트로 붙일 수 있다. 오늘 오후 안에 시제품을 누군가 앞에 내놓는 길이 이쪽이고, 여기에 계속 머무는 것도 충분히 합리적인 선택이다

둘째는 Go 라이브러리로 쓰는 방법이다. 자기 Go 프로그램에 PocketBase를 가져와 그 생명주기 이벤트에 라우트와 업무 로직을 등록하고, 그 결과물을, 즉 자기 코드와 백엔드 전체를 정적으로 링크된 실행 파일 하나로 컴파일한다. README에 실린 최소 예제는 열다섯 줄 남짓이다. 이걸 첫날에 알아 두어야 하는 이유는 이것이 비상구이기 때문이다. 로직이 설정으로 감당할 범위를 넘어서도 독립 실행 앱이 벽이 되지 않는 것은, 같은 프로젝트가 그 아래의 프레임워크이기도 하기 때문이다. 요구 사항은 소박해서 빌드에는 현재 Go 1.27 이상이 필요하다

창업자의 성장 스택에서 어디에 놓이는가

PocketBase는 만드는 도구이지 성장시키는 도구가 아니다. 그러니 성장에 대한 기여는 간접적이고, 그 점은 정직하게 말해 두는 편이 낫다. 아이디어를 떠올린 시점과 낯선 사람이 로그인할 수 있는 무언가가 존재하는 시점 사이의 몇 주를 없애 준다. 그게 중요한 이유는 수요에 대해 배울 수 있는 것 대부분이 그 지점을 넘기 전에는 손에 들어오지 않기 때문이다. 반대로 이것이 하지 않는 일은, 당신이 만든 것에 누군가를 데려오는 일이다

• 처음 돌아가는 버전을 위해 인증과 저장소와 데이터베이스가 내려받기 한 번으로 갖춰지는 것은, 시제품에서 진짜 로그인을 앞에 둘 수 있는 무언가로 가는 가장 짧고 정직한 길이다. 프런트를 AI 도구로 만들고 있다면, 만들기가 끝나는 지점부터는 바이브 코딩으로 만든 앱을 알리는 가장 좋은 방법이 이어받는다
• 돈 내고 쓰기는 아까운 내부 도구를 위해 대기자 명단, 콘텐츠 캘린더, 아웃리치 관리, 첫 쉰 번의 대화를 담을 가벼운 고객 관리. 컬렉션에 관리 UI만 더해도 유지해야 할 제품이 되지 않은 채 꽤 넓은 범위를 감당한다
• 성장 계층을 대신하는 것이 아니라 그 옆에 여기 있는 어떤 것도 포지셔닝을 써 주지 않고, 무언가를 공개하지도 않으며, 고객에게 답하지도 않는다. 제품이 존재하는 순간 일의 형태가 통째로 바뀐다. 다음 문제는 첫 100명의 사용자를 어떻게 모으나이고, 그쪽이 더 어렵다
• 무엇을 들이는지 알고 들이기 라이선스는 MIT이고 README는 그 위에 만든 서비스를 파는 것까지 포함해 상업적 이용을 명시적으로 허용한다. 동시에 1.0 이전이라 호환성을 깨는 변경이 예상되고, 질 낮은 자동 제출이 몰린 탓에 저장소는 풀 리퀘스트를 기존 협력자에게만 한시적으로 열어 두고 있다. 패치보다는 이슈를 올릴 생각으로 접근하는 편이 좋다

SQLite를 프로덕션에서 돌리며 배운 것

여기서 우리는 중립이 아니고, 바로 그 점이 쓸모 있는 부분이다. AgentCeres도 프로덕션에서 SQLite를 쓰고 있으니 아래 이야기는 바깥에서 쓴 리뷰가 아니라 우리가 내린 결정에 관한 것이다. 파일 하나짜리 백엔드가 바꾸는 가장 중요한 사실은, 그 파일이 어디에 사는지가 곧 아키텍처 전체가 된다는 점이다. 우리 파일은 마운트된 볼륨 위에 있었고, 거듭 마주친 실패는 컨테이너가 쓴 것 가운데 아무도 영속 저장소로 밀어 넣지 않은 것은 다음 배포를 그냥 넘기지 못한다는 것이었다. 게다가 그건 오류로 스스로를 알리지도 않는다. 무언가를 조용히 잊어버린 앱의 모습으로 나타나는데, 데이터 손실이 도착하는 방식 가운데 가장 나쁜 형태다

두 번째 놀라움은 희소한 자원이 디스크 용량이 아니라 볼륨 그 자체였다는 점이다. 우리 호스팅 업체는 프로젝트당 볼륨 개수에 상한을 두는데, 어떤 용량 한계보다도 훨씬 먼저 그 천장에 닿았고 결국 재설계로 이어졌다. 컨테이너는 일회용이 되었고 영속 상태는 그것들보다 오래 사는 데이터베이스와 오브젝트 스토리지로 옮겨 갔다. 제품 하나를 위해 PocketBase 하나를 돌린다면 이 이야기가 당신에게 닿을 일은 없다. 고객마다 하나씩 두고 싶어지는 자신을 발견했다면, 그것을 전제로 설계하기 전에 볼륨 개수부터 세어 보라

세 번째는 SQLite에만 해당하는 이야기이고, 우리는 정말로 혼란스러운 오후 하나를 잃었다. SQLite의 타입은 유연하다. 우리는 타임스탬프를 어떤 열에는 정수로, 다른 열에는 텍스트로 저장하고 있었는데, 이 두 형식을 가로지르는 비교는 오류를 전혀 내지 않는다. 그저 조용히 틀린 행을 돌려준다. 읽어 보면 멀쩡해 보이는 질의 그대로. PocketBase는 자기 스키마를 스스로 관리하므로, 같은 파일을 향해 직접 질의를 쓰거나 Go 확장을 쓰기 시작하기 전까지는 이 문제에서 꽤 보호받는다. 그리고 그 순간부터 이것은 당신의 문제가 된다. 저장 형식은 한 번 정하고, 비교를 믿기 전에 열의 타입을 확인하라