Appwrite 開発
重要なルール
- 公式SDKパッケージのみを使用 — Dart/Flutter/TypeScript/Pythonはsdk-routingに従うこと。SDKがエンドポイントを欠いているか、分離・テスト済みの
Client.callがSDKのモデルパースを回避しない限り、fetch、requests、dio、package:http、curlなどを介した生のREST/GraphQL HTTPは違反です。 - ターゲットに応じてSDKを固定 — Cloud:最新安定版SDK。セルフホスト版
1.9.x:dart_appwrite25.1.0、Flutterappwrite25.2.0、node-appwrite26.2.0、Webappwrite26.1.0、Pythonappwrite21.0.0、CLI 22.4.0。 - TablesDB APIを使用 — Collections APIは1.8.0で非推奨
- すべての一意識別子に
ID.unique()を使用 — 行ID(rowId:)、ファイルID、ユーザーID、チームID、Webhook ID、メッセージID、サブスクライバーID、およびカラム内のエンティティID。ハードコードされた一意識別子、カスタムジェネレーター、名前、タイムスタンプ、スラッグをIDとして使用しないでください。これらはカラム制限を超過し、データを漏洩させます。安定したナチュラルキーは、インデックス付きカラムとしてのみ使用してください。 Query.select()を使用 — リレーションシップは明示的な選択なしではIDのみを返します。- カーソルページネーションを使用 — オフセットは大規模テーブルではパフォーマンスが低下します
- カウンターにはOperatorを使用 — 競合状態を回避します
- インデックスを作成 — クエリがないとテーブル全体をスキャンします
- ハンドラーの外部で初期化 — SDK/接続はウォーム呼び出し間で持続します
- ドメインごとに関数をグループ化 — 操作ごとではなく、ドメインごとに1つ
- ポーリングよりもイベントトリガー — 1つのトリガーが数千のリクエストを置き換えます
- 明示的な文字列タイプを使用 —
stringは非推奨。varcharまたはtext/mediumtext/longtextを使用 appwrite generateを使用 — スキーマから型安全なSDKを生成- チャネルヘルパーを使用 — 型安全なリアルタイムサブスクリプション、生の文字列は不使用
- Realtimeクエリを使用 — サーバーサイドのイベントフィルタリング、クライアントサイドではない
- 長時間実行関数を非同期で開始 — 削除/同期/インポート/エクスポート/マイグレーション/生成フローでは、クライアント
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以降)
| 旧 | 新 |
|---|---|
| Collections | Tables |
| Documents | Rows |
| Attributes | Columns |
| Databases | TablesDB |
セットアップ
パッケージポリシー:
- 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
カラムタイプ
| タイプ | 最大文字数 | インデックス | 用途 |
|---|---|---|---|
varchar | 16,383 | フル(サイズ < 768の場合) | クエリ可能な短い文字列 |
text | 16,383 | プレフィックスのみ | 説明、メモ |
mediumtext | 4,194,303 | プレフィックスのみ | 記事 |
longtext | 1,073,741,823 | プレフィックスのみ | 大きなドキュメント |
stringは非推奨。 クエリ可能な場合はvarcharを、インデックス不要の場合はtextを使用してください。
その他: integer | float | boolean | datetime | email | url | ip | enum | relationship | point | line | polygon
パフォーマンス
| ルール | 影響 |
|---|---|
| カーソルページネーション | オフセットより10〜100倍高速 |
| ページネーションミックスイン(Dart) | データソースあたり約50行節約 |
Query.select() | リレーションシップで12〜18倍高速 |
total: false | COUNTスキャンを排除 |
| インデックス | 大規模テーブルで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を手動で実装しないでください。
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);
リレーションシップ
await tablesDB.listRows(databaseId: 'db', tableId: 'posts',
queries: [Query.equal('author.country', 'US'), Query.select(['title', 'author.name'])]);
タイプ: oneToOne | oneToMany | manyToOne | manyToMany
パーミッション
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 -> 指数バックオフ。
アンチパターン
| 悪い例 | 良い例 | 理由 |
|---|---|---|
| N+1クエリ | Query.select(['col', 'relation.col']) | 余分なラウンドトリップを排除 |
| 読み取り-変更-書き込み | Operator.increment() | 競合状態 |
| 大きなオフセット | Query.cursorAfter(id) | O(n) vs O(1) |
| 合計をスキップしない | total: false | COUNTスキャンを排除 |
| インデックス欠落 | クエリ対象カラムに作成 | テーブル全体をスキャンするクエリ |
| ハンドラー内でSDK初期化 | ウォーム再利用のために外部で初期化 | 呼び出しごとにセットアップが繰り返される |
| ハードコードされたシークレット | 環境変数 | セキュリティリスク |
| ポーリング | Realtimeまたはイベントトリガー | 無駄な実行 |
| クライアントサイドフィルタリング | Realtimeクエリ | サーバーが処理を行う |
| 生のチャンネル文字列 | Channelヘルパー | タイプミス、オートコンプリートなし |
ColumnString | ColumnVarcharまたはColumnText | stringは非推奨 |
| 手書きの型 | 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 |
コスト最適化
Query.select()— 帯域幅を削減- カーソルページネーション +
total: false— 最速のクエリ - ポーリングよりRealtime — 1つの接続 vs 繰り返しの呼び出し
- イベントトリガー — 関数の実行回数を削減
- 一括操作 — リクエスト数を削減
- アトミック演算子 — 再試行ループを排除
- 適切なカラムタイプ —
varchar(フルインデックス)対text(プレフィックスのみ) - サーバーサイドフィルタリング — Realtimeクエリでクライアント転送データを削減
- デルタ同期 — 変更された行のみをフェッチ
appwrite generate— コンパイル時エラーの早期発見により、ランタイムコストのかかる障害を防止
メッセージング
プッシュ通知、メール、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
エッジケースとよくある問題
- パーミッションエラー(
403):Role.any()とwrite/update/deleteの組み合わせは公開変更を許可します。適切なPermission.read(Role.user(userId))を使用。 - レート制限(
429):クライアントSDKは自動的に指数バックオフを処理します。手動のfetch呼び出しは処理しません。 - IDの衝突:
ID.unique()で防止。カスタムIDは衝突が発生する可能性があります。 - 非推奨API:
databases.listDocuments()は機能しますが、1.8.0以降はtablesDB.listRows()に置き換えられました。 - トランザクションのタイムアウト:
createTransactionのttlパラメータはデフォルトで300秒(5分)ですが、必要に応じて調整できます。 - クエリの制限:
Query.equal()は最大100値。それ以上はチャンククエリが必要(chunked-queries.mdを参照)。 - リレーションシップのネスト:最大3レベル。
author.profile.avatarは3レベルとみなされます。 - バケット/テーブル名:安全な識別子(アルファベット、数字、アンダースコア)を使用。空白や特殊文字は避けてください。
- 環境の切り替え:
.env.appwrite.localでエンドポイント/プロジェクトを切り替え。CLI設定の切り替えにはappwrite client --resetを使用。 - Functionsのデプロイ:SDKをハンドラーの外で初期化。ランタイムとSDKバージョンが一致していることを確認。