appwrite-backend

Appwrite 開発

ルート

操作する前にオーナーを読み込んでください。記載されていない詳細については、推測せずにオーナーを読んでください。

トリガー	担当
Appwrite に対するエージェント操作、MCP サーバーのセットアップ、Appwrite ドキュメントの検索	mcp-servers
本番環境のスキーマ／データ／ACL／関数の切り替え	production-migrations + 書き込みが同一トランザクションを共有する場合は transactions
TablesDB のトランザクションまたはサービス間の整合性	transactions + ACL を変更する場合は permissions
TablesDB、Auth、Storage、プロバイダーデータ、保持された監査証跡にわたるアカウント／対象データの完全消去	destructive-erasure + transactions
大量の行の作成／更新／アップサート／削除、トランザクション上限への圧迫、行ごとの書き込みループ	bulk-operations + アトミックな範囲が複数のリクエスト／テーブルにまたがる場合は transactions
デプロイ済みの Query.equal() の値数上限を超える ID でのフィルタリング	chunked-queries
テーブル／カラム／インデックスの設計、保存時の暗号化、自動インクリメント、タイムスタンプの上書き、CSV のインポート／エクスポート	schema-management
クエリの形状、select、空間、時刻ヘルパー、インデックス不足の疑い	query-optimization
同時に変更されるカウンター、配列、文字列、日付フィールド	atomic-operators
リレーションシップのモデリングまたはたどり方	relationships
リスト、フィード、無限スクロール、大きなオフセットでのページング	pagination-performance
遅い処理経路、キャッシュ、差分同期、ブートストラップの順序	performance
帯域幅、実行、ストレージのコスト	cost-optimization
セッション、MFA、SSR 認証、JWT、ユーザーラベル、セキュリティ設定	authentication
OAuth、マジックリンク、メール OTP、電話、匿名、カスタムトークン、メール確認、パスワード復旧、セッション一覧／削除、ユーザー設定	auth-methods
ACL の設計、ロックアウト、公開データ漏えいの疑い	permissions
チーム、メンバーシップ、マルチテナンシー	teams
アップロード、ダウンロード、プレビュー、変換、バケット設定	storage-files
関数の作成、ハンドラー、ランタイム、コールドスタート、環境変数	functions
関数イベント、スケジュール、冪等性、バイナリペイロード、CI/CD	functions-advanced
関数実行 SDK のモデルまたはレスポンス形式の解析失敗、実行モード、レスポンス取得、実行タイムアウト	functions-advanced
Realtime サブスクリプション、チャンネル、プレゼンス、イベントフィルタリング	realtime
プッシュ、メール、SMS の配信	messaging
外部システムへのイベント送信	webhooks
アバター、イニシャル、QR、国旗、ファビコン	avatars
429、再試行、型付きエラー、タイムアウト、コードゼロのトランスポート障害、クライアントリクエストの急増、部分同期レポート	error-handling + 起動／ブートストラップ時のリクエスト急増については performance
プラットフォームの上限または制限エラー	limits
国、通貨、言語、位置情報の検索	locale
GraphQL エンドポイント	graphql
セルフホスト可能なインストール、設定、セキュリティ、スケーリング、SDK のバージョン固定	self-hosting
セルフホスト環境のバックアップ、復元、アップグレード、データ損失インシデント	self-hosting-ops
ヘルスチェック、キューの深さ、稼働時間の監視	health

不変条件

