shield_lock
金大哥
← 返回 Skill 列表
extension
分类: 开发与工程无需 API Key

pocketbase-collection-operation

通过PocketBase Web API安全地查询、修改和删除集合（list/view/create/update/delete/truncate/import/scaffolds）

person作者: jakexiaohubgithub
open_in_new仓库download下载资源包

PocketBase Collections Web API

PocketBase의 Collections(Web API) 엔드포인트를 사용해 컬렉션을 조회/생성/수정/삭제/비우기/일괄 가져오기/스캐폴드 조회한다.

언제 사용하나요?

  • PocketBase의 컬렉션(스키마) 자체를 코드/스크립트로 관리해야 할 때
  • CI/CD, 마이그레이션, 개발 환경 초기화에서 컬렉션 구성 자동화가 필요할 때
  • Dashboard UI가 아닌 HTTP API 호출로 컬렉션 조작이 필요할 때

공통 제약/필요 조건

1) 연결 정보(필수)

다음 값이 필요하다.

  • PB_URL: PocketBase 서버의 base URL
    예: http://127.0.0.1:8090 또는 https://pb.example.com
  • PB_ADMIN_EMAIL: superuser 이메일
  • PB_ADMIN_PASSWORD: superuser 비밀번호

입력 우선순위

  1. 사용자가 명시적으로 제공한 값/환경변수 이름
  2. 기본 환경변수(PB_URL, PB_ADMIN_EMAIL, PB_ADMIN_PASSWORD)
  3. 둘 다 없으면: 아래 환경변수 목록과 설정 방법을 사용자에게 안내하고, 값이 준비되면 다시 진행한다.

환경변수 설정 예시

export PB_URL="http://127.0.0.1:8090"
export PB_ADMIN_EMAIL="admin@example.com"
export PB_ADMIN_PASSWORD="your-password"

2) 인증(필수)

Collections API는 superuser 토큰이 필요하다. 토큰 발급은 _superusers auth 컬렉션의 auth-with-password를 사용한다.

토큰 발급

  • POST ${PB_URL}/api/collections/_superusers/auth-with-password
  • Body(JSON): 
    {
  "identity": "admin@example.com",
  "password": "your-password"
}
  • Response(JSON): 
    {
  "token": "JWT_TOKEN_STRING",
  "record": { "...": "..." }
}

이후 모든 요청 헤더

  • Authorization: <token>
  • Content-Type: application/json (JSON 바디를 보낼 때)

PocketBase는 Authorization: Bearer <token> 형태가 아니라, Authorization: <token> 형태를 사용한다.

토큰 발급 bash 예시 (jq 사용)

PB_TOKEN="$(
  curl -sS -X POST "${PB_URL}/api/collections/_superusers/auth-with-password" \
    -H "Content-Type: application/json" \
    -d "{\"identity\":\"${PB_ADMIN_EMAIL}\",\"password\":\"${PB_ADMIN_PASSWORD}\"}" \
  | jq -r .token
)"

jq가 없다면 (python 사용)

PB_TOKEN="$(
  curl -sS -X POST "${PB_URL}/api/collections/_superusers/auth-with-password" \
    -H "Content-Type: application/json" \
    -d "{\"identity\":\"${PB_ADMIN_EMAIL}\",\"password\":\"${PB_ADMIN_PASSWORD}\"}" \
  | python -c 'import sys,json; print(json.load(sys.stdin)["token"])'
)"

3) 공통 요청 규칙

  • Base path는 항상 ${PB_URL}/api/...
  • 일부 엔드포인트는 request body를 multipart/form-data로도 보낼 수 있으나, 기본은 JSON을 사용한다.
  • collectionIdOrName에는 컬렉션 ID 또는 name을 넣을 수 있다.
  • 401이 나오면 토큰이 누락/만료/오류일 수 있으니 재인증 후 재시도한다.
  • 403이 나오면 superuser가 아니거나 권한이 없다(대부분 collections 조작은 superuser 전용).

4) 파괴적 작업 가드레일(권장)

아래 작업은 되돌리기 어렵다. 사용자가 명시적으로 요청한 경우에만 실행한다.

  • DELETE /api/collections/{collectionIdOrName} (컬렉션 삭제)
  • DELETE /api/collections/{collectionIdOrName}/truncate (레코드 전체 삭제)
  • PUT /api/collections/import 중 deleteMissing=true (누락된 컬렉션/필드/데이터 삭제 가능)

