PocketBase ベストプラクティス

PocketBase v0.36+ 向け、9カテゴリ 63ルール（影響度順）

カテゴリ優先度順

優先度	カテゴリ	影響	ルール数
1	コレクション設計	重大	coll-field-types, coll-auth-vs-base, coll-relations, coll-indexes, coll-view-collections, coll-geopoint
2	API ルール & セキュリティ	重大	rules-basics, rules-filter-syntax, rules-request-context, rules-cross-collection, rules-locked-vs-open, rules-strftime
3	認証	重大	auth-password, auth-oauth2, auth-otp, auth-token-management, auth-mfa, auth-impersonation
4	SDK 使用	高	sdk-initialization, sdk-auth-store, sdk-error-handling, sdk-auto-cancellation, sdk-filter-binding, sdk-field-modifiers, sdk-send-hooks
5	クエリパフォーマンス	高	query-pagination, query-expand, query-field-selection, query-batch-operations, query-n-plus-one, query-first-item, query-back-relations
6	リアルタイム	中	realtime-subscribe, realtime-events, realtime-auth, realtime-reconnection
7	ファイルハンドリング	中	file-upload, file-serving, file-validation
8	本番・デプロイ	中	deploy-backup, deploy-configuration, deploy-reverse-proxy, deploy-sqlite-considerations, deploy-rate-limiting, deploy-scaling
9	サーバーサイド拡張	高	ext-go-setup, ext-js-setup, ext-hooks-chain, ext-hooks-record-vs-request, ext-routing-custom, ext-transactions, ext-filter-binding-server, ext-filesystem, ext-cron-jobs, ext-go-migrations, ext-js-migrations, ext-mailer, ext-settings, ext-testing, ext-compose-request-flow, ext-go-custom-sqlite, ext-jsvm-scope, ext-jsvm-modules

クイックリファレンス

コレクション設計（重大）

• coll-field-types: 適切なフィールド型を使用（オブジェクトは json、列挙は select）
• coll-auth-vs-base: ユーザーは auth コレクションを拡張、非認証データは base を使用
• coll-relations: 手動 ID 文字列ではなく relation フィールドを使用
• coll-indexes: フィルタ/ソートが頻繁なフィールドにインデックスを作成
• coll-view-collections: 複雑な集約には views を使用
• coll-geopoint: 座標は json フィールドで lat/lng を保存

API ルール（重大）

• rules-basics: 常に API ルールを設定；空 = パブリックアクセス
• rules-filter-syntax: ルール内で @request.auth、@collection、@now を使用
• rules-request-context: @request.body、@request.query でリクエストデータにアクセス；@request.context の値: default/oauth2/otp/password/realtime/protectedFile
• rules-cross-collection: クロスコレクション確認には @collection.name.field を使用
• rules-locked-vs-open: ロック状態で始め、選択的にオープン
• rules-strftime: 日付計算に strftime('%Y-%m-%d', created) を使用（v0.36+）

認証（重大）

• auth-password: メール/パスワードログインに authWithPassword を使用
• auth-oauth2: Admin UI で OAuth2 プロバイダを設定
• auth-otp: 2ステップフロー requestOTP → authWithOTP；requestOTP をレート制限、メール存在を漏らさない
• auth-token-management: トークンは安全に保管、有効期限前にリフレッシュ
• auth-mfa: 重要なアプリケーションで MFA を有効化
• auth-impersonation: ユーザーの代わりに管理者アクションを行う場合は impersonation を使用

SDK 使用（高）

• sdk-initialization: クライアントを 1 回初期化、インスタンスを再利用
• sdk-auth-store: React Native/SSR に AsyncAuthStore を使用
• sdk-error-handling: ClientResponseError をキャッチ、ステータスコード確認
• sdk-auto-cancellation: 並行リクエストの場合は自動キャンセルを無効化
• sdk-filter-binding: インジェクション防止にフィルタバインディングを使用

クエリパフォーマンス（高）

• query-expand: N+1 クエリを回避するためにリレーションを展開
• query-field-selection: 必要なフィールドのみを選択
• query-pagination: 大規模データセットはカーソルベースのページネーション
• query-batch-operations: 可能な限りバッチ作成/更新

リアルタイム（中）

• realtime-subscribe: 特定レコードまたはコレクションにサブスクライブ
• realtime-events: create、update、delete イベントを別々に処理
• realtime-auth: リアルタイムは API ルールを自動的に尊重
• realtime-reconnection: 再接続ロジックを実装

ファイルハンドリング（中）

• file-upload: アップロードに FormData を使用、適切なコンテンツタイプを設定
• file-serving: ファイル URL には pb.files.getURL() を使用
• file-validation: ファイルタイプとサイズをサーバーサイドで検証

デプロイ（中）

• deploy-backup: pb_data の定期バックアップをスケジュール
• deploy-configuration: 設定に環境変数を使用
• deploy-reverse-proxy: 本番環境では nginx/caddy の背後に配置
• deploy-sqlite-considerations: 本番ワークロード向けに SQLite を最適化
• deploy-rate-limiting: 組み込みレート制限を有効化（v0.36.7 時点で固定ウィンドウ）；防御層を深くするため Nginx/Caddy 前面化
• deploy-scaling: ulimit -n を上げ、GOMEMLIMIT を設定、設定暗号化を有効化

