Appwrite Backend

Appwrite Development

Route

Load the owner before acting. Unlisted detail = read the owner, never infer.

Invariants

1. Official SDK only — raw Appwrite HTTP (fetch, requests, dio, package:http, curl) is a violation unless the SDK lacks the endpoint or an isolated, tested Client.call works around SDK model parsing.
2. Pin SDKs by target and call shape — Cloud: latest stable official SDK. Self-hosted 1.9.x: exact release-matched pins in self-hosting. “Compatible with 1.9.x” does not mean release-matched. Before changing a pin, audit every intervening breaking change and prove the repository's real SDK calls against the candidate; version resolution alone is insufficient. Repository-pinned binary/wrapper version always outranks a skill pin.
3. TablesDB, not Collections — Collections/Documents API deprecated 1.8.0.
4. Allocate Appwrite IDs once with ID.unique() — retryable create: call ID.unique() before the first attempt → persist the returned ID in the durable draft/intent → reuse that exact ID for every retry/reconciliation. A fresh ID.unique() on retry creates a second resource. Business/natural identity remains in indexed columns; never derive resource IDs from names, timestamps, slugs, hashes, or custom generators.
5. Explicit ACL — server SDK/Console create = empty resource ACL; client SDK create = creator read/update/delete. Pass explicit Permission/Role whenever ACL correctness matters.
6. Bind limits to the deployed target — page size, bulk rows/request, transaction operations, and Query.equal() value cap come from the deployed server source/config, never from memory.
7. Async-start long-running Functions — client createExecution for delete/sync/import/export/migrate/generate uses async execution, then reconciles source-of-truth state with bounded polling/realtime/fetch. Report destructive failure only after reconciliation proves the entity still exists. A synchronous createExecution already returns the terminal execution → read responseStatusCode + responseBody off that response; polling getExecution from the creating session returns 404 and inverts a success into a failure. Unavoidable status poll → 404 = terminal-unknown, never an error branch. Use functions-advanced.
8. Guard schema pushes — appwrite push tables reconciles remote TablesDB against the complete local manifest; omission means deletion. Production push requires appwrite-cli inventory + manifest guard PASS. push all, --all, and --force never substitute for that gate.
9. Stage production migrations — additive expand → type-aware resumable backfill → compatible deployment → contract/read-back → consumer activation. Partial data/schema never activates downstream code. Use production-migrations.
10. Preserve write intent before optimizing — update-only work never routes through upsertRow/upsertRows; a pre-read, existence check, or full payload does not remove create-on-missing semantics. Same patch across rows → updateRows; heterogeneous per-row updates → createOperations with action: update inside the verified transaction budget, or redesign. Transaction pressure never authorizes upsert. Use bulk-operations.
11. Batch collection writes before coding — target count can exceed one or is data-dependent → inventory the full mutation set + deployed limits before implementation. Compatible server bulk method exists → per-row write loop is forbidden. Bulk is unsupported → complete operation budget + atomic late-failure proof required. Full plan over cap → redesign or resumable fixed-point workflow; never split one atomic invariant across committed batches. Use bulk-operations + transactions.
12. Preserve failure causality — cleanup, compensation, or rollback failure never replaces the primary exception. Retain both errors + stack traces + execution/transaction IDs, report the operation failed, then reconcile the exact postcondition. Use transactions.
13. Coordinate client demand and uncertain outcomes — one endpoint/project-scoped coordinator owns foreground, sync, auth, and retry traffic. Bound concurrency; share 429/transport cooldowns; classify code-zero network failures; retry reads within one deadline; reconcile writes/transactions before any repeat; report one incident per failed operation; and never advance a sync checkpoint after partial failure. Use error-handling.

SDK Routing

• Call style: TypeScript object parameters, Python keyword arguments, Dart named parameters. Positional only when matching existing code or on explicit request.
• Client SDKs use account sessions and user-scoped APIs. Server SDKs use API keys. SSR uses two clients: a reusable admin client for session creation, and a per-request session client via setSession(...) — never shared.
• Cloud project endpoint = https://<REGION>.cloud.appwrite.io/v1. The CLI account login endpoint stays https://cloud.appwrite.io/v1; do not rewrite it to a region.
• Initialize clients outside warm Function handlers where the runtime allows.

import { Client, TablesDB } from 'node-appwrite';
const client = new Client()
    .setEndpoint('https://<REGION>.cloud.appwrite.io/v1')
    .setProject('<PROJECT_ID>')
    .setKey('<API_KEY>');
const tablesDB = new TablesDB(client);

from appwrite.client import Client
from appwrite.services.tables_db import TablesDB
client = (Client()
    .set_endpoint('https://<REGION>.cloud.appwrite.io/v1')
    .set_project('<PROJECT_ID>')
    .set_key('<API_KEY>'))
tables_db = TablesDB(client)

import 'package:dart_appwrite/dart_appwrite.dart';
final client = Client()
    .setEndpoint('https://<REGION>.cloud.appwrite.io/v1')
    .setProject('<PROJECT_ID>')
    .setKey('<API_KEY>');
final tablesDB = TablesDB(client);

Terminology (1.8.0+)

Collections = Tables · Documents = Rows · Attributes = Columns · Databases = TablesDB

Core Shapes

Row ops: createRow · getRow · listRows · updateRow · upsertRow · deleteRow Bulk (server SDK only, atomic per request, rejects relationship columns): createRows · updateRows · upsertRows · deleteRows

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

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

Query (all prefixed Query.; per-SDK naming + semantics in query-optimization): equal · notEqual · lessThan · lessThanEqual · greaterThan · greaterThanEqual · between · notBetween · startsWith · endsWith · contains · search (+ not variants) · isNull · isNotNull · and · or · select · limit · offset · cursorAfter · cursorBefore · orderAsc · orderDesc · orderRandom · createdAfter · createdBefore · updatedAfter · updatedBefore · distanceEqual · distanceLessThan · distanceGreaterThan · intersects · overlaps · touches · crosses

Operator (atomic field mutation; semantics in atomic-operators): increment · decrement · multiply · divide · arrayAppend · arrayPrepend · arrayRemove · arrayUnique · arrayIntersect · arrayDiff · toggle · stringConcat · stringReplace · dateAddDays · dateSetNow

Column types (string deprecated; full table + storage/index tradeoffs in schema-management): varchar · text · mediumtext · longtext · integer · bigint · float · boolean · datetime · email · url · ip · enum · relationship · point · line · polygon

Realtime channels (type-safe Channel helpers preferred over raw strings): account · tablesdb.<DB>.tables.<TABLE>.rows[.<ROW>] · buckets.<BUCKET>.files[.<FILE>] · teams[.<TEAM>] · memberships[.<MEMBERSHIP>] · functions.<FUNCTION>.executions · presences[.<PRESENCE>]

Anti-Patterns

Resources

Docs https://appwrite.io/docs · API https://appwrite.io/docs/references · SDKs https://github.com/appwrite