Communitygithub.com

sgaabdu4/appwrite-backend

AIエージェント向けAppwrite BaaSスキル。TablesDB、認証、ストレージ、Functions、メッセージング、RealtimeをDart、Python、TypeScriptでカバー。

appwrite-backend とは?

このスキルは、AIエージェント(Claude Code、Cursor、Codexなど)がAppwriteのバックエンドサービスを効率的に操作するための包括的なガイドです。TablesDB(テーブルデータベース)を中心に、認証、ストレージ、Functions、メッセージング、Realtime機能をDart、Python、TypeScriptの公式SDKを使って実装するためのベストプラクティスと厳格なルールを提供します。スキルは、SDKのバージョン固定、`ID.unique()`による一意識別子の使用、カーソルベースのページネーション、アトミック更新のためのOperator、型安全なSDK生成など、パフォーマンスと信頼性を最大化するための15の重要なルールを定義しています。また、よくあるアンチパターン(N+1クエリ、オフセットページネーション、ポーリングなど)を回避する方法や、コスト最適化のテクニックも詳細に解説しており、Appwrite Cloudとセルフホスト版(1.9.x)の両方をサポートします。

対応~Claude Code~Codex CLI✓Cursor
npx skills add sgaabdu4/appwrite-backend

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

Appwrite 開発

重要なルール

  1. 公式SDKパッケージのみを使用 — Dart/Flutter/TypeScript/Pythonはsdk-routingに従うこと。SDKがエンドポイントを欠いているか、分離・テスト済みのClient.callがSDKのモデルパースを回避しない限り、fetch、requests、dio、package:http、curlなどを介した生のREST/GraphQL HTTPは違反です。
  2. ターゲットに応じてSDKを固定 — Cloud:最新安定版SDK。セルフホスト版1.9.x:dart_appwrite 25.1.0、Flutter appwrite 25.2.0、node-appwrite 26.2.0、Web appwrite 26.1.0、Python appwrite 21.0.0、CLI 22.4.0。
  3. TablesDB APIを使用 — Collections APIは1.8.0で非推奨
  4. すべての一意識別子にID.unique()を使用 — 行ID(rowId:)、ファイルID、ユーザーID、チームID、Webhook ID、メッセージID、サブスクライバーID、およびカラム内のエンティティID。ハードコードされた一意識別子、カスタムジェネレーター、名前、タイムスタンプ、スラッグをIDとして使用しないでください。これらはカラム制限を超過し、データを漏洩させます。安定したナチュラルキーは、インデックス付きカラムとしてのみ使用してください。
  5. Query.select()を使用 — リレーションシップは明示的な選択なしではIDのみを返します。
  6. カーソルページネーションを使用 — オフセットは大規模テーブルではパフォーマンスが低下します
  7. カウンターにはOperatorを使用 — 競合状態を回避します
  8. インデックスを作成 — クエリがないとテーブル全体をスキャンします
  9. ハンドラーの外部で初期化 — SDK/接続はウォーム呼び出し間で持続します
  10. ドメインごとに関数をグループ化 — 操作ごとではなく、ドメインごとに1つ
  11. ポーリングよりもイベントトリガー — 1つのトリガーが数千のリクエストを置き換えます
  12. 明示的な文字列タイプを使用 — stringは非推奨。varcharまたはtext/mediumtext/longtextを使用
  13. appwrite generateを使用 — スキーマから型安全なSDKを生成
  14. チャネルヘルパーを使用 — 型安全なリアルタイムサブスクリプション、生の文字列は不使用
  15. Realtimeクエリを使用 — サーバーサイドのイベントフィルタリング、クライアントサイドではない
  16. 長時間実行関数を非同期で開始 — 削除/同期/インポート/エクスポート/マイグレーション/生成フローでは、クライアントcreateExecution呼び出しを非同期実行で使用し、その後、制限付きポーリング/Realtime/フェッチでソースオブトゥルース状態を調整します。バックエンドの完了をブロックせず、調整によってエンティティ/アカウントがまだ存在することが証明された後にのみ、破壊的な障害を報告します。