API 레퍼런스: Collections

아래 모든 요청은 기본적으로 다음 헤더를 사용한다.

Authorization: <PB_TOKEN>
Content-Type: application/json

A) List collections

  • GET /api/collections
  • Query:
    • page (number, default 1)
    • perPage (number, default 30)
    • sort (string, 예: -created,id)
    • filter (string, 예: (name~'abc' && created>'2022-01-01'))
    • fields (string, 반환 필드 선택)
    • skipTotal (boolean, total 계산 생략)
  • Response 200(JSON): PageResult<Collection> 
    {
  "page": 1,
  "perPage": 30,
  "totalItems": 123,
  "totalPages": 5,
  "items": [ { "id": "...", "name": "...", "type": "...", "fields": [ ... ] } ]
}
  • curl 예시 
    curl -sS "${PB_URL}/api/collections?page=1&perPage=50&sort=-created" \
  -H "Authorization: ${PB_TOKEN}"

B) View collection

  • GET /api/collections/{collectionIdOrName}
  • Query:
    • fields (string)
  • Response 200(JSON): Collection 
    {
  "id": "COLLECTION_ID",
  "name": "posts",
  "type": "base",
  "system": false,
  "listRule": null,
  "viewRule": null,
  "createRule": null,
  "updateRule": null,
  "deleteRule": null,
  "fields": [ { "name": "title", "type": "text" } ],
  "indexes": []
}
  • curl 예시 
    curl -sS "${PB_URL}/api/collections/posts" \
  -H "Authorization: ${PB_TOKEN}"

C) Create collection

  • POST /api/collections
  • Body: CollectionCreate

CollectionCreate (요약 스키마)

{
  "id": "optional_15_chars",
  "name": "required_unique_name",
  "type": "base | view | auth",             // default: base
  "fields": [ /* Array<Field> */ ],         // view는 viewQuery 기반 자동 채움(보통 생략 가능)
  "indexes": [ "CREATE INDEX ..." ],        // view는 indexes 미지원
  "system": false,

  "listRule": null,
  "viewRule": null,
  "createRule": null,
  "updateRule": null,
  "deleteRule": null,

  // type=view 일 때 필수
  "viewQuery": "SELECT ...",

  // type=auth 일 때 주로 사용
  "manageRule": null,
  "authRule": null,
  "authAlert": { "enabled": true, "emailTemplate": { "subject": "...", "body": "..." } },
  "oauth2": { "enabled": false, "providers": [], "mappedFields": { "id": "", "name": "", "username": "", "avatarURL": "" } },
  "passwordAuth": { "enabled": true, "identityFields": ["email"] },
  "mfa": { "enabled": false, "duration": 1800, "rule": "" },
  "otp": { "enabled": false, "duration": 180, "length": 8, "emailTemplate": { "subject": "...", "body": "..." } }
}
  • Response 200(JSON): Collection

curl 예시 (base)

curl -sS -X POST "${PB_URL}/api/collections" \
  -H "Authorization: ${PB_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "exampleBase",
    "type": "base",
    "fields": [
      { "name": "title", "type": "text", "required": true, "min": 1 },
      { "name": "status", "type": "bool" }
    ]
  }'

curl 예시 (view)

curl -sS -X POST "${PB_URL}/api/collections" \
  -H "Authorization: ${PB_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "exampleView",
    "type": "view",
    "listRule": "@request.auth.id != \"\"",
    "viewRule": null,
    "viewQuery": "SELECT id, name FROM posts"
  }'

curl 예시 (auth)

curl -sS -X POST "${PB_URL}/api/collections" \
  -H "Authorization: ${PB_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "exampleAuth",
    "type": "auth",
    "createRule": "id = @request.auth.id",
    "updateRule": "id = @request.auth.id",
    "deleteRule": "id = @request.auth.id",
    "fields": [
      { "name": "name", "type": "text" }
    ],
    "passwordAuth": { "enabled": true, "identityFields": ["email"] }
  }'

D) Update collection

  • PATCH /api/collections/{collectionIdOrName}
  • Body: CollectionUpdate (부분 업데이트)

CollectionUpdate (요약)

