Communitygithub.com

sgaabdu4/appwrite-backend

Compétence Appwrite BaaS pour agents IA. Couvre TablesDB, Auth, Storage, Functions, Messaging et Realtime en Dart, Python et TypeScript.

Qu'est-ce que appwrite-backend ?

Cette compétence permet à un agent IA (comme Claude Code, Cursor, Codex ou tout autre éditeur ou CLI basé sur un modèle de langage) d'interagir avec Appwrite en tant que Backend-as-a-Service (BaaS). Elle fournit des directives précises sur l'utilisation des SDK officiels (Dart/Flutter, TypeScript, Python), la gestion de la base de données via l'API TablesDB (remplaçante de l'API Collections), l'authentification, le stockage, les fonctions serverless, la messagerie, le temps réel, les transactions, les relations et les permissions. L'agent doit impérativement suivre des règles strictes : utiliser `ID.unique()` pour tous les identifiants, privilégier la pagination par curseur plutôt que par offset, créer des index pour les colonnes interrogées, initialiser le SDK en dehors du handler des fonctions, et éviter les appels HTTP REST directs. Le markdown de la compétence inclut des extraits de code prêts à l'emploi pour les opérations CRUD, les requêtes, les opérateurs atomiques, et la génération de SDK type-safe, avec des références vers des fichiers détaillés pour chaque sous-domaine.

Compatible avec~Claude Code~Codex CLI✓Cursor
npx skills add sgaabdu4/appwrite-backend

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

Développement Appwrite

Règles critiques

  1. Utiliser uniquement les SDK officiels — Dart/Flutter/TypeScript/Python doivent utiliser sdk-routing. Les appels REST/GraphQL bruts via fetch, requests, dio, package:http, curl, etc. sont une violation, sauf si le SDK ne fournit pas le point d'accès ou qu'un Client.call isolé et testé contourne le parsing du modèle SDK.
  2. Épingler les SDK par cible — Cloud : dernier SDK stable. Auto-hébergé 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. Utiliser l'API TablesDB — L'API Collections est dépréciée depuis 1.8.0.
  4. Utiliser ID.unique() pour tous les identifiants uniques — Identifiants de lignes (rowId:), de fichiers, d'utilisateurs, d'équipes, de webhooks, de messages, d'abonnés et d'entités dans les colonnes. Pas d'identifiants uniques codés en dur, de générateurs personnalisés, de noms, d'horodatages ou de slugs comme identifiants ; ils dépassent les limites des colonnes et fuient des données. Utilisez des clés naturelles stables uniquement comme colonnes indexées.
  5. Utiliser Query.select() — Les relations ne renvoient que des identifiants sans sélection explicite.
  6. Utiliser la pagination par curseur — L'offset se dégrade sur les grandes tables.
  7. Utiliser Operator pour les compteurs — Évite les conditions de compétition.
  8. Créer des index — Les requêtes sans index parcourent l'intégralité des tables.
  9. Initialiser en dehors du handler — Les SDK/connexions persistent entre les invocations à chaud.
  10. Regrouper les fonctions par domaine — Une par domaine, pas par opération.
  11. Déclencheurs d'événements plutôt que du polling — Un seul déclencheur remplace des milliers de requêtes.
  12. Utiliser des types de chaîne explicites — string est déprécié ; utilisez varchar ou text/mediumtext/longtext.
  13. Utiliser appwrite generate — SDK type-safe à partir du schéma.
  14. Utiliser les helpers Channel — Abonnements temps réel type-safe, pas de chaînes brutes.
  15. Utiliser les requêtes temps réel — Filtrage d'événements côté serveur, pas côté client.
  16. Démarrer de manière asynchrone les fonctions longues — Les appels clients createExecution pour les flux de suppression/synchronisation/import/export/migration/génération utilisent une exécution asynchrone, puis réconcilient l'état source de vérité avec un polling/Realtime/fetch limité. Ne pas bloquer sur l'achèvement du backend ; signaler les échecs destructeurs uniquement après que la réconciliation prouve que l'entité/compte existe toujours.

Vérification rapide CLI (En haut)

Utiliser un .env.appwrite.local ignoré par le dépôt par projet ; ne pas se fier à la configuration globale du CLI.

# .env.appwrite.local (gitignoré)
APPWRITE_ENDPOINT=https://<endpoint>/v1
APPWRITE_PROJECT_ID=<project_id>
APPWRITE_API_KEY=standard_...
# Utilisez "cloud" ou la ligne du serveur auto-hébergé.
APPWRITE_SERVER_VERSION=cloud

Politique de version CLI :

  • Appwrite Cloud : dernier appwrite-cli.
  • Appwrite auto-hébergé 1.9.x : [email protected].