CLIクイックチェック(トップ)

プロジェクトごとにリポジトリローカルで無視された.env.appwrite.localを使用。グローバルなCLI設定は信頼しないこと。

# .env.appwrite.local (gitignored)
APPWRITE_ENDPOINT=https://<endpoint>/v1
APPWRITE_PROJECT_ID=<project_id>
APPWRITE_API_KEY=standard_...
# "cloud" またはセルフホストサーバーの行を使用。
APPWRITE_SERVER_VERSION=cloud

CLIバージョンポリシー:

  • Appwrite Cloud:最新のappwrite-cli。
  • セルフホストAppwrite 1.9.x:[email protected]。

Appwrite CLI作業の前に:

set -a
[ -f .env.appwrite.local ] && . ./.env.appwrite.local
set +a

case "$APPWRITE_SERVER_VERSION" in
  cloud|"")
    npm install -g appwrite-cli@latest
    ;;
  1.9|1.9.*)
    npm install -g [email protected]
    ;;
  *)
    echo "サポートされていない APPWRITE_SERVER_VERSION=$APPWRITE_SERVER_VERSION です。続行する前に適切なCLIを選択してください。"
    exit 1
    ;;
esac

appwrite --version
appwrite client \
  --endpoint "$APPWRITE_ENDPOINT" \
  --project-id "$APPWRITE_PROJECT_ID" \
  --key "$APPWRITE_API_KEY"

appwrite client --debug

appwrite client --debugは、続行する前に期待されるエンドポイント/プロジェクトとマスクされたキーを表示する必要があります。欠落している場合は、エンドポイント、プロジェクトID、APIキー、サーバーバージョンを要求してください。

ルール:appwrite.config.json = ローカルプロジェクト設定。appwrite client ... = グローバルオーバーライド(非対話型)。オーバーライドのクリア:appwrite client --reset。CLIヘルパーフラグはバージョンによって異なります。利用できない場合は、生の--queriesを使用するか、迅速なステータスチェックのためにプレーンテーブル出力を解析します。 詳細:appwrite-cli

用語(1.8.0以降)

旧新
CollectionsTables
DocumentsRows
AttributesColumns
DatabasesTablesDB

セットアップ

パッケージポリシー:

  • Cloud:最新安定版公式SDK。
  • セルフホスト版1.9.x:重要なルール2の固定バージョンを使用。
  • TypeScript/Reactブラウザ:appwrite。TypeScriptサーバー/SSR/Functions:node-appwrite。
  • Python:appwrite。SDK呼び出しにはキーワード引数を推奨。
  • Dart:Flutter/クライアントアプリにはappwrite、サーバー/Functionsにはdart_appwrite。名前付きパラメータを推奨。
import 'package:dart_appwrite/dart_appwrite.dart';

final client = Client()
    .setEndpoint('https://cloud.appwrite.io/v1')
    .setProject('<PROJECT_ID>')
    .setKey('<API_KEY>');

final tablesDB = TablesDB(client);
from appwrite.client import Client
from appwrite.services.tables_db import TablesDB
client = Client()
client.set_endpoint('https://cloud.appwrite.io/v1')
client.set_project('<PROJECT_ID>')
client.set_key('<API_KEY>')
tables_db = TablesDB(client)
import { Client, TablesDB } from 'node-appwrite';
const client = new Client()
    .setEndpoint('https://cloud.appwrite.io/v1')
    .setProject('<PROJECT_ID>')
    .setKey('<API_KEY>');
const tablesDB = new TablesDB(client);

TablesDB CRUD

// 作成
await tablesDB.createRow(databaseId: 'db', tableId: 'users', rowId: ID.unique(),
    data: {'name': 'Alice'});