{
  "name": "required",
  "fields": [ /* Array<Field> */ ],
  "indexes": [ "CREATE INDEX ..." ],
  "system": false,

  "listRule": null,
  "viewRule": null,
  "createRule": null,
  "updateRule": null,
  "deleteRule": null,

  "viewQuery": "SELECT ...",

  "manageRule": null,
  "authRule": null,
  "authAlert": { "enabled": true, "emailTemplate": { "subject": "...", "body": "..." } },
  "oauth2": { "enabled": false, "providers": [], "mappedFields": { "id": "", "name": "", "username": "", "avatarURL": "" } },
  "passwordAuth": { "enabled": true, "identityFields": ["email"] },
  "mfa": { "enabled": false, "duration": 1800, "rule": "" },
  "otp": { "enabled": false, "duration": 180, "length": 8, "emailTemplate": { "subject": "...", "body": "..." } }
}
  • Response 200(JSON): Collection
  • curl 예시 
    curl -sS -X PATCH "${PB_URL}/api/collections/demo" \
  -H "Authorization: ${PB_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "new_demo",
    "listRule": "created > \"2022-01-01 00:00:00\""
  }'

E) Delete collection

  • DELETE /api/collections/{collectionIdOrName}
  • Response 204: null
  • curl 예시 
    curl -sS -X DELETE "${PB_URL}/api/collections/demo" \
  -H "Authorization: ${PB_TOKEN}" \
  -o /dev/null -w "%{http_code}\n"

F) Truncate collection (records 전체 삭제)

  • DELETE /api/collections/{collectionIdOrName}/truncate
  • Response 204: null
  • curl 예시 
    curl -sS -X DELETE "${PB_URL}/api/collections/demo/truncate" \
  -H "Authorization: ${PB_TOKEN}" \
  -o /dev/null -w "%{http_code}\n"

G) Import collections (bulk)

  • PUT /api/collections/import
  • Body(JSON): 
    {
  "collections": [ /* Array<Collection> */ ],
  "deleteMissing": false
}
  • Response 204: null

deleteMissing=true는 "import에 없는 기존 컬렉션/필드"를 삭제할 수 있고, 관련 레코드 데이터도 삭제될 수 있으니 주의.

  • curl 예시 
    curl -sS -X PUT "${PB_URL}/api/collections/import" \
  -H "Authorization: ${PB_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "collections": [
      {
        "name": "collection1",
        "type": "base",
        "fields": [ { "name": "status", "type": "bool" } ]
      },
      {
        "name": "collection2",
        "type": "base",
        "fields": [ { "name": "title", "type": "text" } ]
      }
    ],
    "deleteMissing": false
  }' \
  -o /dev/null -w "%{http_code}\n"

H) Scaffolds (기본 컬렉션 템플릿 조회)

  • GET /api/collections/meta/scaffolds
  • Response 200(JSON): Scaffolds 
    {
  "auth": { "type": "auth", "fields": [ /* default fields */ ], "...": "..." },
  "base": { "type": "base", "fields": [ /* default fields */ ], "...": "..." },
  "view": { "type": "view", "fields": [ /* empty by default */ ], "viewQuery": "" }
}
  • curl 예시 
    curl -sS "${PB_URL}/api/collections/meta/scaffolds" \
  -H "Authorization: ${PB_TOKEN}"

권장 실행 순서(워크플로우)

  1. 입력 확인: PB_URL, PB_ADMIN_EMAIL, PB_ADMIN_PASSWORD 확보
  2. 토큰 발급: _superusers/auth-with-password로 PB_TOKEN 획득
  3. 안전한 조회로 시작:
  • List collections → View collection
  1. 변경 작업:
  • Create 또는 Update
  1. 파괴적 작업은 사용자 요청을 재확인 후 실행:
  • Delete / Truncate / Import(deleteMissing=true)

빠른 점검 체크리스트

  • PB_URL에 /api를 중복으로 붙이지 않았나? (base는 host까지만)
  • Authorization: <token> 헤더 형식이 맞나?
  • superuser로 로그인했나? (일반 auth record 토큰으로는 collections 조작이 막힐 수 있음)
  • import에서 deleteMissing=true를 의도했나?
  • truncate/delete는 정말 필요한가?

참고

oai_citation:0‡pocketbase.io