Avant le travail avec le CLI Appwrite :

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 "Version APPWRITE_SERVER_VERSION=$APPWRITE_SERVER_VERSION non prise en charge ; choisissez un CLI correspondant avant de continuer."
    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 doit montrer le point d'accès/projet attendu et une clé masquée avant de continuer. Si absent, demander le point d'accès, l'ID du projet, la clé API et la version du serveur.

Règles : appwrite.config.json = configuration du projet local. appwrite client ... = remplacement global (non interactif). Effacer le remplacement : appwrite client --reset. Les drapeaux d'aide du CLI varient selon la version ; si indisponibles, utilisez des --queries bruts ou analysez la sortie de tableau simple pour des vérifications rapides d'état. Détails : appwrite-cli

Terminologie (1.8.0+)

AncienNouveau
CollectionsTables
DocumentsLignes
AttributsColonnes
Bases de donnéesTablesDB

Configuration

Politique des packages :

  • Cloud : dernier SDK officiel stable.
  • Auto-hébergé 1.9.x : utiliser les épingles de la règle critique 2.
  • TypeScript/React (navigateur) : appwrite ; TypeScript serveur/SSR/Functions : node-appwrite.
  • Python : appwrite ; préférer les arguments nommés pour les appels SDK.
  • Dart : appwrite pour les applications Flutter/client, dart_appwrite pour le serveur/Functions ; préférer les paramètres nommés.
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);

CRUD TablesDB

// Créer
await tablesDB.createRow(databaseId: 'db', tableId: 'utilisateurs', rowId: ID.unique(),
    data: {'nom': 'Alice'});

// Lire
final lignes = await tablesDB.listRows(databaseId: 'db', tableId: 'utilisateurs',
    queries: [Query.equal('statut', 'actif'), Query.select(['nom', 'email'])]);

// Mettre à jour
await tablesDB.updateRow(databaseId: 'db', tableId: 'utilisateurs', rowId: 'utilisateur_123',
    data: {'statut': 'inactif'});

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

// Supprimer
await tablesDB.deleteRow(databaseId: 'db', tableId: 'utilisateurs', rowId: 'utilisateur_123');

Utiliser les idiomes du SDK :

  • TypeScript utilise des paramètres objet : tablesDB.createRow({ databaseId, tableId, rowId, data }).
  • Python utilise des arguments nommés : tables_db.create_row(database_id='db', table_id='utilisateurs', row_id=ID.unique(), data={...}).
  • Dart utilise des paramètres nommés comme ci-dessus.

En masse : bulk-operations.md | Requêtes d'ID par lots : chunked-queries.md


Référence des requêtes

Comparaison : equal | notEqual | lessThan | lessThanEqual | greaterThan | greaterThanEqual | between | notBetween Chaîne : startsWith | endsWith | contains | search (+ variantes not) Nul : isNull | isNotNull · Logique : and([...]) | or([...]) Pagination : select | limit | cursorAfter | cursorBefore | orderAsc | orderDesc | orderRandom Horodatage : createdAfter | createdBefore | updatedAfter | updatedBefore Spatial : distanceEqual | distanceLessThan | distanceGreaterThan | intersects | overlaps | touches | crosses (+ variantes not)

Tous préfixés par Query.. Détails : query-optimization.md


Opérateurs (Mises à jour atomiques)

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

Numériques : increment | decrement | multiply | divide Tableaux : arrayAppend | arrayPrepend | arrayRemove | arrayUnique | arrayIntersect | arrayDiff Autres : toggle | stringConcat | stringReplace | dateAddDays | dateSetNow

Détails : atomic-operators.md


Types de colonnes

TypeMax CaractèresIndexationUtilisation
varchar16 383Complète (si taille < 768)Chaînes courtes interrogeables
text16 383Préfixe uniquementDescriptions, notes
mediumtext4 194 303Préfixe uniquementArticles
longtext1 073 741 823Préfixe uniquementGrands documents

string est déprécié. Utilisez varchar pour les colonnes interrogeables, text pour les colonnes non indexées.

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

Détails : schema-management.md


Performances

RègleImpact
Pagination par curseur10 à 100 fois plus rapide que l'offset
Mixin de pagination (Dart)~50 lignes économisées par source de données
Query.select()12 à 18 fois plus rapide pour les relations
total: falseÉlimine le scan COUNT
Indexes100 fois plus rapide sur les grandes tables
OpérateursPas de conditions de compétition
Opérations en masseN → 1 requête
Synchronisation deltaRécupère uniquement les lignes modifiées

Détails : performance.md, pagination-performance.md


Génération de SDK type-safe

appwrite generate

Génère des helpers typés à partir du schéma dans generated/appwrite/. Auto-complétion + vérifications à la compilation. Régénérer après un changement de schéma. Flux CLI : login -> init project -> pull -> generate -> push. Détails : appwrite-cli


Authentification

