Communitygithub.com

sgaabdu4/appwrite-backend

Habilidad de Appwrite BaaS para agentes de IA. Cubre TablesDB, Auth, Storage, Functions, Messaging y Realtime en Dart, Python y TypeScript.

¿Qué es appwrite-backend?

Esta habilidad proporciona un conjunto completo de reglas y referencias para que los agentes de IA (como Claude Code, Cursor o Codex) interactúen con Appwrite como backend como servicio (BaaS). Cubre el uso de las SDK oficiales de Appwrite para Dart/Flutter, TypeScript y Python, con un enfoque en la API TablesDB (reemplazo de la antigua API de Collections). La habilidad incluye reglas críticas como el uso de `ID.unique()` para todos los IDs, `Query.select()` para optimizar consultas relacionadas, paginación por cursor en lugar de offset, operadores atómicos para evitar condiciones de carrera, y la generación de SDK con tipo seguro mediante `appwrite generate`. También aborda autenticación, almacenamiento de archivos, funciones serverless, suscripciones en tiempo real, transacciones, relaciones entre tablas y permisos detallados. Al seguir estas guías, los desarrolladores pueden construir aplicaciones escalables, eficientes y seguras sobre Appwrite, evitando antipatrones comunes como consultas N+1, falta de índices o el uso de la API REST directamente. La habilidad está optimizada tanto para Appwrite Cloud como para instancias auto-gestionadas.

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

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

Desarrollo con Appwrite

Reglas Críticas

  1. 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 un Client.call aislado y probado solucione el análisis del modelo del SDK.
  2. Fija las SDK según el destino — Cloud: última SDK estable. Auto-gestionado 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. Usa la API TablesDB — La API de Collections está obsoleta desde 1.8.0.
  4. 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.
  5. Usa Query.select() — Las relaciones devuelven solo IDs sin selección explícita.
  6. Usa paginación por cursor — El offset se degrada en tablas grandes.
  7. Usa operadores para contadores — Evita condiciones de carrera.
  8. Crea índices — Las consultas sin índices escanean tablas enteras.
  9. Inicializa fuera del manejador — Las SDK/conexiones persisten entre invocaciones en caliente.
  10. Agrupa funciones por dominio — Una por dominio, no por operación.
  11. Disparadores de eventos en lugar de sondeo — Un disparador reemplaza miles de solicitudes.
  12. Usa tipos de cadena explícitos — string obsoleto; usa varchar o text/mediumtext/longtext.
  13. Usa appwrite generate — SDK con tipo seguro a partir del esquema.
  14. Usa los ayudantes de Canal — Suscripciones en tiempo real con tipo seguro, no cadenas sin procesar.
  15. Usa consultas en tiempo real — Filtrado de eventos del lado del servidor, no del lado del cliente.
  16. Iniciar asincrónicamente funciones de larga duración — Las llamadas createExecution del 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+)

AntiguoNuevo
CollectionsTables
DocumentsRows
AttributesColumns
DatabasesTablesDB

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: appwrite para aplicaciones Flutter/cliente, dart_appwrite para 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

TipoMáx. CaracteresIndexaciónUso
varchar16,383Completa (si tamaño < 768)Cadenas cortas consultables
text16,383Solo prefijoDescripciones, notas
mediumtext4,194,303Solo prefijoArtículos
longtext1,073,741,823Solo prefijoDocumentos grandes

string obsoleto. Usa varchar para consultable, text para no indexado.

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

Detalles: schema-management.md


Rendimiento

ReglaImpacto
Paginación por cursor10-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: falseElimina escaneo COUNT
Índices100x más rápido en tablas grandes
OperadoresSin condiciones de carrera
Operaciones masivasN → 1 solicitud
Sincronización deltaObtiene 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

IncorrectoCorrectoPor qué
Consultas N+1Query.select(['col', 'relation.col'])Elimina viajes de ida y vuelta extra
Leer-modificar-escribirOperator.increment()Condición de carrera
Offsets grandesQuery.cursorAfter(id)O(n) vs O(1)
Omitir totalestotal: falseElimina escaneo COUNT
Falta de índicesCrear para columnas consultadasLas consultas escanean toda la tabla
Inicialización de SDK dentro del manejadorInicializar fuera para reutilización en calienteConfiguración repetida en cada llamada
Secretos codificadosVariables de entornoRiesgo de seguridad
SondeoTiempo real o disparadores de eventosEjecuciones desperdiciadas
Filtrado del lado del clienteConsultas en tiempo realEl servidor hace el trabajo
Cadenas de canal sin procesarAyudantes ChannelErrores tipográficos, sin autocompletado
ColumnStringColumnVarchar o ColumnTextstring obsoleto
Escribir tipos manualmenteappwrite generateDesviación de esquema, sin autocompletado
databases.listDocuments()tablesDB.listRows()API obsoleta
HTTP Appwrite sin procesar (fetch, requests, dio, package:http, curl)Paquete SDK oficialDesviación de versión, errores de autenticación, pérdida de APIs tipadas
IDs únicos personalizados/codificadosID.unique()Riesgo de desbordamiento, fuga de información, colisiones
Reobtenci�n completa en cada sincronizaciónQuery.updatedAfter() + marcas de tiempo por tablaDesperdicia ancho de banda, lento
Bucle con createRow()createRows() masivoN solicitudes vs 1

Optimización de Costos

  1. Query.select() — reduce el ancho de banda
  2. Paginación por cursor + total: false — consultas más rápidas
  3. Tiempo real en lugar de sondeo — una conexión vs llamadas repetidas
  4. Consultas en lote — N solicitudes → 1 solicitud
  5. Usar funciones de activación en lugar de programación basada en sondeo
  6. Sincronización delta (Query.updatedAfter()) — solo cambios desde la última marca de tiempo
  7. Operadores para actualizaciones atómicas — sin errores de concurrencia que requieran reintentos
  8. 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.

Skills relacionados