Développement Appwrite
Règles critiques
- 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'unClient.callisolé et testé contourne le parsing du modèle SDK. - Épingler les SDK par cible — Cloud : dernier SDK stable. Auto-hébergé
1.9.x:dart_appwrite25.1.0, Flutterappwrite25.2.0,node-appwrite26.2.0, webappwrite26.1.0, Pythonappwrite21.0.0, CLI 22.4.0. - Utiliser l'API TablesDB — L'API Collections est dépréciée depuis 1.8.0.
- 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. - Utiliser
Query.select()— Les relations ne renvoient que des identifiants sans sélection explicite. - Utiliser la pagination par curseur — L'offset se dégrade sur les grandes tables.
- Utiliser
Operatorpour les compteurs — Évite les conditions de compétition. - Créer des index — Les requêtes sans index parcourent l'intégralité des tables.
- Initialiser en dehors du handler — Les SDK/connexions persistent entre les invocations à chaud.
- Regrouper les fonctions par domaine — Une par domaine, pas par opération.
- Déclencheurs d'événements plutôt que du polling — Un seul déclencheur remplace des milliers de requêtes.
- Utiliser des types de chaîne explicites —
stringest déprécié ; utilisezvarcharoutext/mediumtext/longtext. - Utiliser
appwrite generate— SDK type-safe à partir du schéma. - Utiliser les helpers
Channel— Abonnements temps réel type-safe, pas de chaînes brutes. - Utiliser les requêtes temps réel — Filtrage d'événements côté serveur, pas côté client.
- Démarrer de manière asynchrone les fonctions longues — Les appels clients
createExecutionpour 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/fetchlimité. 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+)
| Ancien | Nouveau |
|---|---|
| Collections | Tables |
| Documents | Lignes |
| Attributs | Colonnes |
| Bases de données | TablesDB |
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 :
appwritepour les applications Flutter/client,dart_appwritepour 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
| Type | Max Caractères | Indexation | Utilisation |
|---|---|---|---|
varchar | 16 383 | Complète (si taille < 768) | Chaînes courtes interrogeables |
text | 16 383 | Préfixe uniquement | Descriptions, notes |
mediumtext | 4 194 303 | Préfixe uniquement | Articles |
longtext | 1 073 741 823 | Préfixe uniquement | Grands documents |
stringest déprécié. Utilisezvarcharpour les colonnes interrogeables,textpour 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ègle | Impact |
|---|---|
| Pagination par curseur | 10 à 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 |
| Indexes | 100 fois plus rapide sur les grandes tables |
| Opérateurs | Pas de conditions de compétition |
| Opérations en masse | N → 1 requête |
| Synchronisation delta | Ré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é | Correct | Pourquoi |
|---|---|---|
| Requêtes N+1 | Query.select(['col', 'relation.col']) | Tue les allers-retours supplémentaires |
| Lire-modifier-écrire | Operator.increment() | Condition de compétition |
| Grands offsets | Query.cursorAfter(id) | O(n) vs O(1) |
| Sauter les totaux | total: false | Tue le scan COUNT |
| Index manquants | Créer pour les colonnes interrogées | Les requêtes parcourent toute la table |
| Initialisation du SDK dans le handler | Initialiser en dehors pour une réutilisation à chaud | Configuration répétée à chaque appel |
| Secrets codés en dur | Variables d'environnement | Risque de sécurité |
| Polling | Temps réel ou déclencheurs d'événements | Exécutions gaspillées |
| Filtrage côté client | Requêtes temps réel | Le serveur fait le travail |
| Chaînes de canal brutes | Helpers Channel | Fautes de frappe, pas d'auto-complétion |
ColumnString | ColumnVarchar ou ColumnText | string déprécié |
| Écrire les types à la main | appwrite generate | Dé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 officiel | Dérive de version, erreurs d'authentification, perte d'API typées |
| Identifiants uniques personnalisés/codés en dur | ID.unique() | Risque de débordement, fuite d'informations, collisions |
| Re-recherche complète à chaque synchronisation | Query.updatedAfter() + horodatages par table | Gaspille la bande passante, lent |
Boucle avec createRow() | createRows() en masse | N requêtes vs 1 |
Optimisation des coûts
Query.select()— réduit la bande passante- Pagination par curseur +
total: false— requêtes les plus rapides - Temps réel plutôt que polling — une connexion vs appels répétés
- Opérations en masse — réduit le nombre de requêtes
- Index — requêtes plus rapides = moins de temps de calcul
- Utiliser le plan gratuit/faible pour les environnements de développement