pocketbase

PocketBase スキル

同梱の Python スクリプトとリファレンスを使って、PocketBase バックエンドプロジェクト（スタンドアロンバイナリまたは Go パッケージモード）を操作します。

スキルのリソース

まず、このスキルディレクトリ内のリソースを使用してください。

• scripts/ - 認証、コレクション、レコード、バックアップ、マイグレーションテンプレート生成用の実行可能なヘルパー
• references/ - 必要に応じて読み込む詳細なバックエンドドキュメント
• assets/ - マイグレーションテンプレート

まず --help の出力とこのガイドを確認してください。動作が不明な場合は、該当するスクリプトファイルだけを読んでください。

0. クイックスタート

モードの判定

1. go.mod に github.com/pocketbase/pocketbase が含まれている場合 -> Go パッケージモード
2. それ以外の場合 -> スタンドアロンモード

ブートストラップ（PocketBase が起動していない場合）

1. 最新バージョンを動的に解決します。

VERSION=$(curl -s https://api.github.com/repos/pocketbase/pocketbase/releases/latest | python3 -c "import sys,json; print(json.load(sys.stdin)['tag_name'].lstrip('v'))")
ARCH=$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/')
OS=$(uname -s | tr A-Z a-z)
curl -sL "https://github.com/pocketbase/pocketbase/releases/download/v${VERSION}/pocketbase_${VERSION}_${OS}_${ARCH}.zip" -o pb.zip
unzip -o pb.zip pocketbase && rm pb.zip

2. スーパー ユーザーを作成します。

./pocketbase superuser create [email protected] <password>

3. .env を設定します（.env が .gitignore に含まれていることを確認してください）。

PB_URL=http://127.0.0.1:8090
[email protected]
PB_SUPERUSER_PASSWORD=your-password

4. サービスを起動します。

nohup ./pocketbase serve --http=127.0.0.1:8090 > pb.log 2>&1 &

5. ヘルスチェックを実行します。

python scripts/pb_health.py

2026-02-27 時点で、最新の安定版リリースは v0.36.5 です。

1. 設計と安全性のチェックリスト

モデルの事前知識には v0.23 より前のパターンが含まれている可能性があります。スキーマまたはフックを変更する前に、以下を確認してください。

v0.23 以降の重要なルール

• _admins ではなく _superusers を使用します
• schema ではなくコレクションの fields を使用します
• options ラッパーは使わず、フラットなフィールドプロパティを使用します
• マイグレーションでは型付きフィールドコンストラクター（TextField、SelectField、RelationField など）を使用します
• ルートでは :param ではなく {param} のパス構文を使用します
• JSVM フックでは e.next() を呼び出し、Go フックでは return e.Next() を返します
• 複数の行が該当する可能性がある場合、@collection.* フィルターでは ?= を使用します

API ルールのデフォルト

• null -> スーパー ユーザーのみ
• "" -> パブリック（未認証を含む）

デフォルトでは null に設定し、必要なものだけを公開してください。

Go モードの確認事項

• コレクションの変更には API／管理 UI を使用し、PocketBase にマイグレーションを自動生成させます
• 生成された pb_migrations/ 内のファイルをコミットします
• 開発環境では migratecmd.MustRegister(..., migratecmd.Config{Automigrate: true}) を設定します
• 手動マイグレーションを使用する場合は、ブランクインポートがあることを確認します：_ "yourmodule/migrations"
• 手動の Go マイグレーションでルールを割り当てる場合は、types.Pointer("...") を使用します

2. 主な操作

2.1 認証

スーパー ユーザー認証：

python scripts/pb_auth.py

ユーザー認証：

python scripts/pb_auth.py --collection users --identity [email protected] --password secret

2.2 コレクション

一覧表示／取得：

python scripts/pb_collections.py list
python scripts/pb_collections.py get posts

作成／更新／削除：

python scripts/pb_collections.py create --file schema.json
python scripts/pb_collections.py update posts --file updates.json
python scripts/pb_collections.py delete posts

一括インポート（複数コレクションのセットアップに推奨）：

python scripts/pb_collections.py import --file collections.json

重要：

• 新しい users コレクションは作成せず、既存のものを更新してください
• ペイロードに API ルールが含まれる場合は、シェルの引用符に関する問題を避けるため --file を使用してください
• fields を更新する場合は、全フィールドを送信してください（部分マージではありません）

2.3 レコード

python scripts/pb_records.py list posts --filter 'status="published"' --sort "-created" --expand "author"
python scripts/pb_records.py get posts <recordId>
python scripts/pb_records.py create posts --file record.json
python scripts/pb_records.py update posts <recordId> '{"status":"published"}'
python scripts/pb_records.py delete posts <recordId>

2.4 バックアップ

python scripts/pb_backups.py list
python scripts/pb_backups.py create
python scripts/pb_backups.py restore <backupKey>
python scripts/pb_backups.py delete <backupKey>

復元するとすべてのデータが置き換えられます。復元の前に必ずバックアップを作成してください。

2.5 マイグレーション

主なワークフロー（両モード共通）：

1. PocketBase を起動します
2. API／管理 UI でコレクションを変更します
3. 自動生成された pb_migrations/ 内のマイグレーションをコミットします

手動マイグレーションテンプレートの生成（シード／データ変換／生 SQL の場合のみ）：

python scripts/pb_create_migration.py "backfill_user_slugs"
python scripts/pb_create_migration.py "seed_categories" --dir ./pb_migrations

3. 検証

スキーマまたはルールを変更した後、以下を実行します。

1. python scripts/pb_collections.py get <collection>
2. CRUD のスモークテスト（作成／一覧表示／取得／更新／削除）
3. スーパー ユーザー以外のトークンを使ったルールテスト

ルールによって拒否された場合の動作に関するリファレンス：

• listRule で拒否 -> 200 と空の items
• viewRule で拒否 -> 404
• createRule で拒否 -> 400
• updateRule で拒否 -> 404
• deleteRule で拒否 -> 404
• 一般ユーザーに対する null ルール -> 403

null 以外の API ルールまたはカスタムフック／ルートがある場合、E2E テストは必須です。references/e2e-testing.md と scripts/pb_e2e_helpers.py を使用してください。

E2E テストの最低限のカバレッジ：

• 未認証アクセスが拒否される
• 認証済みユーザーの許可されたパスが成功する
• 他ユーザーのデータへのアクセスがブロックされる
• 作成ペイロードでの所有者の偽装がブロックされる
• cascadeDelete の動作が検証される
• カスタムルートの認証強制が検証される
• フックの副作用が検証される

4. リファレンスマップ

必要なものだけをお読みください。

• よくある落とし穴：references/gotchas.md
• API のルール：references/api-rules-guide.md
• コレクション API：references/collections-api.md
• レコード API：references/records-api.md
• 認証 API：references/auth-api.md
• マイグレーション（JS）：references/migrations.md
• フィールド型：references/field-types.md
• リレーションのパターン：references/relation-patterns.md
• ファイルの処理：references/file-handling.md
• JSVM フック：references/jsvm-hooks.md
• Go のセットアップ：references/go-framework.md
• Go のマイグレーション：references/go-migrations.md
• Go のフック／ルート：references/go-hooks-routes.md
• E2E テスト：references/e2e-testing.md

フロントエンド統合作業には pb-react-spa スキルを使用します。