Email/mot de passe, OAuth (50+ fournisseurs), téléphone, lien magique, anonyme, OTP par email, jeton personnalisé. MFA : TOTP/email/téléphone/récupération. Sessions SSR. JWT pour les fonctions. Cookie SSR : a_session_<PROJECT_ID>. Le client admin crée la session. Le client de session par requête lit le contexte utilisateur. Les politiques d'email peuvent bloquer les emails gratuits, aliasés ou jetables lors de l'inscription/mise à jour.

Détails : authentication.md | auth-methods.md


Stockage

Télécharger/télécharger/prévisualiser avec transformations (redimensionnement, conversion de format). Jetons de fichiers pour les URL partageables. HEIC, AVIF, WebP pris en charge. Les SDK gèrent le découpage/les téléchargements parallèles par morceaux ; ne pas faire de téléchargement HTTP manuel.

Détails : storage-files.md


Temps réel

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

Canaux : account | tablesdb.<DB>.tables.<TABLE>.rows | buckets.<BUCKET>.files | presences

Helpers de canal (recommandés) : classe Channel pour des abonnements type-safe avec auto-complétion IDE :

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'])]  // filtrage côté serveur
);

Utilisez l'API Presences pour l'état en ligne/typage/actif lorsqu'il est pris en charge ; évitez les lignes DB durables + une tâche de nettoyage pour un état éphémère.

Détails : realtime.md


Functions

Initialiser le SDK en dehors du handler. Regrouper par domaine. Déclencheurs d'événements, pas de polling. Functions : auto-hébergé utilise l'épingle Dart de la règle 2 ; Cloud utilise le SDK/runtime le plus récent.

Détails : functions.md | functions-advanced.md


Transactions

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

Détails : transactions.md


Relations

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

Types : oneToOne | oneToMany | manyToOne | manyToMany

Détails : relationships.md


Permissions

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

Par défaut : tout refuser sauf si les permissions de ligne/fichier sont définies ou héritées de la table/du bucket. Utilisez les permissions de ligne/fichier pour une ACL par ressource. Si toutes les ressources partagent les règles, définissez les permissions de table/bucket, laissez les permissions de ligne/fichier vides. write = create + update + delete À éviter : permissions manquantes = verrouillage ; Role.any() + write/update/delete = mutation publique ; Permission.read(Role.any()) sur des données sensibles = fuite publique. Rôles : any() | guests() | users() | user(id) | team(id) | team(id, role) | label(name) Détails : permissions | teams | storage-files


Limites

Page par défaut : 25 · En masse : 1000 lignes · Query.equal() : 100 valeurs · Imbrication : 3 niveaux · Requêtes/req : 100 · Délai d'attente : 15s

Codes d'erreur

400 Mauvaise requête · 401 Non autorisé · 403 Interdit · 404 Introuvable · 409 Conflit · 429 Limité (SDK client uniquement) Attraper AppwriteException. 429 -> backoff exponentiel.

Détails : error-handling.md


Anti-patrons

ErronéCorrectPourquoi
Requêtes N+1Query.select(['col', 'relation.col'])Tue les allers-retours supplémentaires
Lire-modifier-écrireOperator.increment()Condition de compétition
Grands offsetsQuery.cursorAfter(id)O(n) vs O(1)
Sauter les totauxtotal: falseTue le scan COUNT
Index manquantsCréer pour les colonnes interrogéesLes requêtes parcourent toute la table
Initialisation du SDK dans le handlerInitialiser en dehors pour une réutilisation à chaudConfiguration répétée à chaque appel
Secrets codés en durVariables d'environnementRisque de sécurité
PollingTemps réel ou déclencheurs d'événementsExécutions gaspillées
Filtrage côté clientRequêtes temps réelLe serveur fait le travail
Chaînes de canal brutesHelpers ChannelFautes de frappe, pas d'auto-complétion
ColumnStringColumnVarchar ou ColumnTextstring déprécié
Écrire les types à la mainappwrite generateDérive de schéma, pas d'auto-complétion
databases.listDocuments()tablesDB.listRows()API dépréciée
HTTP Appwrite brut (fetch, requests, dio, package:http, curl)Package SDK officielDérive de version, erreurs d'authentification, perte d'API typées
Identifiants uniques personnalisés/codés en durID.unique()Risque de débordement, fuite d'informations, collisions
Re-recherche complète à chaque synchronisationQuery.updatedAfter() + horodatages par tableGaspille la bande passante, lent
Boucle avec createRow()createRows() en masseN requêtes vs 1

Optimisation des coûts

  1. Query.select() — réduit la bande passante
  2. Pagination par curseur + total: false — requêtes les plus rapides
  3. Temps réel plutôt que polling — une connexion vs appels répétés
  4. Opérations en masse — réduit le nombre de requêtes
  5. Index — requêtes plus rapides = moins de temps de calcul
  6. Utiliser le plan gratuit/faible pour les environnements de développement

Skills associés