Communitygithub.com

sgaabdu4/appwrite-backend

Skill do Appwrite BaaS para agentes de IA. Abrange TablesDB, Autenticação, Armazenamento, Funções, Mensageria e Tempo Real em Dart, Python e TypeScript.

O que é appwrite-backend?

Esta skill capacita agentes de IA a interagir programaticamente com o Appwrite, um Backend-as-a-Service (BaaS), através de SDKs oficiais em Dart, Python e TypeScript. Ela fornece regras críticas e exemplos de código para operações fundamentais como CRUD no TablesDB (substituto moderno das coleções), consultas otimizadas com `Query.select()` e paginação por cursor, atualizações atômicas com `Operator`, e geração de SDK type-safe via `appwrite generate`. A skill também cobre autenticação, armazenamento de arquivos, comunicação em tempo real com canais e queries, execução de funções serverless, transações, relacionamentos entre tabelas, controle de permissões e padrões de boas práticas (como evitar polling em favor de eventos e usar `ID.unique()` para todos os IDs únicos). O objetivo é garantir que o agente siga as regras oficiais do Appwrite, evite anti-padrões e otimize custos e desempenho, seja em ambientes Cloud ou self-hosted versão 1.9.x.

Funciona com~Claude Code~Codex CLI✓Cursor
npx skills add sgaabdu4/appwrite-backend

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Desenvolvimento Appwrite

Regras Críticas

  1. Use apenas SDKs oficiais — Dart/Flutter/TypeScript/Python devem usar sdk-routing. Requisições REST/GraphQL via fetch, requests, dio, package:http, curl, etc. são violação a menos que o SDK não possua o endpoint ou um Client.call isolado e testado contorne a análise de modelos do SDK.
  2. Fixar SDKs por destino — Cloud: última versão estável do 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. Use a API TablesDB — API Collections depreciada desde 1.8.0
  4. Use ID.unique() para todos os IDs únicos — IDs de linhas (rowId:), IDs de arquivos, IDs de usuários, IDs de times, IDs de webhooks, IDs de mensagens, IDs de inscritos e IDs de entidades em colunas. Sem IDs únicos fixos, geradores personalizados, nomes, timestamps ou slugs como IDs; eles estouram limites de coluna e vazam dados. Use chaves naturais estáveis apenas como colunas indexadas.
  5. Use Query.select() — Relacionamentos retornam apenas IDs sem seleção explícita.
  6. Use paginação por cursor — Offset degrada em tabelas grandes
  7. Use Operator para contadores — Evita condições de corrida
  8. Crie índices — Consultas sem índices varrem tabelas inteiras
  9. Inicialize fora do handler — SDK/conexões persistem entre invocações quentes
  10. Agrupe funções por domínio — Uma por domínio, não por operação
  11. Eventos em vez de polling — Um gatilho substitui milhares de requisições
  12. Use tipos string explícitos — string depreciado; use varchar ou text/mediumtext/longtext
  13. Use appwrite generate — SDK type-safe a partir do esquema
  14. Use helpers de Channel — Inscrições em tempo real type-safe, não strings cruas
  15. Use consultas Realtime — Filtragem de eventos no servidor, não no cliente
  16. Inicie assincronamente Funções de longa duração — Chamadas createExecution do cliente para fluxos de exclusão/sincronização/importação/exportação/migração/geração usam execução assíncrona, depois reconciliam o estado fonte-da-verdade com polling limitado/tempo real/fetch. Não bloqueie na conclusão do backend; reporte falhas destrutivas somente após a reconciliação provar que a entidade/conta ainda existe.

Verificação Rápida da CLI (Topo)

Use um .env.appwrite.local ignorado (gitignored) por repositório e projeto; não confie na configuração global da CLI.

# .env.appwrite.local (gitignored)
APPWRITE_ENDPOINT=https://<endpoint>/v1
APPWRITE_PROJECT_ID=<project_id>
APPWRITE_API_KEY=standard_...
# Use "cloud" ou a linha do servidor self-hosted.
APPWRITE_SERVER_VERSION=cloud

Política de versão da CLI:

  • Appwrite Cloud: última versão do appwrite-cli.
  • Appwrite Self-hosted 1.9.x: [email protected].

