Desarrollo con Appwrite
Reglas Críticas
- Usa solo los paquetes SDK oficiales — Dart/Flutter/TypeScript/Python deben usar sdk-routing. Usar HTTP REST/GraphQL sin procesar a través de
fetch,requests,dio,package:http,curl, etc. es una violación a menos que el SDK carezca del endpoint o unClient.callaislado y probado solucione el análisis del modelo del SDK. - Fija las SDK según el destino — Cloud: última SDK estable. Auto-gestionado
1.9.x:dart_appwrite25.1.0, Flutterappwrite25.2.0,node-appwrite26.2.0, webappwrite26.1.0, Pythonappwrite21.0.0, CLI 22.4.0. - Usa la API TablesDB — La API de Collections está obsoleta desde 1.8.0.
- Usa
ID.unique()para todos los IDs únicos — IDs de filas (rowId:), IDs de archivos, IDs de usuarios, IDs de equipos, IDs de webhooks, IDs de mensajes, IDs de suscriptores e IDs de entidades en columnas. Sin IDs únicos codificados, generadores personalizados, nombres, marcas de tiempo o slugs como IDs; desbordan los límites de las columnas y filtran datos. Usa claves naturales estables solo como columnas indexadas. - Usa
Query.select()— Las relaciones devuelven solo IDs sin selección explícita. - Usa paginación por cursor — El offset se degrada en tablas grandes.
- Usa operadores para contadores — Evita condiciones de carrera.
- Crea índices — Las consultas sin índices escanean tablas enteras.
- Inicializa fuera del manejador — Las SDK/conexiones persisten entre invocaciones en caliente.
- Agrupa funciones por dominio — Una por dominio, no por operación.
- Disparadores de eventos en lugar de sondeo — Un disparador reemplaza miles de solicitudes.
- Usa tipos de cadena explícitos —
stringobsoleto; usavarcharotext/mediumtext/longtext. - Usa
appwrite generate— SDK con tipo seguro a partir del esquema. - Usa los ayudantes de Canal — Suscripciones en tiempo real con tipo seguro, no cadenas sin procesar.
- Usa consultas en tiempo real — Filtrado de eventos del lado del servidor, no del lado del cliente.
- Iniciar asincrónicamente funciones de larga duración — Las llamadas
createExecutiondel cliente para flujos de eliminación/sincronización/importación/exportación/migración/generación usan ejecución asíncrona, luego reconcilian el estado de la fuente de verdad con sondeo acotado/tiempo real/obtención. No bloquear en la finalización del backend; reportar fallos destructivos solo después de que la reconciliación demuestre que la entidad/cuenta aún existe.
Comprobación Rápida de CLI (Arriba)
Usa un archivo .env.appwrite.local ignorado por el repositorio local por proyecto; no confíes en la configuración global de CLI.
# .env.appwrite.local (gitignorado)
APPWRITE_ENDPOINT=https://<endpoint>/v1
APPWRITE_PROJECT_ID=<project_id>
APPWRITE_API_KEY=standard_...
# Usa "cloud" o la línea del servidor auto-gestionado.
APPWRITE_SERVER_VERSION=cloud
Política de versión de CLI:
- Appwrite Cloud: último
appwrite-cli. - Appwrite auto-gestionado
1.9.x:[email protected].
Antes de trabajar con la CLI de 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 "Versión de APPWRITE_SERVER_VERSION=$APPWRITE_SERVER_VERSION no soportada; elige una CLI que coincida antes de continuar."
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 debe mostrar el endpoint/proyecto esperado y una clave enmascarada antes de continuar. Si falta, solicita endpoint, ID de proyecto, clave API y versión del servidor.
Reglas: appwrite.config.json = configuración del proyecto local. appwrite client ... = anulación global (no interactiva). Para anular: appwrite client --reset. Las banderas auxiliares de CLI varían según la versión; si no están disponibles, usa --queries sin procesar o analiza la salida de tabla simple para verificaciones rápidas de estado.
Detalles: appwrite-cli
Terminología (1.8.0+)
| Antiguo | Nuevo |
|---|---|
| Collections | Tables |
| Documents | Rows |
| Attributes | Columns |
| Databases | TablesDB |
Configuración
Política de paquetes:
- Cloud: última SDK oficial estable.
- Auto-gestionado
1.9.x: usa los pines de la Regla Crítica 2. - TypeScript/React navegador:
appwrite; TypeScript servidor/SSR/Functions:node-appwrite. - Python:
appwrite; prefiere argumentos de palabra clave para las llamadas al SDK. - Dart:
appwritepara aplicaciones Flutter/cliente,dart_appwritepara servidor/Functions; prefiere parámetros con nombre.
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 de TablesDB
// Crear
await tablesDB.createRow(databaseId: 'db', tableId: 'users', rowId: ID.unique(),
data: {'name': 'Alice'});
// Leer
final rows = await tablesDB.listRows(databaseId: 'db', tableId: 'users',
queries: [Query.equal('status', 'active'), Query.select(['name', 'email'])]);
// Actualizar
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'});
// Eliminar
await tablesDB.deleteRow(databaseId: 'db', tableId: 'users', rowId: 'user_123');
Usa modismos del SDK:
- TypeScript usa parámetros de objeto:
tablesDB.createRow({ databaseId, tableId, rowId, data }). - Python usa argumentos de palabra clave:
tables_db.create_row(database_id='db', table_id='users', row_id=ID.unique(), data={...}). - Dart usa parámetros con nombre como se muestra arriba.
Masivo: bulk-operations.md | Consultas de ID fragmentadas: chunked-queries.md
Referencia de Consultas
Comparación: equal | notEqual | lessThan | lessThanEqual | greaterThan | greaterThanEqual | between | notBetween
Cadena: startsWith | endsWith | contains | search (+ variantes not)
Nulo: isNull | isNotNull · Lógicas: and([...]) | or([...])
Paginación: select | limit | cursorAfter | cursorBefore | orderAsc | orderDesc | orderRandom
Marca de tiempo: createdAfter | createdBefore | updatedAfter | updatedBefore
Espaciales: distanceEqual | distanceLessThan | distanceGreaterThan | intersects | overlaps | touches | crosses (+ variantes not)
Todas con prefijo Query.. Detalles: query-optimization.md
Operadores (Actualizaciones Atómicas)
data: {
'likes': Operator.increment(1),
'tags': Operator.arrayAppend(['trending']),
'updatedAt': Operator.dateSetNow(),
}
Numéricos: increment | decrement | multiply | divide
Array: arrayAppend | arrayPrepend | arrayRemove | arrayUnique | arrayIntersect | arrayDiff
Otros: toggle | stringConcat | stringReplace | dateAddDays | dateSetNow
Detalles: atomic-operators.md
Tipos de Columna
| Tipo | Máx. Caracteres | Indexación | Uso |
|---|---|---|---|
varchar | 16,383 | Completa (si tamaño < 768) | Cadenas cortas consultables |
text | 16,383 | Solo prefijo | Descripciones, notas |
mediumtext | 4,194,303 | Solo prefijo | Artículos |
longtext | 1,073,741,823 | Solo prefijo | Documentos grandes |
stringobsoleto. Usavarcharpara consultable,textpara no indexado.
Otros: integer | float | boolean | datetime | email | url | ip | enum | relationship | point | line | polygon
Detalles: schema-management.md
Rendimiento
| Regla | Impacto |
|---|---|
| Paginación por cursor | 10-100x más rápida que offset |
| Mixin de paginación (Dart) | ~50 líneas ahorradas por fuente de datos |
Query.select() | 12-18x más rápido para relaciones |
total: false | Elimina escaneo COUNT |
| Índices | 100x más rápido en tablas grandes |
| Operadores | Sin condiciones de carrera |
| Operaciones masivas | N → 1 solicitud |
| Sincronización delta | Obtiene solo filas modificadas |
Detalles: performance.md, pagination-performance.md
Generación de SDK con Tipo Seguro
appwrite generate
Genera ayudantes tipados a partir del esquema en generated/appwrite/. Autocompletado + verificaciones en compilación. Regenerar después de cambios en el esquema.
Flujo CLI: login -> init project -> pull -> generate -> push. Detalles: appwrite-cli
Autenticación
Email/contraseña, OAuth (más de 50 proveedores), teléfono, enlace mágico, anónimo, OTP por email, token personalizado. MFA: TOTP/email/teléfono/recuperación. Sesiones SSR. JWT para funciones.
Cookie SSR: a_session_<PROJECT_ID>. Cliente admin crea sesión. Cliente de sesión por solicitud lee el contexto del usuario.
Las políticas de email pueden bloquear correos gratuitos, con alias o desechables en el registro/actualización.
Detalles: authentication.md | auth-methods.md
Almacenamiento
Subir/descargar/previsualizar c/transformaciones (redimensionar, conversión de formato). Tokens de archivo para URLs compartibles. HEIC, AVIF, WebP soportados. Las SDK manejan la fragmentación y subida de fragmentos en paralelo; no implementes subidas HTTP manualmente.
Detalles: storage-files.md
Tiempo Real
final sub = realtime.subscribe(['tablesdb.db.tables.posts.rows']);
sub.stream.listen((e) => print(e.events));
Canales: account | tablesdb.<DB>.tables.<TABLE>.rows | buckets.<BUCKET>.files | presences
Ayudantes de canal (preferidos): Clase Channel para suscripciones con tipo seguro y autocompletado del 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'])] // filtrado del lado del servidor
);
Usa la API de Presencias para estado en línea/escribiendo/activo cuando sea compatible; evita filas duraderas en DB + cron de limpieza para estado efímero.
Detalles: realtime.md
Funciones
Inicializa SDK fuera del manejador. Agrupa por dominio. Disparadores de eventos, no sondeo. Funciones: auto-gestionado usa el pin de Dart de la Regla 2; Cloud usa la última SDK/entorno de ejecución.
Detalles: functions.md | functions-advanced.md
Transacciones
final tx = await tablesDB.createTransaction(ttl: 300);
await tablesDB.createRow(..., transactionId: tx.$id);
await tablesDB.updateTransaction(transactionId: tx.$id, commit: true);
Detalles: transactions.md
Relaciones
await tablesDB.listRows(databaseId: 'db', tableId: 'posts',
queries: [Query.equal('author.country', 'US'), Query.select(['title', 'author.name'])]);
Tipos: oneToOne | oneToMany | manyToOne | manyToMany
Detalles: relationships.md
Permisos
permissions: [
Permission.read(Role.any()),
Permission.update(Role.user(userId)),
Permission.delete(Role.team('admin')),
Permission.create(Role.label('premium')),
]
Por defecto: denegar todo a menos que se establezcan permisos de fila/archivo o se hereden de tabla/contenedor.
Usa permisos de fila/archivo para ACL por recurso. Si todos los recursos comparten reglas, establece permisos de tabla/contenedor, deja vacíos los permisos de fila/archivo.
write = create + update + delete
Evita: permisos faltantes = bloqueo; Role.any() + write/update/delete = mutación pública; Permission.read(Role.any()) en datos sensibles = fuga pública.
Roles: any() | guests() | users() | user(id) | team(id) | team(id, role) | label(name)
Detalles: permissions | teams | storage-files
Límites
Página por defecto: 25 · Masivo: 1000 filas · Query.equal(): 100 valores · Anidamiento: 3 niveles · Consultas/solicitud: 100 · Tiempo de espera: 15s
Códigos de Error
400 Solicitud incorrecta · 401 No autorizado · 403 Prohibido · 404 No encontrado · 409 Conflicto · 429 Límite de tasa excedido (solo SDK de cliente)
Captura AppwriteException. 429 -> retroceso exponencial.
Detalles: error-handling.md
Anti-patrones
| Incorrecto | Correcto | Por qué |
|---|---|---|
| Consultas N+1 | Query.select(['col', 'relation.col']) | Elimina viajes de ida y vuelta extra |
| Leer-modificar-escribir | Operator.increment() | Condición de carrera |
| Offsets grandes | Query.cursorAfter(id) | O(n) vs O(1) |
| Omitir totales | total: false | Elimina escaneo COUNT |
| Falta de índices | Crear para columnas consultadas | Las consultas escanean toda la tabla |
| Inicialización de SDK dentro del manejador | Inicializar fuera para reutilización en caliente | Configuración repetida en cada llamada |
| Secretos codificados | Variables de entorno | Riesgo de seguridad |
| Sondeo | Tiempo real o disparadores de eventos | Ejecuciones desperdiciadas |
| Filtrado del lado del cliente | Consultas en tiempo real | El servidor hace el trabajo |
| Cadenas de canal sin procesar | Ayudantes Channel | Errores tipográficos, sin autocompletado |
ColumnString | ColumnVarchar o ColumnText | string obsoleto |
| Escribir tipos manualmente | appwrite generate | Desviación de esquema, sin autocompletado |
databases.listDocuments() | tablesDB.listRows() | API obsoleta |
HTTP Appwrite sin procesar (fetch, requests, dio, package:http, curl) | Paquete SDK oficial | Desviación de versión, errores de autenticación, pérdida de APIs tipadas |
| IDs únicos personalizados/codificados | ID.unique() | Riesgo de desbordamiento, fuga de información, colisiones |
| Reobtenci�n completa en cada sincronización | Query.updatedAfter() + marcas de tiempo por tabla | Desperdicia ancho de banda, lento |
Bucle con createRow() | createRows() masivo | N solicitudes vs 1 |
Optimización de Costos
Query.select()— reduce el ancho de banda- Paginación por cursor +
total: false— consultas más rápidas - Tiempo real en lugar de sondeo — una conexión vs llamadas repetidas
- Consultas en lote — N solicitudes → 1 solicitud
- Usar funciones de activación en lugar de programación basada en sondeo
- Sincronización delta (
Query.updatedAfter()) — solo cambios desde la última marca de tiempo - Operadores para actualizaciones atómicas — sin errores de concurrencia que requieran reintentos
- Generación de SDK (
appwrite generate) — sin costos de depuración por errores de tipado
Instrucciones Específicas del Agente
Consulta agent-identity.md para pautas de comportamiento del agente durante el desarrollo de Appwrite. Consulta latency-expectations.md para expectativas de latencia en Appwrite Cloud vs auto-gestionado.