Appwrite-Entwicklung
Kritische Regeln
- Nur offizielle SDK-Pakete verwenden — Dart/Flutter/TypeScript/Python müssen sdk-routing verwenden. Rohe REST/GraphQL-HTTP-Anfragen über
fetch,requests,dio,package:http,curlusw. sind ein Verstoß, es sei denn, dem SDK fehlt der Endpunkt oder ein isolierter, getesteterClient.callumgeht das SDK-Modell-Parsing. - SDKs nach Zielsystem festlegen — Cloud: neuestes stabiles SDK. Self-Hosted
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 verwenden — Collections-API seit 1.8.0 veraltet.
ID.unique()für alle eindeutigen IDs verwenden — Zeilen-IDs (rowId:), Datei-IDs, Benutzer-IDs, Team-IDs, Webhook-IDs, Nachrichten-IDs, Abonnenten-IDs und Entitäts-IDs in Spalten. Keine fest codierten eindeutigen IDs, benutzerdefinierten Generatoren, Namen, Zeitstempel oder Slugs-als-IDs; sie überschreiten Spaltenlimits und geben Daten preis. Verwenden Sie stabile natürliche Schlüssel nur als indizierte Spalten.- Query.select() verwenden — Beziehungen geben ohne explizite Auswahl nur IDs zurück.
- Cursor-Paginierung verwenden — Offset verschlechtert die Leistung bei großen Tabellen.
- Operator für Zähler verwenden — Vermeidet Wettlaufsituationen.
- Indizes erstellen — Abfragen ohne Indizes durchsuchen gesamte Tabellen.
- Initialisierung außerhalb des Handlers — SDK/Verbindungen bleiben zwischen Warmstart-Invocationen bestehen.
- Funktionen nach Domäne gruppieren — Eine pro Domäne, nicht pro Operation.
- Ereignis-Trigger anstelle von Polling — Ein Trigger ersetzt Tausende von Anfragen.
- Explizite String-Typen verwenden —
stringveraltet; verwenden Sievarcharodertext/mediumtext/longtext. appwrite generateverwenden — Typsicheres SDK aus dem Schema.- Channel-Helfer verwenden — Typsichere Echtzeit-Abonnements, keine rohen Strings.
- Realtime-Abfragen verwenden — Serverseitige Ereignisfilterung, nicht clientseitig.
- Asynchronen Start von langlebigen Funktionen — Client
createExecution-Aufrufe für Lösch-/Sync-/Import-/Export-/Migrieren-/Generieren-Abläufe verwenden asynchrone Ausführung, dann den Wahrheitsquellen-Status mit begrenztem Polling/Realtime/Fetch abgleichen. Nicht auf die Backend-Fertigstellung warten; destruktive Fehler erst melden, nachdem der Abgleich bestätigt hat, dass die Entität/das Konto noch existiert.
CLI-Schnellcheck (Oben)
Verwenden Sie eine repo-lokale, ignorierte .env.appwrite.local pro Projekt; vertrauen Sie nicht der globalen CLI-Konfiguration.
# .env.appwrite.local (gitignoriert)
APPWRITE_ENDPOINT=https://<endpoint>/v1
APPWRITE_PROJECT_ID=<project_id>
APPWRITE_API_KEY=standard_...
# Verwenden Sie "cloud" oder die Self-Hosted-Serverzeile.
APPWRITE_SERVER_VERSION=cloud
CLI-Versionsrichtlinie:
- Appwrite Cloud: neueste
appwrite-cli. - Self-Hosted Appwrite
1.9.x:[email protected].
Vor der Arbeit mit der 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 "Nicht unterstützte APPWRITE_SERVER_VERSION=$APPWRITE_SERVER_VERSION; wählen Sie eine passende CLI, bevor Sie fortfahren."
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 muss den erwarteten Endpunkt/das erwartete Projekt und einen maskierten Schlüssel anzeigen, bevor fortgefahren wird. Falls nicht vorhanden, nach Endpunkt, Projekt-ID, API-Schlüssel und Serverversion fragen.
Regeln: appwrite.config.json = lokale Projektkonfiguration. appwrite client ... = globale Überschreibung (nicht interaktiv). Überschreibung löschen: appwrite client --reset. CLI-Hilfs-Flags variieren je nach Version; falls nicht verfügbar, rohes --queries verwenden oder einfache Tabellenausgabe für schnelle Statusprüfungen parsen.
Details: appwrite-cli
Terminologie (1.8.0+)
| Alt | Neu |
|---|---|
| Collections | Tables |
| Documents | Rows |
| Attributes | Columns |
| Databases | TablesDB |
Einrichtung
Paketrichtlinie:
- Cloud: Neuestes stabiles offizielles SDK.
- Self-Hosted
1.9.x: Pins aus kritischer Regel 2 verwenden. - TypeScript/React-Browser:
appwrite; TypeScript-Server/SSR/Functions:node-appwrite. - Python:
appwrite; bevorzugt Schlüsselwortargumente für SDK-Aufrufe. - Dart:
appwritefür Flutter/Client-Apps,dart_appwritefür Server/Functions; benannte Parameter bevorzugen.
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
// Erstellen
await tablesDB.createRow(databaseId: 'db', tableId: 'users', rowId: ID.unique(),
data: {'name': 'Alice'});
// Lesen
final rows = await tablesDB.listRows(databaseId: 'db', tableId: 'users',
queries: [Query.equal('status', 'active'), Query.select(['name', 'email'])]);
// Aktualisieren
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'});
// Löschen
await tablesDB.deleteRow(databaseId: 'db', tableId: 'users', rowId: 'user_123');
SDK-Idiome verwenden:
- TypeScript verwendet Objektparameter:
tablesDB.createRow({ databaseId, tableId, rowId, data }). - Python verwendet Schlüsselwortargumente:
tables_db.create_row(database_id='db', table_id='users', row_id=ID.unique(), data={...}). - Dart verwendet benannte Parameter wie oben gezeigt.
Massenoperationen: bulk-operations.md | Segmentierte ID-Abfragen: chunked-queries.md
Query-Referenz
Vergleich: equal | notEqual | lessThan | lessThanEqual | greaterThan | greaterThanEqual | between | notBetween
String: startsWith | endsWith | contains | search (+ not-Varianten)
Null: isNull | isNotNull · Logisch: and([...]) | or([...])
Paginierung: select | limit | cursorAfter | cursorBefore | orderAsc | orderDesc | orderRandom
Zeitstempel: createdAfter | createdBefore | updatedAfter | updatedBefore
Räumlich: distanceEqual | distanceLessThan | distanceGreaterThan | intersects | overlaps | touches | crosses (+ not-Varianten)
Alle mit Query.-Präfix. Details: query-optimization.md
Operatoren (Atomare Aktualisierungen)
data: {
'likes': Operator.increment(1),
'tags': Operator.arrayAppend(['trending']),
'updatedAt': Operator.dateSetNow(),
}
Numerisch: increment | decrement | multiply | divide
Array: arrayAppend | arrayPrepend | arrayRemove | arrayUnique | arrayIntersect | arrayDiff
Sonstige: toggle | stringConcat | stringReplace | dateAddDays | dateSetNow
Details: atomic-operators.md
Spaltentypen
| Typ | Max. Zeichen | Indizierung | Verwendung |
|---|---|---|---|
varchar | 16.383 | Vollständig (wenn Größe < 768) | Abfragbare kurze Zeichenfolgen |
text | 16.383 | Nur Präfix | Beschreibungen, Notizen |
mediumtext | 4.194.303 | Nur Präfix | Artikel |
longtext | 1.073.741.823 | Nur Präfix | Große Dokumente |
stringveraltet. Verwenden Sievarcharfür abfragbare undtextfür nicht indizierte Felder.
Sonstige: integer | float | boolean | datetime | email | url | ip | enum | relationship | point | line | polygon
Details: schema-management.md
Leistung
| Regel | Auswirkung |
|---|---|
| Cursor-Paginierung | 10-100x schneller als Offset |
| Paginierungs-Mixin (Dart) | ~50 Zeilen pro Datenquelle gespart |
Query.select() | 12-18x schneller bei Beziehungen |
total: false | Eliminiert COUNT-Scan |
| Indizes | 100x schneller bei großen Tabellen |
| Operatoren | Keine Wettlaufsituationen |
| Massenoperationen | N → 1 Anfrage |
| Delta-Sync | Ruft nur geänderte Zeilen ab |
Details: performance.md, pagination-performance.md
Typsichere SDK-Generierung
appwrite generate
Generiert typisierte Helfer aus dem Schema in generated/appwrite/. Autovervollständigung + Compiler-Prüfungen. Nach Schemaänderung neu generieren.
CLI-Ablauf: login -> init project -> pull -> generate -> push. Details: appwrite-cli
Authentifizierung
E-Mail/Passwort, OAuth (50+ Anbieter), Telefon, Magic Link, anonym, E-Mail-OTP, benutzerdefiniertes Token. MFA: TOTP/E-Mail/Telefon/Wiederherstellung. SSR-Sitzungen. JWT für Funktionen.
SSR-Cookie: a_session_<PROJECT_ID>. Admin-Client erstellt Sitzung. Pro-Anfrage-Sitzungs-Client liest Benutzerkontext.
E-Mail-Richtlinien können kostenlose, aliasierte oder wegwerfbare E-Mails bei Registrierung/Aktualisierung blockieren.
Details: authentication.md | auth-methods.md
Speicher
Hochladen/Herunterladen/Vorschau mit Transformationen (Größe ändern, Formatkonvertierung). Datei-Token für teilbare URLs. HEIC, AVIF, WebP unterstützt. SDKs handhaben Chunking/parallele Chunk-Uploads; keine manuellen Upload-HTTP-Implementierungen.
Details: storage-files.md
Echtzeit
final sub = realtime.subscribe(['tablesdb.db.tables.posts.rows']);
sub.stream.listen((e) => print(e.events));
Kanäle: account | tablesdb.<DB>.tables.<TABLE>.rows | buckets.<BUCKET>.files | presences
Kanal-Helfer (bevorzugt): Channel-Klasse für typsichere Abos mit IDE-Autovervollständigung:
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'])] // serverseitige Filterung
);
Verwenden Sie die Anwesenheits-API für Online-/Tipp-/Aktivitätsstatus, wenn unterstützt; vermeiden Sie dauerhafte DB-Zeilen + Bereinigungs-Cron für flüchtige Status.
Details: realtime.md
Funktionen
SDK außerhalb des Handlers initialisieren. Nach Domäne gruppieren. Ereignis-Trigger, kein Polling. Funktionen: Self-Hosted verwendet Dart-Pin aus Regel 2; Cloud verwendet neuestes SDK/Laufzeit.
Details: functions.md | functions-advanced.md
Transaktionen
final tx = await tablesDB.createTransaction(ttl: 300);
await tablesDB.createRow(..., transactionId: tx.$id);
await tablesDB.updateTransaction(transactionId: tx.$id, commit: true);
Details: transactions.md
Beziehungen
await tablesDB.listRows(databaseId: 'db', tableId: 'posts',
queries: [Query.equal('author.country', 'US'), Query.select(['title', 'author.name'])]);
Typen: oneToOne | oneToMany | manyToOne | manyToMany
Details: relationships.md
Berechtigungen
permissions: [
Permission.read(Role.any()),
Permission.update(Role.user(userId)),
Permission.delete(Role.team('admin')),
Permission.create(Role.label('premium')),
]
Standard: Alles verweigern, es sei denn, Zeilen-/Dateiberechtigungen sind gesetzt oder von der Tabelle/dem Bucket geerbt.
Zeilen-/Dateiberechtigungen für Pro-Ressource-ACL verwenden. Wenn alle Ressourcen dieselben Regeln teilen, Tabellen-/Bucket-Berechtigungen setzen, Zeilen-/Dateiberechtigungen leer lassen.
write = create + update + delete
Vermeiden: Fehlende Berechtigungen = Aussperrung; Role.any() + write/update/delete = öffentliche Mutation; Permission.read(Role.any()) bei sensiblen Daten = öffentliches Leck.
Rollen: any() | guests() | users() | user(id) | team(id) | team(id, role) | label(name)
Details: permissions | teams | storage-files
Limits
Standardseite: 25 · Massenoperation: 1000 Zeilen · Query.equal(): 100 Werte · Verschachtelungstiefe: 3 Ebenen · Abfragen/Anfrage: 100 · Zeitüberschreitung: 15 s
Fehlercodes
400 Ungültige Anfrage · 401 Nicht autorisiert · 403 Verboten · 404 Nicht gefunden · 409 Konflikt · 429 Rate limitiert (nur Client-SDKs)
AppwriteException abfangen. Bei 429 -> exponentielles Backoff.
Details: error-handling.md
Anti-Patterns
| Falsch | Richtig | Warum |
|---|---|---|
| N+1-Abfragen | Query.select(['col', 'relation.col']) | Eliminiert zusätzliche Roundtrips |
| Lesen-Ändern-Schreiben | Operator.increment() | Wettlaufsituation |
| Große Offsets | Query.cursorAfter(id) | O(n) vs. O(1) |
| Summen überspringen | total: false | Eliminiert COUNT-Scan |
| Fehlende Indizes | Für abgefragte Spalten erstellen | Abfragen durchsuchen gesamte Tabelle |
| SDK-Initialisierung im Handler | Außerhalb für Warmwiederverwendung initialisieren | Wiederholte Einrichtung pro Aufruf |
| Hartcodierte Geheimnisse | Umgebungsvariablen | Sicherheitsrisiko |
| Polling | Echtzeit- oder Ereignis-Trigger | Verschwendete Ausführungen |
| Clientseitige Filterung | Echtzeit-Abfragen | Server erledigt die Arbeit |
| Rohe Kanal-Strings | Channel-Helfer | Tippfehler, keine Autovervollständigung |
ColumnString | ColumnVarchar oder ColumnText | string veraltet |
| Manuelles Schreiben von Typen | appwrite generate | Schema-Drift, keine Autovervollständigung |
databases.listDocuments() | tablesDB.listRows() | Veraltete API |
Rohes Appwrite-HTTP (fetch, requests, dio, package:http, curl) | Offizielles SDK-Paket | Versionsdrift, Authentifizierungsfehler, verlorene typisierte APIs |
| Benutzerdefinierte/hartcodierte eindeutige IDs | ID.unique() | Überlaufrisiko, Informationsleck, Kollisionen |
| Vollständiger Neuabruf bei jedem Sync | Query.updatedAfter() + tabellenweise Zeitstempel | Verschwendet Bandbreite, langsam |
Schleife mit createRow() | createRows() Massenoperation | N Anfragen vs. 1 |
Kostenoptimierung
Query.select()— reduziert Bandbreite- Cursor-Paginierung +
total: false— schnellste Abfragen - Echtzeit statt Polling — eine Verbindung vs. wiederholte Aufrufe
- Massenoperationen — N Anfragen reduziert auf 1
- Operatoren — keine Wettlaufsituationen, eine Anfrage
- Delta-Sync — nur geänderte Zeilen abrufen
- Indizes — 100x schneller bei großen Tabellen
- Ereignis-Trigger — nur bei Bedarf ausführen