// 読み取り
final rows = await tablesDB.listRows(databaseId: 'db', tableId: 'users',
    queries: [Query.equal('status', 'active'), Query.select(['name', 'email'])]);

// 更新
await tablesDB.updateRow(databaseId: 'db', tableId: 'users', rowId: 'user_123',
    data: {'status': 'inactive'});

// Upsert
await tablesDB.upsertRow(databaseId: 'db', tableId: 'settings', rowId: 'prefs',
    data: {'theme': 'dark'});

// 削除
await tablesDB.deleteRow(databaseId: 'db', tableId: 'users', rowId: 'user_123');

SDKの記法を使用:

  • TypeScriptはオブジェクトパラメータを使用:tablesDB.createRow({ databaseId, tableId, rowId, data })。
  • Pythonはキーワード引数を使用:tables_db.create_row(database_id='db', table_id='users', row_id=ID.unique(), data={...})。
  • Dartは上記のように名前付きパラメータを使用。

一括操作: bulk-operations.md | チャンク化IDクエリ: chunked-queries.md


クエリリファレンス

比較: equal | notEqual | lessThan | lessThanEqual | greaterThan | greaterThanEqual | between | notBetween 文字列: startsWith | endsWith | contains | search (+ not バリアント) NULL: isNull | isNotNull · 論理: and([...]) | or([...]) ページネーション: select | limit | cursorAfter | cursorBefore | orderAsc | orderDesc | orderRandom タイムスタンプ: createdAfter | createdBefore | updatedAfter | updatedBefore 空間: distanceEqual | distanceLessThan | distanceGreaterThan | intersects | overlaps | touches | crosses (+ not バリアント)

すべてQuery.プレフィックス付き。詳細:query-optimization.md


演算子(アトミック更新)

data: {
    'likes': Operator.increment(1),
    'tags': Operator.arrayAppend(['trending']),
    'updatedAt': Operator.dateSetNow(),
}

数値: increment | decrement | multiply | divide 配列: arrayAppend | arrayPrepend | arrayRemove | arrayUnique | arrayIntersect | arrayDiff その他: toggle | stringConcat | stringReplace | dateAddDays | dateSetNow

詳細:atomic-operators.md


カラムタイプ

タイプ最大文字数インデックス用途
varchar16,383フル(サイズ < 768の場合)クエリ可能な短い文字列
text16,383プレフィックスのみ説明、メモ
mediumtext4,194,303プレフィックスのみ記事
longtext1,073,741,823プレフィックスのみ大きなドキュメント

stringは非推奨。 クエリ可能な場合はvarcharを、インデックス不要の場合はtextを使用してください。

その他: integer | float | boolean | datetime | email | url | ip | enum | relationship | point | line | polygon

詳細:schema-management.md


パフォーマンス

ルール影響
カーソルページネーションオフセットより10〜100倍高速
ページネーションミックスイン(Dart)データソースあたり約50行節約
Query.select()リレーションシップで12〜18倍高速
total: falseCOUNTスキャンを排除
インデックス大規模テーブルで100倍高速
演算子競合状態なし
一括操作N → 1リクエスト
デルタ同期変更された行のみをフェッチ

詳細:performance.md, pagination-performance.md


型安全SDK生成

appwrite generate

スキーマからgenerated/appwrite/に型付きヘルパーを生成します。オートコンプリート+コンパイルチェック。スキーマ変更後に再生成。 CLIフロー:login -> init project -> pull -> generate -> push。詳細:appwrite-cli


認証

メール/パスワード、OAuth(50以上のプロバイダー)、電話、マジックリンク、匿名、メールOTP、カスタムトークン。MFA:TOTP/メール/電話/リカバリー。SSRセッション。関数用JWT。 SSR Cookie:a_session_<PROJECT_ID>。管理者クライアントがセッションを作成。リクエストごとのセッションクライアントがユーザーコンテキストを読み取ります。 メールポリシーは、サインアップ/更新時にフリー、エイリアス、または使い捨てメールをブロックできます。

