Appwrite 개발
중요 규칙
- 공식 SDK 패키지만 사용 — Dart/Flutter/TypeScript/Python은 sdk-routing을 따라야 합니다. SDK가 엔드포인트를 지원하지 않거나 격리되고 테스트된
Client.call이 SDK 모델 파싱을 우회하는 경우가 아니라면,fetch,requests,dio,package:http,curl등을 통한 원시 REST/GraphQL HTTP 사용은 위반입니다. - 대상 환경별 SDK 고정 — Cloud: 최신 안정 SDK. 자체 호스팅
1.9.x:dart_appwrite25.1.0, Flutterappwrite25.2.0,node-appwrite26.2.0, 웹appwrite26.1.0, Pythonappwrite21.0.0, CLI 22.4.0. - TablesDB API 사용 — Collections API는 1.8.0부터 사용 중단(deprecated)
- 모든 고유 ID에
ID.unique()사용 — Row ID(rowId:), 파일 ID, 사용자 ID, 팀 ID, 웹훅 ID, 메시지 ID, 구독자 ID, 그리고 열(column)의 엔티티 ID. 하드코딩된 고유 ID, 사용자 정의 생성기, 이름, 타임스탬프, 또는 slug를 ID로 사용하지 마세요. 열 제한을 초과하고 데이터를 유출합니다. 인덱싱된 열로만 안정적인 자연 키를 사용하세요. Query.select()사용 — 관계는 명시적 선택 없이 ID만 반환합니다.- Cursor 페이지네이션 사용 — Offset은 대규모 테이블에서 성능이 저하됩니다.
- 카운터에는 Operator 사용 — 경쟁 조건을 방지합니다.
- 인덱스 생성 — 쿼리 없이 인덱스가 없으면 전체 테이블을 스캔합니다.
- 핸들러 외부에서 초기화 — SDK/연결은 웜 호출 간에 유지됩니다.
- 도메인별로 함수 그룹화 — 작업별 하나가 아닌 도메인별 하나의 함수
- 폴링보다 이벤트 트리거 — 하나의 트리거가 수천 개의 요청을 대체합니다.
- 명시적 문자열 유형 사용 —
string은 사용 중단됨;varchar또는text/mediumtext/longtext를 사용하세요. appwrite generate사용 — 스키마로부터 유형 안전 SDK 생성- Channel 헬퍼 사용 — 원시 문자열이 아닌 유형 안전 실시간 구독
- 실시간 쿼리 사용 — 클라이언트 측이 아닌 서버 측 이벤트 필터링
- 장기 실행 함수는 비동기 시작 — 삭제/동기화/가져오기/내보내기/마이그레이션/생성 흐름에 대한
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+)
| 구 버전 | 새 버전 |
|---|---|
| Collections | Tables |
| Documents | Rows |
| Attributes | Columns |
| Databases | TablesDB |
설정
패키지 정책:
- 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
열 유형
| 유형 | 최대 문자 | 인덱싱 | 사용 |
|---|---|---|---|
varchar | 16,383 | 전체 (크기 < 768이면) | 쿼리 가능한 짧은 문자열 |
text | 16,383 | 접두사만 | 설명, 메모 |
mediumtext | 4,194,303 | 접두사만 | 기사 |
longtext | 1,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: false | COUNT 스캔 제거 |
| 인덱스 | 대규모 테이블에서 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() | 경쟁 조건 |
| 큰 offset | Query.cursorAfter(id) | O(n) 대 O(1) |
| 합계 건너뛰기 | total: false | COUNT 스캔 제거 |
| 인덱스 누락 | 쿼리된 열에 대해 생성 | 쿼리가 전체 테이블 스캔 |
| 핸들러 내부 SDK 초기화 | 웜 재사용을 위해 외부에서 초기화 | 각 호출마다 반복 설정 |
| 하드코딩된 비밀 | 환경 변수 | 보안 위험 |
| 폴링 | 실시간 또는 이벤트 트리거 | 낭비되는 실행 |
| 클라이언트 측 필터링 | 실시간 쿼리 | 서버가 작업 수행 |
| 원시 채널 문자열 | Channel 헬퍼 | 오타, 자동 완성 없음 |
ColumnString | ColumnVarchar 또는 ColumnText | string 사용 중단 |
| 수동 유형 작성 | appwrite generate | 스키마 드리프트, 자동 완성 없음 |
databases.listDocuments() | tablesDB.listRows() | 사용 중단된 API |
원시 Appwrite HTTP (fetch, requests, dio, package:http, curl) | 공식 SDK 패키지 | 버전 드리프트, 인증 오류, 손실된 유형 API |
| 사용자 정의/하드코딩된 고유 ID | ID.unique() | 오버플로 위험, 정보 유출, 충돌 |
| 모든 동기화마다 전체 재가져오기 | Query.updatedAfter() + 테이블별 타임스탬프 | 대역폭 낭비, 느림 |
createRow() 루프 | createRows() 대량 | N개 요청 대 1개 |
비용 최적화
Query.select()— 대역폭 감소- Cursor 페이지네이션 +
total: false— 가장 빠른 쿼리 - 폴링보다 실시간 — 반복 호출 대신 단일 연결
- B
…