Antes de trabalhar com a 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 "APPWRITE_SERVER_VERSION=$APPWRITE_SERVER_VERSION não suportada; escolha uma CLI compatível 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 deve mostrar o endpoint/projeto esperados e uma chave mascarada antes de prosseguir. Se ausente, peça endpoint, ID do projeto, chave da API e versão do servidor.

Regras: appwrite.config.json = config do projeto local. appwrite client ... = substituição global (não interativa). Limpar substituição: appwrite client --reset. Flags auxiliares da CLI variam por versão; se indisponíveis, use --queries cru ou analise a saída simples da tabela para verificações rápidas de status. Detalhes: appwrite-cli

Terminologia (1.8.0+)

AntigoNovo
CollectionsTables
DocumentsRows
AttributesColumns
DatabasesTablesDB

Configuração

Política de pacotes:

  • Cloud: última versão estável oficial do SDK.
  • Self-hosted 1.9.x: use as fixações da Regra Crítica 2.
  • TypeScript/React browser: appwrite; TypeScript server/SSR/Functions: node-appwrite.
  • Python: appwrite; prefira argumentos nomeados nas chamadas do SDK.
  • Dart: appwrite para apps Flutter/cliente, dart_appwrite para servidor/Funções; prefira parâmetros nomeados.
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 no TablesDB

// Criar
await tablesDB.createRow(databaseId: 'db', tableId: 'users', rowId: ID.unique(),
    data: {'name': 'Alice'});

// Ler
final rows = await tablesDB.listRows(databaseId: 'db', tableId: 'users',
    queries: [Query.equal('status', 'active'), Query.select(['name', 'email'])]);

// Atualizar
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'});

// Excluir
await tablesDB.deleteRow(databaseId: 'db', tableId: 'users', rowId: 'user_123');

Use os modismos do SDK:

  • TypeScript usa parâmetros de objeto: tablesDB.createRow({ databaseId, tableId, rowId, data }).
  • Python usa argumentos nomeados: tables_db.create_row(database_id='db', table_id='users', row_id=ID.unique(), data={...}).
  • Dart usa parâmetros nomeados como mostrado acima.

Em lote: bulk-operations.md | Consultas de ID fragmentadas: chunked-queries.md


Referência de Consultas

Comparação: equal | notEqual | lessThan | lessThanEqual | greaterThan | greaterThanEqual | between | notBetween String: startsWith | endsWith | contains | search (+ variantes not) Nulo: isNull | isNotNull · Lógico: and([...]) | or([...]) Paginação: select | limit | cursorAfter | cursorBefore | orderAsc | orderDesc | orderRandom Timestamp: createdAfter | createdBefore | updatedAfter | updatedBefore Espacial: distanceEqual | distanceLessThan | distanceGreaterThan | intersects | overlaps | touches | crosses (+ variantes not)

Todos prefixados com Query.. Detalhes: query-optimization.md


Operadores (Atualizações 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 Outros: toggle | stringConcat | stringReplace | dateAddDays | dateSetNow

Detalhes: atomic-operators.md


Tipos de Coluna

TipoMáx. CaracteresIndexaçãoUso
varchar16.383Completa (se tamanho < 768)Strings curtas consultáveis
text16.383Apenas prefixoDescrições, notas
mediumtext4.194.303Apenas prefixoArtigos
longtext1.073.741.823Apenas prefixoDocumentos grandes

string depreciado. Use varchar para consultável, text para não indexado.

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

Detalhes: schema-management.md


Performance

RegraImpacto
Paginação por cursor10-100x mais rápido que offset
Mixin de paginação (Dart)~50 linhas economizadas por fonte de dados
Query.select()12-18x mais rápido para relacionamentos
total: falseElimina varredura COUNT
Índices100x mais rápido em tabelas grandes
OperadoresSem condições de corrida
Operações em loteN → 1 requisição
Sincronização deltaBusca apenas linhas alteradas

Detalhes: performance.md, pagination-performance.md


Geração de SDK Type-Safe

appwrite generate

Gera helpers tipados a partir do esquema em generated/appwrite/. Autocomplete + verificações de compilação. Regerar após alteração no esquema. Fluxo da CLI: login -> init project -> pull -> generate -> push. Detalhes: appwrite-cli


Autenticação

Email/senha, OAuth (50+ provedores), telefone, link mágico, anônimo, OTP por email, token personalizado. MFA: TOTP/email/telefone/recuperação. Sessões SSR. JWT para funções. Cookie SSR: a_session_<PROJECT_ID>. Cliente admin cria sessão. Cliente de sessão por requisição lê contexto do usuário. Políticas de email podem bloquear emails gratuitos, com aliases ou descartáveis no cadastro/atualização.

Detalhes: authentication.md | auth-methods.md


Armazenamento

Upload/download/preview com transformações (redimensionar, conversão de formato). Tokens de arquivo para URLs compartilháveis. HEIC, AVIF, WebP suportados. SDKs lidam com chunking/uploads paralelos; não faça upload HTTP manual.

Detalhes: storage-files.md


Tempo Real

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

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

Helpers de channel (preferenciais): Classe Channel para inscrições type-safe com autocomplete 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'])]  // filtragem no servidor
);