詳細:authentication.md | auth-methods.md


ストレージ

変換(リサイズ、フォーマット変換)付きのアップロード/ダウンロード/プレビュー。共有可能なURL用のファイルトークン。HEIC、AVIF、WebPをサポート。 SDKがチャンク/並列チャンクアップロードを処理します。アップロードHTTPを手動で実装しないでください。

詳細:storage-files.md


Realtime

final sub = realtime.subscribe(['tablesdb.db.tables.posts.rows']);
sub.stream.listen((e) => print(e.events));

チャンネル: account | tablesdb.<DB>.tables.<TABLE>.rows | buckets.<BUCKET>.files | presences

チャンネルヘルパー(推奨): IDEオートコンプリート付きの型安全サブスクリプション用Channelクラス:

import { Client, Realtime, Channel, Query } from "appwrite";
const sub = await realtime.subscribe(
    Channel.tablesdb('<DB>').table('<TABLE>').row(),
    response => console.log(response.payload),
    [Query.equal('status', ['active'])]  // サーバーサイドフィルタリング
);

サポートされている場合は、オンライン/タイピング/アクティブ状態にPresences APIを使用。一時的なステータスのために、耐久性のあるDB行+クリーンアップcronは避けてください。

詳細:realtime.md


Functions

ハンドラーの外部でSDKを初期化。ドメインごとにグループ化。ポーリングではなくイベントトリガー。 Functions:セルフホスト版はルール2のDart固定を使用。Cloudは最新のSDK/ランタイムを使用。

詳細:functions.md | functions-advanced.md


トランザクション

final tx = await tablesDB.createTransaction(ttl: 300);
await tablesDB.createRow(..., transactionId: tx.$id);
await tablesDB.updateTransaction(transactionId: tx.$id, commit: true);

詳細:transactions.md


リレーションシップ

await tablesDB.listRows(databaseId: 'db', tableId: 'posts',
    queries: [Query.equal('author.country', 'US'), Query.select(['title', 'author.name'])]);

タイプ: oneToOne | oneToMany | manyToOne | manyToMany

詳細:relationships.md


パーミッション

permissions: [
    Permission.read(Role.any()),
    Permission.update(Role.user(userId)),
    Permission.delete(Role.team('admin')),
    Permission.create(Role.label('premium')),
]

デフォルト: 行/ファイルのパーミッションが設定されているか、テーブル/バケットから継承されていない限り、すべて拒否。 リソースごとのACLには行/ファイルパーミッションを使用。 すべてのリソースが同じルールを共有する場合は、テーブル/バケットのパーミッションを設定し、行/ファイルのパーミッションは空のままにします。 write = create + update + delete 回避すべきこと: パーミッションの欠落=ロックアウト。Role.any() + write/update/delete = 公開変更。機密データに対するPermission.read(Role.any()) = 公開漏洩。 ロール: any() | guests() | users() | user(id) | team(id) | team(id, role) | label(name) 詳細:permissions | teams | storage-files


制限

デフォルトページ:25 · 一括:1000行 · Query.equal():100値 · ネスト:3レベル · クエリ/リクエスト:100 · タイムアウト:15秒

エラーコード

400 不正なリクエスト · 401 認証エラー · 403 禁止 · 404 見つかりません · 409 競合 · 429 レート制限(クライアントSDKのみ) AppwriteExceptionをキャッチ。429 -> 指数バックオフ。

詳細:error-handling.md


アンチパターン

