Communitygithub.com

sgaabdu4/appwrite-backend

AI 에이전트를 위한 Appwrite BaaS 스킬입니다. TablesDB, Auth, Storage, Functions, Messaging, Realtime을 Dart, Python, TypeScript로 지원합니다.

appwrite-backend란 무엇인가요?

이 스킬은 AI 에이전트(Claude Code, Cursor 등의 IDE 에이전트)가 Appwrite BaaS(Backend-as-a-Service) 플랫폼과 상호작용할 수 있도록 설계된 포괄적인 지침 모음입니다. Appwrite Cloud 및 자체 호스팅 버전을 모두 지원하며, Dart, Python, TypeScript를 포함한 주요 SDK를 사용하여 TablesDB(데이터베이스), 인증, 스토리지, 함수, 실시간 기능을 안전하고 효율적으로 구축할 수 있도록 안내합니다. 이 스킬의 핵심은 공식 SDK만을 사용하도록 강제하고, ID.unique() 사용, cursor 기반 페이지네이션, 원자적 연산자(Operator) 사용, 쿼리 최적화, 함수 초기화 위치 등 16가지 주요 규칙을 통해 일반적인 안티 패턴을 방지합니다. CLI 설정, SDK 초기화, CRUD 작업, 쿼리 참조, 권한 관리, 트랜잭션, 성능 최적화, 유형 안전 SDK 생성, 비용 최적화 등 백엔드 개발에 필요한 모든 측면을 상세히 다루어 개발자와 AI 에이전트가 신뢰할 수 있는 코드를 생성할 수 있도록 돕습니다.

지원 대상~Claude Code~Codex CLI✓Cursor
npx skills add sgaabdu4/appwrite-backend

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

Appwrite 개발

중요 규칙

  1. 공식 SDK 패키지만 사용 — Dart/Flutter/TypeScript/Python은 sdk-routing을 따라야 합니다. SDK가 엔드포인트를 지원하지 않거나 격리되고 테스트된 Client.call이 SDK 모델 파싱을 우회하는 경우가 아니라면, fetch, requests, dio, package:http, curl 등을 통한 원시 REST/GraphQL HTTP 사용은 위반입니다.
  2. 대상 환경별 SDK 고정 — Cloud: 최신 안정 SDK. 자체 호스팅 1.9.x: dart_appwrite 25.1.0, Flutter appwrite 25.2.0, node-appwrite 26.2.0, 웹 appwrite 26.1.0, Python appwrite 21.0.0, CLI 22.4.0.
  3. TablesDB API 사용 — Collections API는 1.8.0부터 사용 중단(deprecated)
  4. 모든 고유 ID에 ID.unique() 사용 — Row ID(rowId:), 파일 ID, 사용자 ID, 팀 ID, 웹훅 ID, 메시지 ID, 구독자 ID, 그리고 열(column)의 엔티티 ID. 하드코딩된 고유 ID, 사용자 정의 생성기, 이름, 타임스탬프, 또는 slug를 ID로 사용하지 마세요. 열 제한을 초과하고 데이터를 유출합니다. 인덱싱된 열로만 안정적인 자연 키를 사용하세요.
  5. Query.select() 사용 — 관계는 명시적 선택 없이 ID만 반환합니다.
  6. Cursor 페이지네이션 사용 — Offset은 대규모 테이블에서 성능이 저하됩니다.
  7. 카운터에는 Operator 사용 — 경쟁 조건을 방지합니다.
  8. 인덱스 생성 — 쿼리 없이 인덱스가 없으면 전체 테이블을 스캔합니다.
  9. 핸들러 외부에서 초기화 — SDK/연결은 웜 호출 간에 유지됩니다.
  10. 도메인별로 함수 그룹화 — 작업별 하나가 아닌 도메인별 하나의 함수
  11. 폴링보다 이벤트 트리거 — 하나의 트리거가 수천 개의 요청을 대체합니다.
  12. 명시적 문자열 유형 사용 — string은 사용 중단됨; varchar 또는 text/mediumtext/longtext를 사용하세요.
  13. appwrite generate 사용 — 스키마로부터 유형 안전 SDK 생성
  14. Channel 헬퍼 사용 — 원시 문자열이 아닌 유형 안전 실시간 구독
  15. 실시간 쿼리 사용 — 클라이언트 측이 아닌 서버 측 이벤트 필터링
  16. 장기 실행 함수는 비동기 시작 — 삭제/동기화/가져오기/내보내기/마이그레이션/생성 흐름에 대한 createExecution 호출은 비동기 실행을 사용한 후, 제한된 폴링/실시간/가져오기로 소스 오브 트루스 상태를 조정합니다. 백엔드 완료를 차단하지 마십시오. 조정 결과 엔티티/계정이 여전히 존재함이 입증된 후에만 파괴적 오류를 보고하세요.

CLI 빠른 확인 (상단)