1. エージェントの操作にはMCPを、アプリケーションコードには公式SDKを使用する — エージェントによる読み取り、変更、デプロイ、診断には mcp-servers を使用します。MCPの機能が不足している場合は、その不足を報告してください。エージェントの操作に、SDK、HTTP、コマンドラインで直接フォールバックしてはいけません。アプリケーションコードでは公式SDKを使用します。生のAppwrite HTTP（fetch、requests、dio、package:http、curl）を使用できるのは、SDKにエンドポイントがない場合、または分離してテスト済みの Client.call によるモデル解析の回避策に限られます。
2. 対象と呼び出し形式に合わせてSDKのバージョンを固定する — Cloud：最新の安定版公式SDK。セルフホスト：デプロイ済みサーバーバージョン（2.x または 1.9.x）に正確に対応するリリース固定バージョンを self-hosting で確認します。「1.9.xと互換性がある」は、リリースに正確に対応していることを意味しません。バージョンを変更する前に、途中のすべての破壊的変更を監査し、候補のSDKを使ってリポジトリ内の実際の呼び出しが動作することを確認してください。バージョン解決だけでは不十分です。リポジトリで検証済みのSDKバージョン固定は、スキルで指定されたバージョンより優先されます。
3. レガシーの Databases サービスではなく、TablesDBを使用する — そのCollections/Documents APIは 1.8.0 以降、非推奨です。DocumentsDBとVectorsDBは別のサービスであり、レガシーAPIではありません。
4. Appwrite IDは ID.unique() で一度だけ割り当てる — 再試行可能な作成処理では、最初の試行前に ID.unique() を呼び出し、返されたIDを永続的なドラフト／インテントに保存して、すべての再試行／照合で同じIDを再利用します。再試行時に新たに ID.unique() を呼び出すと、2つ目のリソースが作成されます。ビジネス上の識別子／自然キーはインデックス付きの列に保持してください。リソースIDを名前、タイムスタンプ、スラッグ、ハッシュ、カスタムジェネレーターから生成してはいけません。
5. ACLを明示する — サーバーSDK／Consoleでの作成ではリソースACLは空になります。クライアントSDKでの作成では、作成者に読み取り／更新／削除の権限が付与されます。ACLの正確性が重要な場合は、必ず Permission／Role を明示的に渡してください。
6. 上限値はデプロイ済みの対象に合わせる — ページサイズ、一度のリクエストで処理する一括行数、トランザクション操作数、Query.equal() の値数上限は、記憶ではなく、デプロイ済みサーバーのソース／設定から確認してください。
7. 必要な結果に応じて実行モードを選ぶ — レスポンスデータが必要な場合は、30秒の制限内で同期的に createExecution を実行します。非同期のバックグラウンド処理では、上限を設けた状態監視と信頼できる情報源との照合を行います。実行のポーリング／リアルタイム監視では、レスポンス本文やヘッダーは取得できません。長時間実行の結果には、権限が付与された永続的な結果の読み取り手段が必要です。破壊的処理の失敗を報告するのは、照合によって対象エンティティがまだ存在することを確認した後に限ります。同期レスポンスは直接使用してください。状態が不明瞭な場合や 404 の場合は、再試行前に照合してください。functions-advanced を使用します。
8. 破壊的変更の対象範囲を立証する — スキーマ／アクセス権の縮小には、完全な本番環境のインベントリ、正確に承認されたリソースID、バックアップ／復旧の証明が必要です。フィールドの欠落、ページネーションの未完了、アクセス権への影響が不明な場合は、処理を中止します。production-migrations を使用します。
9. 本番環境のマイグレーションは段階的に行う — 互換性を保った拡張 → 型を考慮した再開可能なバックフィル → 互換性のあるデプロイ → 縮小／読み戻し → コンシューマーの有効化、の順に進めます。データ／スキーマが部分的な状態では、後続コードを有効化しません。production-migrations を使用します。
10. 最適化する前に書き込みの意図を保つ — 更新のみを行う処理を upsertRow／upsertRows 経由にしてはいけません。事前読み取り、存在確認、完全なペイロードのいずれを行っても、存在しない場合に作成するセマンティクスは変わりません。行ごとに同じパッチを適用する場合は updateRows を使用します。行ごとに更新内容が異なる場合は、検証済みのトランザクション上限内で action: update を含む createOperations を使用するか、設計を見直してください。トランザクションの負荷が高くても、upsertを許可する理由にはなりません。bulk-operations を使用します。
11. コーディング前にコレクションへの書き込みをまとめる — 対象数が1件を超える可能性がある場合、またはデータに応じて変わる場合は、実装前に変更対象全体とデプロイ済みの上限を確認します。互換性のあるサーバー一括処理メソッドがある場合、行ごとの書き込みループは禁止です。一括処理がサポートされない場合は、全操作数の見積もりと、途中失敗時の整合性の証明が必要です。計画全体が上限を超える場合は、設計を見直すか、固定点まで再開可能なワークフローにします。1つの原子的な不変条件を、コミット済みの複数バッチに分割してはいけません。bulk-operations と transactions を使用します。
12. 失敗の因果関係を保つ — クリーンアップ、補償処理、ロールバックが失敗しても、主たる例外を置き換えてはいけません。両方のエラー、スタックトレース、実行ID／トランザクションIDを保持し、操作の失敗を報告したうえで、正確な事後条件を照合してください。transactions を使用します。
13. クライアントからの要求と不確定な結果を調整する — エンドポイント／プロジェクトごとに1つのコーディネーターを設け、フォアグラウンド、同期、認証、再試行のトラフィックを管理します。同時実行数に上限を設定し、429／トランスポートエラーのクールダウンを共有します。コード0のネットワーク障害を分類し、1つの期限内で読み取りを再試行します。書き込み／トランザクションは、再試行前に必ず照合します。操作の失敗ごとにインシデントを1件だけ報告し、部分的な失敗の後に同期チェックポイントを進めてはいけません。error-handling を使用します。

SDK の振り分け

ランタイム	パッケージ
Web TypeScript/JavaScript/React	appwrite
Node.js/Deno/TypeScript SSR/Functions	node-appwrite
Flutter クライアント	appwrite
Dart サーバー/Functions	dart_appwrite
Python サーバー/Functions	appwrite

• 呼び出し形式：TypeScript ではオブジェクトパラメーター、Python ではキーワード引数、Dart では名前付きパラメーターを使用します。位置引数は、既存コードに合わせる場合、または明示的に求められた場合にのみ使用します。
• クライアント SDK ではアカウントセッションとユーザー単位の API を使用します。サーバー SDK では API キーを使用します。SSR では 2 つのクライアントを使用します。セッション作成用の再利用可能な管理者クライアントと、setSession(...) を使うリクエストごとのセッションクライアントです。後者を共有してはいけません。
• Cloud プロジェクトのエンドポイント = https://<REGION>.cloud.appwrite.io/v1。
• ランタイムが対応している場合は、ウォーム状態の Function ハンドラーの外でクライアントを初期化します。

リソース

ドキュメント https://appwrite.io/docs · API https://appwrite.io/docs/apis/rest · SDK https://github.com/appwrite