悪い例良い例理由
N+1クエリQuery.select(['col', 'relation.col'])余分なラウンドトリップを排除
読み取り-変更-書き込みOperator.increment()競合状態
大きなオフセットQuery.cursorAfter(id)O(n) vs O(1)
合計をスキップしないtotal: falseCOUNTスキャンを排除
インデックス欠落クエリ対象カラムに作成テーブル全体をスキャンするクエリ
ハンドラー内でSDK初期化ウォーム再利用のために外部で初期化呼び出しごとにセットアップが繰り返される
ハードコードされたシークレット環境変数セキュリティリスク
ポーリングRealtimeまたはイベントトリガー無駄な実行
クライアントサイドフィルタリングRealtimeクエリサーバーが処理を行う
生のチャンネル文字列Channelヘルパータイプミス、オートコンプリートなし
ColumnStringColumnVarcharまたはColumnTextstringは非推奨
手書きの型appwrite generateスキーマドリフト、オートコンプリートなし
databases.listDocuments()tablesDB.listRows()非推奨API
生のAppwrite HTTP(fetch、requests、dio、package:http、curl)公式SDKパッケージバージョンドリフト、認証ミス、型付きAPIの喪失
カスタム/ハードコードされた一意識別子ID.unique()オーバーフローリスク、情報漏洩、衝突
毎回の同期で全データ再取得Query.updatedAfter() + テーブルごとのタイムスタンプ帯域幅の無駄、遅い
createRow()のループ一括createRows()Nリクエスト vs 1

コスト最適化

  1. Query.select() — 帯域幅を削減
  2. カーソルページネーション + total: false — 最速のクエリ
  3. ポーリングよりRealtime — 1つの接続 vs 繰り返しの呼び出し
  4. イベントトリガー — 関数の実行回数を削減
  5. 一括操作 — リクエスト数を削減
  6. アトミック演算子 — 再試行ループを排除
  7. 適切なカラムタイプ — varchar(フルインデックス)対text(プレフィックスのみ)
  8. サーバーサイドフィルタリング — Realtimeクエリでクライアント転送データを削減
  9. デルタ同期 — 変更された行のみをフェッチ
  10. appwrite generate — コンパイル時エラーの早期発見により、ランタイムコストのかかる障害を防止

詳細:cost-optimization.md


メッセージング

プッシュ通知、メール、SMS。トピップベース。キューイング。プロバイダー(FCM、APNs、SMTP、Twilio、Vonageなど)。 重要なルール: サブスクライバーIDにはID.unique()を使用。Query.select()で効率的なサブスクライバー取得。

// サブスクリプション作成
await messaging.createSubscriber(topicId: 'updates', subscriberId: ID.unique(), targetId: target.$id);
// メッセージ送信
await messaging.createPush(
  topicId: 'updates',
  title: 'Hello',
  body: 'Push notification body',
);

詳細:messaging.md


エッジケースとよくある問題

  1. パーミッションエラー(403):Role.any()とwrite/update/deleteの組み合わせは公開変更を許可します。適切なPermission.read(Role.user(userId))を使用。
  2. レート制限(429):クライアントSDKは自動的に指数バックオフを処理します。手動のfetch呼び出しは処理しません。
  3. IDの衝突:ID.unique()で防止。カスタムIDは衝突が発生する可能性があります。
  4. 非推奨API:databases.listDocuments()は機能しますが、1.8.0以降はtablesDB.listRows()に置き換えられました。
  5. トランザクションのタイムアウト:createTransactionのttlパラメータはデフォルトで300秒(5分)ですが、必要に応じて調整できます。
  6. クエリの制限:Query.equal()は最大100値。それ以上はチャンククエリが必要(chunked-queries.mdを参照)。
  7. リレーションシップのネスト:最大3レベル。author.profile.avatarは3レベルとみなされます。
  8. バケット/テーブル名:安全な識別子(アルファベット、数字、アンダースコア)を使用。空白や特殊文字は避けてください。
  9. 環境の切り替え:.env.appwrite.localでエンドポイント/プロジェクトを切り替え。CLI設定の切り替えにはappwrite client --resetを使用。
  10. Functionsのデプロイ:SDKをハンドラーの外で初期化。ランタイムとSDKバージョンが一致していることを確認。

リファレンス

関連スキル