프로젝트별로 repo-로컬 무시 .env.appwrite.local을 사용하세요. 전역 CLI 구성을 신뢰하지 마세요.

# .env.appwrite.local (gitignored)
APPWRITE_ENDPOINT=https://<endpoint>/v1
APPWRITE_PROJECT_ID=<project_id>
APPWRITE_API_KEY=standard_...
# "cloud" 또는 자체 호스팅 서버 라인을 사용하세요.
APPWRITE_SERVER_VERSION=cloud

CLI 버전 정책:

  • Appwrite Cloud: 최신 appwrite-cli.
  • 자체 호스팅 Appwrite 1.9.x: [email protected].

Appwrite CLI 작업 전:

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입니다. 계속하기 전에 일치하는 CLI를 선택하세요."
    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는 계속 진행하기 전에 예상되는 엔드포인트/프로젝트와 마스킹된 키를 표시해야 합니다. 없으면 엔드포인트, 프로젝트 ID, API 키, 서버 버전을 요청하세요.

규칙: appwrite.config.json = 로컬 프로젝트 구성. appwrite client ... = 전역 재정의(비대화형). 재정의 지우기: appwrite client --reset. CLI 헬퍼 플래그는 버전마다 다릅니다. 사용할 수 없으면 원시 --queries를 사용하거나 빠른 상태 확인을 위해 일반 테이블 출력을 구문 분석하세요. 자세한 내용: appwrite-cli

용어 (1.8.0+)

구 버전새 버전
CollectionsTables
DocumentsRows
AttributesColumns
DatabasesTablesDB

설정

패키지 정책:

  • Cloud: 최신 안정 공식 SDK.
  • 자체 호스팅 1.9.x: 중요 규칙 2의 고정 버전 사용.
  • TypeScript/React 브라우저: appwrite; TypeScript 서버/SSR/Functions: node-appwrite.
  • Python: appwrite; SDK 호출에는 키워드 인자 선호.
  • Dart: Flutter/클라이언트 앱용 appwrite, 서버/Functions용 dart_appwrite; 명명된 매개변수 선호.
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);

TablesDB CRUD

// 생성
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'])]);

// 업데이트
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'});

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

SDK 관용구 사용:

  • TypeScript는 객체 매개변수 사용: tablesDB.createRow({ databaseId, tableId, rowId, data }).
  • Python은 키워드 인자 사용: tables_db.create_row(database_id='db', table_id='users', row_id=ID.unique(), data={...}).
  • Dart는 위와 같이 명명된 매개변수를 사용합니다.

대량: bulk-operations.md | 청크 ID 쿼리: chunked-queries.md


쿼리 참조

비교: equal | notEqual | lessThan | lessThanEqual | greaterThan | greaterThanEqual | between | notBetween 문자열: startsWith | endsWith | contains | search (+ not 변형) Null: isNull | isNotNull · 논리: and([...]) | or([...]) 페이지네이션: select | limit | cursorAfter | cursorBefore | orderAsc | orderDesc | orderRandom 타임스탬프: createdAfter | createdBefore | updatedAfter | updatedBefore 공간: distanceEqual | distanceLessThan | distanceGreaterThan | intersects | overlaps | touches | crosses (+ not 변형)

모두 Query. 접두사 붙음. 자세한 내용: query-optimization.md


연산자 (원자적 업데이트)

data: {
    'likes': Operator.increment(1),
    'tags': Operator.arrayAppend(['trending']),
    'updatedAt': Operator.dateSetNow(),
}

숫자: increment | decrement | multiply | divide 배열: arrayAppend | arrayPrepend | arrayRemove | arrayUnique | arrayIntersect | arrayDiff 기타: toggle | stringConcat | stringReplace | dateAddDays | dateSetNow

자세한 내용: atomic-operators.md


열 유형

유형최대 문자인덱싱사용
varchar16,383전체 (크기 < 768이면)쿼리 가능한 짧은 문자열
text16,383접두사만설명, 메모
mediumtext4,194,303접두사만기사
longtext1,073,741,823접두사만대용량 문서

string 사용 중단. 쿼리 가능하려면 varchar, 인덱싱되지 않으려면 text를 사용하세요.

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

자세한 내용: schema-management.md


성능

규칙영향
Cursor 페이지네이션offset보다 10-100배 빠름
페이지네이션 믹스인 (Dart)데이터 소스당 약 50줄 절약
Query.select()관계에서 12-18배 빠름
total: falseCOUNT 스캔 제거
인덱스대규모 테이블에서 100배 빠름
연산자경쟁 조건 없음
대량 연산N → 1 요청
델타 동기화변경된 행만 가져옴

자세한 내용: performance.md, pagination-performance.md


유형 안전 SDK 생성

appwrite generate

스키마에서 generated/appwrite/로 유형 안전 헬퍼를 생성합니다. 자동 완성 + 컴파일 검사. 스키마 변경 후 재생성. CLI 흐름: login -> init project -> pull -> generate -> push. 자세한 내용: appwrite-cli


