Desenvolvimento Appwrite
Regras Críticas
- 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 umClient.callisolado e testado contorne a análise de modelos do SDK. - Fixar SDKs por destino — Cloud: última versão estável do SDK. Self-hosted
1.9.x:dart_appwrite25.1.0, Flutterappwrite25.2.0,node-appwrite26.2.0, webappwrite26.1.0, Pythonappwrite21.0.0, CLI 22.4.0. - Use a API TablesDB — API Collections depreciada desde 1.8.0
- 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. - Use Query.select() — Relacionamentos retornam apenas IDs sem seleção explícita.
- Use paginação por cursor — Offset degrada em tabelas grandes
- Use Operator para contadores — Evita condições de corrida
- Crie índices — Consultas sem índices varrem tabelas inteiras
- Inicialize fora do handler — SDK/conexões persistem entre invocações quentes
- Agrupe funções por domínio — Uma por domínio, não por operação
- Eventos em vez de polling — Um gatilho substitui milhares de requisições
- Use tipos string explícitos —
stringdepreciado; usevarcharoutext/mediumtext/longtext - Use
appwrite generate— SDK type-safe a partir do esquema - Use helpers de Channel — Inscrições em tempo real type-safe, não strings cruas
- Use consultas Realtime — Filtragem de eventos no servidor, não no cliente
- Inicie assincronamente Funções de longa duração — Chamadas
createExecutiondo 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+)
| Antigo | Novo |
|---|---|
| Collections | Tables |
| Documents | Rows |
| Attributes | Columns |
| Databases | TablesDB |
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:
appwritepara apps Flutter/cliente,dart_appwritepara 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
| Tipo | Máx. Caracteres | Indexação | Uso |
|---|---|---|---|
varchar | 16.383 | Completa (se tamanho < 768) | Strings curtas consultáveis |
text | 16.383 | Apenas prefixo | Descrições, notas |
mediumtext | 4.194.303 | Apenas prefixo | Artigos |
longtext | 1.073.741.823 | Apenas prefixo | Documentos grandes |
stringdepreciado. Usevarcharpara consultável,textpara não indexado.
Outros: integer | float | boolean | datetime | email | url | ip | enum | relationship | point | line | polygon
Detalhes: schema-management.md
Performance
| Regra | Impacto |
|---|---|
| Paginação por cursor | 10-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: false | Elimina varredura COUNT |
| Índices | 100x mais rápido em tabelas grandes |
| Operadores | Sem condições de corrida |
| Operações em lote | N → 1 requisição |
| Sincronização delta | Busca 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
| Errado | Certo | Porquê |
|---|---|---|
| Consultas N+1 | Query.select(['col', 'relation.col']) | Elimina viagens extras de ida e volta |
| Ler-modificar-escrever | Operator.increment() | Condição de corrida |
| Offsets grandes | Query.cursorAfter(id) | O(n) vs O(1) |
| Pular totais | total: false | Elimina varredura COUNT |
| Índices ausentes | Crie para colunas consultadas | Consultas varrem tabela inteira |
| SDK init dentro do handler | Init fora para reuso a quente | Configuração repetida a cada chamada |
| Segredos fixos | Variáveis de ambiente | Risco de segurança |
| Polling | Gatilhos de tempo real ou eventos | Execuções desperdiçadas |
| Filtragem no cliente | Consultas de tempo real | Servidor faz o trabalho |
| Strings de canal cruas | Helpers Channel | Erros de digitação, sem autocomplete |
ColumnString | ColumnVarchar ou ColumnText | string depreciado |
| Escrever tipos manualmente | appwrite generate | Deriva de esquema, sem autocomplete |
databases.listDocuments() | tablesDB.listRows() | API depreciada |
HTTP Appwrite cru (fetch, requests, dio, package:http, curl) | Pacote SDK oficial | Deriva de versão, erros de autenticação, APIs tipadas perdidas |
| IDs únicos personalizados/fixos | ID.unique() | Risco de estouro, vazamento de informações, colisões |
| Re-busca completa a cada sincronização | Query.updatedAfter() + timestamps por tabela | Desperdiça largura de banda, lento |
Loop com createRow() | createRows() em lote | N requisições vs 1 |
Otimização de Custos
Query.select()— reduz largura de banda- Paginação por cursor +
total: false— consultas mais rápidas - Tempo real em vez de polling — uma conexão vs chamadas repetidas
- Opera