Communitygithub.com

sgaabdu4/appwrite-backend

Appwrite BaaS-Fähigkeit für KI-Agenten. Deckt TablesDB, Auth, Storage, Functions, Messaging und Realtime in Dart, Python und TypeScript ab.

Was ist appwrite-backend?

Diese Fähigkeit befähigt KI-Agenten (wie Claude Code, Cursor oder Codex), umfassend mit Appwrite zu interagieren, einer Open-Source-Backend-as-a-Service-Plattform. Sie bietet klare Richtlinien und Codebeispiele für die Kernfunktionen von Appwrite: TablesDB (ehemals Collections) für NoSQL-Datenbankoperationen, Authentifizierung (E-Mail, OAuth, Magic Link, etc.), Datei-Speicher mit Transformationen, serverlose Functions, Echtzeit-Abonnements via WebSockets und Nachrichtenübermittlung. Die Fähigkeit unterstützt die offiziellen SDKs für Dart/Flutter, TypeScript und Python und enthält kritische Regeln, die häufige Fehler wie die Verwendung von veralteten APIs, N+1-Abfragen und fehlenden Index verhindern. Sie enthält außerdem ausführliche Referenzen zu Query-Operatoren, atomaren Aktualisierungen, Berechtigungen, Transaktionen und Leistungsoptimierung und ist damit ein umfassendes Werkzeug für die Entwicklung mit Appwrite.

Funktioniert mit~Claude Code~Codex CLI✓Cursor
npx skills add sgaabdu4/appwrite-backend

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

Appwrite-Entwicklung

Kritische Regeln

  1. 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, curl usw. sind ein Verstoß, es sei denn, dem SDK fehlt der Endpunkt oder ein isolierter, getesteter Client.call umgeht das SDK-Modell-Parsing.
  2. SDKs nach Zielsystem festlegen — Cloud: neuestes stabiles SDK. Self-Hosted 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 verwenden — Collections-API seit 1.8.0 veraltet.
  4. 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.
  5. Query.select() verwenden — Beziehungen geben ohne explizite Auswahl nur IDs zurück.
  6. Cursor-Paginierung verwenden — Offset verschlechtert die Leistung bei großen Tabellen.
  7. Operator für Zähler verwenden — Vermeidet Wettlaufsituationen.
  8. Indizes erstellen — Abfragen ohne Indizes durchsuchen gesamte Tabellen.
  9. Initialisierung außerhalb des Handlers — SDK/Verbindungen bleiben zwischen Warmstart-Invocationen bestehen.
  10. Funktionen nach Domäne gruppieren — Eine pro Domäne, nicht pro Operation.
  11. Ereignis-Trigger anstelle von Polling — Ein Trigger ersetzt Tausende von Anfragen.
  12. Explizite String-Typen verwenden — string veraltet; verwenden Sie varchar oder text/mediumtext/longtext.
  13. appwrite generate verwenden — Typsicheres SDK aus dem Schema.
  14. Channel-Helfer verwenden — Typsichere Echtzeit-Abonnements, keine rohen Strings.
  15. Realtime-Abfragen verwenden — Serverseitige Ereignisfilterung, nicht clientseitig.
  16. 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:

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+)

AltNeu
CollectionsTables
DocumentsRows
AttributesColumns
DatabasesTablesDB

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: appwrite für Flutter/Client-Apps, dart_appwrite fü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

TypMax. ZeichenIndizierungVerwendung
varchar16.383Vollständig (wenn Größe < 768)Abfragbare kurze Zeichenfolgen
text16.383Nur PräfixBeschreibungen, Notizen
mediumtext4.194.303Nur PräfixArtikel
longtext1.073.741.823Nur PräfixGroße Dokumente

string veraltet. Verwenden Sie varchar für abfragbare und text für nicht indizierte Felder.

Sonstige: integer | float | boolean | datetime | email | url | ip | enum | relationship | point | line | polygon

Details: schema-management.md


Leistung

RegelAuswirkung
Cursor-Paginierung10-100x schneller als Offset
Paginierungs-Mixin (Dart)~50 Zeilen pro Datenquelle gespart
Query.select()12-18x schneller bei Beziehungen
total: falseEliminiert COUNT-Scan
Indizes100x schneller bei großen Tabellen
OperatorenKeine Wettlaufsituationen
MassenoperationenN → 1 Anfrage
Delta-SyncRuft 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

FalschRichtigWarum
N+1-AbfragenQuery.select(['col', 'relation.col'])Eliminiert zusätzliche Roundtrips
Lesen-Ändern-SchreibenOperator.increment()Wettlaufsituation
Große OffsetsQuery.cursorAfter(id)O(n) vs. O(1)
Summen überspringentotal: falseEliminiert COUNT-Scan
Fehlende IndizesFür abgefragte Spalten erstellenAbfragen durchsuchen gesamte Tabelle
SDK-Initialisierung im HandlerAußerhalb für Warmwiederverwendung initialisierenWiederholte Einrichtung pro Aufruf
Hartcodierte GeheimnisseUmgebungsvariablenSicherheitsrisiko
PollingEchtzeit- oder Ereignis-TriggerVerschwendete Ausführungen
Clientseitige FilterungEchtzeit-AbfragenServer erledigt die Arbeit
Rohe Kanal-StringsChannel-HelferTippfehler, keine Autovervollständigung
ColumnStringColumnVarchar oder ColumnTextstring veraltet
Manuelles Schreiben von Typenappwrite generateSchema-Drift, keine Autovervollständigung
databases.listDocuments()tablesDB.listRows()Veraltete API
Rohes Appwrite-HTTP (fetch, requests, dio, package:http, curl)Offizielles SDK-PaketVersionsdrift, Authentifizierungsfehler, verlorene typisierte APIs
Benutzerdefinierte/hartcodierte eindeutige IDsID.unique()Überlaufrisiko, Informationsleck, Kollisionen
Vollständiger Neuabruf bei jedem SyncQuery.updatedAfter() + tabellenweise ZeitstempelVerschwendet Bandbreite, langsam
Schleife mit createRow()createRows() MassenoperationN Anfragen vs. 1

Kostenoptimierung

  1. Query.select() — reduziert Bandbreite
  2. Cursor-Paginierung + total: false — schnellste Abfragen
  3. Echtzeit statt Polling — eine Verbindung vs. wiederholte Aufrufe
  4. Massenoperationen — N Anfragen reduziert auf 1
  5. Operatoren — keine Wettlaufsituationen, eine Anfrage
  6. Delta-Sync — nur geänderte Zeilen abrufen
  7. Indizes — 100x schneller bei großen Tabellen
  8. Ereignis-Trigger — nur bei Bedarf ausführen

Nächste Schritte

Verwandte Skills