인증

이메일/비밀번호, OAuth (50개 이상의 제공자), 전화, 매직 링크, 익명, 이메일 OTP, 사용자 정의 토큰. MFA: TOTP/이메일/전화/복구. SSR 세션. 함수용 JWT. SSR 쿠키: a_session_<PROJECT_ID>. 관리자 클라이언트가 세션을 생성합니다. 요청당 세션 클라이언트가 사용자 컨텍스트를 읽습니다. 이메일 정책은 가입/업데이트 시 무료, 별칭 또는 일회용 이메일을 차단할 수 있습니다.

자세한 내용: authentication.md | auth-methods.md


스토리지

업로드/다운로드/미리보기 (크기 조정, 형식 변환) 포함. 공유 가능한 URL을 위한 파일 토큰. HEIC, AVIF, WebP 지원. SDK가 청킹/병렬 청크 업로드를 처리합니다. 업로드 HTTP를 직접 구현하지 마세요.

자세한 내용: storage-files.md


실시간

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

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

채널 헬퍼 (권장): IDE 자동 완성과 함께 유형 안전 구독을 위한 Channel 클래스:

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'])]  // 서버 측 필터링
);

지원되는 경우 Presences API를 온라인/입력 중/활성 상태에 사용하세요. 임시 상태를 위해 내구성 있는 DB 행 + 정리 크론을 피하세요.

자세한 내용: realtime.md


함수

핸들러 외부에서 SDK 초기화. 도메인별로 그룹화. 폴링이 아닌 이벤트 트리거. 함수: 자체 호스팅은 규칙 2 Dart 고정 버전 사용; Cloud는 최신 SDK/런타임 사용.

자세한 내용: functions.md | functions-advanced.md


트랜잭션

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

자세한 내용: transactions.md


관계

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

유형: oneToOne | oneToMany | manyToOne | manyToMany

자세한 내용: relationships.md


권한

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

기본값: 행/파일 권한이 설정되거나 테이블/버킷에서 상속되지 않으면 모두 거부. 리소스별 ACL에는 행/파일 권한을 사용하세요. 모든 리소스가 규칙을 공유하면 테이블/버킷 권한을 설정하고 행/파일 권한은 비워 두세요. write = create + update + delete 주의: 누락된 권한 = 잠금; Role.any() + write/update/delete = 공개 변형; 민감한 데이터에 Permission.read(Role.any()) = 공개 유출. 역할: any() | guests() | users() | user(id) | team(id) | team(id, role) | label(name) 자세한 내용: permissions | teams | storage-files


제한

기본 페이지: 25 · 대량: 1000개 행 · Query.equal(): 100개 값 · 중첩: 3레벨 · 쿼리/요청: 100 · 타임아웃: 15초

오류 코드

400 잘못된 요청 · 401 권한 없음 · 403 금지됨 · 404 찾을 수 없음 · 409 충돌 · 429 속도 제한 (클라이언트 SDK만 해당) AppwriteException을 잡으세요. 429 -> 지수 백오프.

자세한 내용: error-handling.md


안티 패턴

잘못된 방법올바른 방법이유
N+1 쿼리Query.select(['col', 'relation.col'])추가 왕복 제거
읽기-수정-쓰기Operator.increment()경쟁 조건
큰 offsetQuery.cursorAfter(id)O(n) 대 O(1)
합계 건너뛰기total: falseCOUNT 스캔 제거
인덱스 누락쿼리된 열에 대해 생성쿼리가 전체 테이블 스캔
핸들러 내부 SDK 초기화웜 재사용을 위해 외부에서 초기화각 호출마다 반복 설정
하드코딩된 비밀환경 변수보안 위험
폴링실시간 또는 이벤트 트리거낭비되는 실행
클라이언트 측 필터링실시간 쿼리서버가 작업 수행
원시 채널 문자열Channel 헬퍼오타, 자동 완성 없음
ColumnStringColumnVarchar 또는 ColumnTextstring 사용 중단
수동 유형 작성appwrite generate스키마 드리프트, 자동 완성 없음
databases.listDocuments()tablesDB.listRows()사용 중단된 API
원시 Appwrite HTTP (fetch, requests, dio, package:http, curl)공식 SDK 패키지버전 드리프트, 인증 오류, 손실된 유형 API
사용자 정의/하드코딩된 고유 IDID.unique()오버플로 위험, 정보 유출, 충돌
모든 동기화마다 전체 재가져오기Query.updatedAfter() + 테이블별 타임스탬프대역폭 낭비, 느림
createRow() 루프createRows() 대량N개 요청 대 1개

비용 최적화

  1. Query.select() — 대역폭 감소
  2. Cursor 페이지네이션 + total: false — 가장 빠른 쿼리
  3. 폴링보다 실시간 — 반복 호출 대신 단일 연결
  4. B

…

관련 스킬