サーバーサイド拡張（高）

• ext-go-setup: app.OnServe() を使ってルートを登録；フック内では e.App を使用、親スコープの app は不可
• ext-js-setup: *.pb.js ファイルを pb_hooks/ に配置；/// <reference path="../pb_data/types.d.ts" /> を追加
• ext-hooks-chain: 常に e.Next()/e.next() を呼び出す；後で Unbind するために Bind で Id を指定
• ext-hooks-record-vs-request: OnRecordEnrich でレスポンスを整形（リアルタイム含む）；OnRecordRequest は HTTP のみ
• ext-routing-custom: ルートを /api/{yourapp}/ 名前空間内に配置；RequireAuth() ミドルウェアをアタッチ
• ext-transactions: RunInTransaction 内では スコープされた txApp を使用；外側の app をキャプチャしない
• ext-filter-binding-server: {:name} + dbx.Params で FindFirstRecordByFilter / FindRecordsByFilter にユーザー入力をバインド
• ext-filesystem: すべての NewFilesystem() / NewBackupsFilesystem() ハンドルに defer fs.Close() を実行
• ext-cron-jobs: app.Cron().MustAdd(id, expr, fn) / cronAdd() で登録；安定した id、__pb*__ プリフィックス不可
• ext-go-migrations: バージョン付き .go ファイルを migrations/ 下に配置；Automigrate: osutils.IsProbablyGoRun()
• ext-js-migrations: pb_migrations/<unix>_*.js に migrate(upFn, downFn) で作成；ファイル名で自動検出
• ext-mailer: 送信時に app.Settings().Meta から送信者を解決；no-reply@example.com を本番で使用しない；送信ごとにメールクライアントを作成
• ext-settings: 呼び出し時に app.Settings() で読み取り；PB_ENCRYPTION（32 文字）を設定して _params を保存時に暗号化
• ext-testing: tests.NewTestApp(testDataDir) + tests.ApiScenario；defer app.Cleanup()、ExpectedEvents でアサート
• ext-compose-request-flow: 各層（ルート → トランザクション → フック → エンリッチ）でどの app インスタンスがアクティブかを示す複合説明
• ext-go-custom-sqlite: FTS5/ICU が必要な場合のみ DBConnect を使用；DBConnect は 2 回呼ばれる（data.db + auxiliary.db）
• ext-jsvm-scope: ハンドラ外の変数は実行時に未定義 — require() をハンドラ内で共有設定を読み込み
• ext-jsvm-modules: CJS（require()）のみが goja で動作；ESM を先にバンドル；変更可能なモジュール状態を回避

使用例

AI エージェントでこれらを試して、スキルを動作確認できます：

新機能の構築:

• 「e-commerce アプリのスキーマを設計してください：製品、注文、レビュー」
• 「Google と GitHub による OAuth2 ログインを実装してください」
• 「PocketBase サブスクリプションでリアルタイム通知システムを構築してください」
• 「画像検証とサムネイル生成付きのファイルアップロードフォームを作成してください」

問題の修正:

• 「100k レコードのリスト クエリが遅い -- 最適化してください」
• 「バッチ操作で 403 エラーが発生している」
• 「ループでオーサー データを読み込む投稿リストの N+1 クエリ問題を修正してください」
• 「数分後にリアルタイム サブスクリプションが停止する」

セキュリティレビュー:

• 「API ルールをレビュー -- ユーザーは自分のデータのみアクセス可能」
• 「適切なアクセス制御をセットアップ：管理者がすべてのコンテンツを管理、ユーザーが自分のみ編集」
• 「SSR のために認証 Cookie は安全に設定されているか」
• 「IDOR 脆弱性のコレクション ルールを監査」

本番環境へのデプロイ:

• 「HTTPS、レート制限、セキュリティヘッダー付き Nginx で PocketBase を設定」
• 「PocketBase データベースの自動バックアップをセットアップ」
• 「約 500 同時ユーザーの本番ワークロード向けに SQLite 設定を最適化」
• 「Docker Compose と Caddy で PocketBase をデプロイ」

PocketBase の拡張:

• 「レコード作成後に Slack 通知を送信するカスタム Go ルートを追加」
• 「ユーザーサインアップ前にメール ドメインを検証する pb_hooks スクリプトを作成」
• 「カスタム SQLite ドライバで FTS5 フルテキスト検索をセットアップ」
• 「複数の pb_hooks ファイル間で競合状態なく設定オブジェクトを共有」

詳細ルール

完全なルール文書とコード例については、関連カテゴリをロード：

• Collection Design - スキーマパターン、フィールド型、リレーション、インデックス
• API Rules & Security - アクセス制御、フィルタ式、セキュリティパターン
• Authentication - パスワード認証、OAuth2、MFA、トークン管理
• SDK Usage - クライアント初期化、認証ストア、エラーハンドリング、フック
• Query Performance - ページネーション、展開、バッチ操作、N+1 防止
• Realtime - SSE サブスクリプション、イベントハンドリング、再接続
• File Handling - アップロード、配信、検証
• Production & Deployment - バックアップ、設定、リバースプロキシ、SQLite 最適化
• Server-Side Extending - Go/JSVM セットアップ、イベントフック、カスタムルート、モジュール、カスタム SQLite