Use a API Presences para status online/digitando/ativo quando suportado; evite linhas DB duráveis + cron de limpeza para status efêmeros.

Detalhes: realtime.md


Funções

Inicialize SDK fora do handler. Agrupe por domínio. Gatilhos de eventos, não polling. Funções: self-hosted usa fixação Dart da Regra 2; Cloud usa SDK/runtime mais recente.

Detalhes: functions.md | functions-advanced.md


Transações

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

Detalhes: transactions.md


Relacionamentos

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

Tipos: oneToOne | oneToMany | manyToOne | manyToMany

Detalhes: relationships.md


Permissões

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

Padrão: negar tudo a menos que permissões de linha/arquivo sejam definidas ou herdadas da tabela/balde. Use permissões de linha/arquivo para ACL por recurso. Se todos os recursos compartilham regras, defina permissões da tabela/balde, deixe vazias as permissões de linha/arquivo. write = create + update + delete Evite: permissões ausentes = bloqueio; Role.any() + write/update/delete = mutação pública; Permission.read(Role.any()) em dados sensíveis = vazamento público. Papéis: any() | guests() | users() | user(id) | team(id) | team(id, role) | label(name) Detalhes: permissions | teams | storage-files


Limites

Página padrão: 25 · Em lote: 1000 linhas · Query.equal(): 100 valores · Aninhamento: 3 níveis · Consultas/req: 100 · Timeout: 15s

Códigos de Erro

400 Requisição inválida · 401 Não autorizado · 403 Proibido · 404 Não encontrado · 409 Conflito · 429 Limitado por taxa (apenas SDKs do cliente) Capture AppwriteException. 429 -> backoff exponencial.

Detalhes: error-handling.md


Anti-Padrões

ErradoCertoPorquê
Consultas N+1Query.select(['col', 'relation.col'])Elimina viagens extras de ida e volta
Ler-modificar-escreverOperator.increment()Condição de corrida
Offsets grandesQuery.cursorAfter(id)O(n) vs O(1)
Pular totaistotal: falseElimina varredura COUNT
Índices ausentesCrie para colunas consultadasConsultas varrem tabela inteira
SDK init dentro do handlerInit fora para reuso a quenteConfiguração repetida a cada chamada
Segredos fixosVariáveis de ambienteRisco de segurança
PollingGatilhos de tempo real ou eventosExecuções desperdiçadas
Filtragem no clienteConsultas de tempo realServidor faz o trabalho
Strings de canal cruasHelpers ChannelErros de digitação, sem autocomplete
ColumnStringColumnVarchar ou ColumnTextstring depreciado
Escrever tipos manualmenteappwrite generateDeriva de esquema, sem autocomplete
databases.listDocuments()tablesDB.listRows()API depreciada
HTTP Appwrite cru (fetch, requests, dio, package:http, curl)Pacote SDK oficialDeriva de versão, erros de autenticação, APIs tipadas perdidas
IDs únicos personalizados/fixosID.unique()Risco de estouro, vazamento de informações, colisões
Re-busca completa a cada sincronizaçãoQuery.updatedAfter() + timestamps por tabelaDesperdiça largura de banda, lento
Loop com createRow()createRows() em loteN requisições vs 1

Otimização de Custos

  1. Query.select() — reduz largura de banda
  2. Paginação por cursor + total: false — consultas mais rápidas
  3. Tempo real em vez de polling — uma conexão vs chamadas repetidas
  4. Opera

Habilidades Relacionadas