# Migrating Appwrite to Code: The Complete Playbook (2026)

- Tool: No-Code to Code Migrations
- Last updated: July 2026

## TL;DR

Appwrite is a capable, BSD-3-Clause open-source BaaS with a genuine self-host path. Teams migrate when relational data needs exceed the document model, or when Cloud Scale pricing ($599/mo for SOC 2) is disproportionate versus Supabase Pro at $25/mo. The built-in Migrations tool handles most data portability. The document-to-relational schema redesign is the intellectually demanding step — budget 6–10 weeks.

## Platform status

- Status: active — BSD-3-Clause (permissive open source). Cloud tiers: Pro ($15/mo/member), Scale ($599/mo with SOC 2). Self-host via Docker Compose or Kubernetes — full-featured at zero license cost. Added Sites (static hosting), Messaging, and 15 function runtimes in 2026. Built-in Migrations tool for cloud↔self-host data moves.
- Migration urgency: low
- Typical timeline: 6–10 weeks
- Typical cost: $13K–$25K (agency, fixed)

## Why migrate

Appwrite is a capable platform with a genuine self-host option and a strong Firebase-alternative story. Teams migrate when relational data requirements outgrow the document model, or when Cloud pricing for compliance tiers becomes a mismatch.

- **Document DB architecture ceiling for relational workloads** — Appwrite uses a document-style database — not relational SQL. Teams that need complex joins, foreign-key relationships, or multi-table transactions hit the conceptual ceiling quickly and end up fighting the API to express patterns it wasn't designed for.
- **Cloud Scale tier is $599/mo for SOC 2** — SOC 2 compliance requires the Scale tier at $599/mo. Supabase Pro offers managed PostgreSQL with a comparable compliance posture at $25/mo. For workloads that primarily need compliance, the cost delta is significant.
- **Function runtime diversity creates migration overhead** — Appwrite supports 15 function runtimes (Node.js, Python, PHP, Ruby, Swift, Kotlin, Dart, and more). Functions are not portable between runtimes without rewrite; a multi-runtime backend adds complexity to any future migration.
- **No SQL query access** — Appwrite's database API is document-centric. Complex filtering requires multiple API calls or data denormalization. If your app needs SQL queries, views, or stored procedures, Appwrite does not expose that layer.
- **Self-host migration wizard can stall on large datasets** — The built-in Migrations tool has been reported to get stuck on large database or storage migrations (anecdotal, Appwrite Discord threads 2026). A manual MariaDB dump fallback should be prepared alongside the tool-based approach.

## What you can export

Appwrite's data portability is better than most document-DB BaaS platforms — the built-in Migrations tool covers accounts, databases, files, and functions. The document-to-relational schema redesign is where the real migration work lives.

| Asset | Exportable | How |
| --- | --- | --- |
| Data | yes | Built-in Migrations tool (appwrite.io/docs/advanced/migrations) exports databases, rows, and files; moves cloud↔self-host and between Appwrite instances. Manual backup: Docker volumes + MariaDB dump (community-documented, Appwrite Discord 2026). |
| Code (Appwrite Functions) | partial | BSD-3-Clause license; self-host is fully featured. Your Appwrite Functions (your code in Node.js, Deno, Python, PHP, etc.) are yours and portable. The Appwrite backend engine is not portable. |
| Design/UI | no | Appwrite is a backend service. Your frontend application is separate code you own and is not affected by this migration. |
| Logic/Workflows (Functions) | partial | Appwrite Functions triggered by events, schedules, or HTTP — your code is portable to Edge Functions or Lambda. Appwrite-specific SDK calls within functions need systematic replacement. |
| Users & Auth | partial | Auth includes email/password, OAuth2, phone, MFA. User records export via the Migrations tool or Docker volume backup. Included in the Migrations tool's accounts export. |
| File Storage | yes | File metadata and files are included in the Migrations tool export. Manual alternative: copy Docker volumes for self-hosted storage. |

## Stack mapping

The target stack is Next.js (App Router) + Supabase (PostgreSQL). The key architectural decision is the document-to-relational schema mapping — this happens before any data moves.

| Platform concept | Code equivalent |
| --- | --- |
| Appwrite Collections (document DB) | Supabase / PostgreSQL tables (relational schema) |
| Appwrite Documents (JSON documents) | SQL rows; nested JSON fields → PostgreSQL JSONB columns or normalized child tables |
| Appwrite Functions (Node.js, Deno, Python, etc.) | Supabase Edge Functions (Deno) or Next.js API Routes |
| Appwrite Auth (email/OAuth2/phone/MFA) | Supabase Auth |
| Appwrite Storage (buckets) | Supabase Storage or S3/R2 |
| Appwrite Realtime (channel subscriptions) | Supabase Realtime (WebSockets) |
| Appwrite Messaging (email/SMS/push) | Resend (email), Twilio (SMS), integrated via Edge Functions |
| Appwrite Teams and RBAC | Supabase Auth + PostgreSQL RLS policies |

## Migration roadmap

A 6–10 week migration where the document-to-relational schema design is the most intellectually demanding step. Do not start data migration before schema decisions are finalized.

### Phase 1: Audit & Export (3–5 days)

- Run Appwrite Migrations export — moves accounts, databases, files, functions to backup or self-hosted instance
- Manually back up Docker volumes and MariaDB dump if self-hosted — don't rely only on the Migrations tool
- Document every Collection and its full nested field structure
- Inventory all Appwrite Functions: runtime, trigger type (HTTP/event/schedule), and which Appwrite SDK methods they call
- Catalog all Realtime channels in use and their client-side subscription handlers

> Watch out: The Migrations tool has been reported to stall on large DB or storage migrations. Test it on a copy first and have a manual MariaDB dump ready as fallback.

### Phase 2: Schema Design (1–2 weeks)

- Map every Collection field to a PostgreSQL DDL decision: flat attribute → column, nested object → JSONB or child table, array → junction table
- Write sample schema migration scripts and validate against representative documents
- Design Supabase RLS policies to replace Appwrite's Teams/RBAC model
- Confirm which nested structures benefit from normalization vs JSONB storage (query patterns drive this decision)

> Watch out: Do not begin data migration until schema decisions are finalized. Retrofitting normalization decisions after bulk import multiplies work.

### Phase 3: Data Migration (1–2 weeks)

- Run MariaDB → PostgreSQL migration using the schema decisions from Phase 2
- Validate row counts and spot-check nested field conversion accuracy
- Migrate Storage files to Supabase Storage or S3/R2
- Apply RLS policies and test access patterns

### Phase 4: Function Port (1–3 weeks)

- Abstract Appwrite SDK calls behind a service layer in each function
- Replace Appwrite SDK service calls with Supabase SDK equivalents
- Port pure business logic functions directly to Deno Edge Functions or Next.js API Routes
- Replace Appwrite Messaging calls with Resend (email) or Twilio (SMS)

> Watch out: Functions that call Appwrite Teams, Messaging, or document-style database APIs require the most rewrite work. Identify these first and scope them separately.

### Phase 5: Auth, Realtime & Cutover (1 week)

- Import user records via Migrations tool export to Supabase Auth
- Prepare forced password-reset campaign (hashes not documented as exportable)
- Update client-side Realtime subscriptions to Supabase channel API
- Parallel run: verify parity on all API endpoints, switch DNS, deprecate Appwrite instance

## Cost paths

| Path | Cost | Timeline | Fits |
| --- | --- | --- | --- |
| DIY (self-directed with AI tools) | $0–500 + time | 3–6 months part-time | Developers with SQL experience who can design and validate the document-to-relational schema migration. Best for backends with simple, flat Collections and fewer than 10 Functions. |
| Freelancer | $4K–10K | 6–10 weeks | Teams with moderate Collection complexity (under 20 collections, primarily flat documents) and an internal developer available to own the Supabase schema going forward. |
| Agency (RapidDev) | $13K–25K fixed | 6–10 weeks | Teams with complex nested document structures, multi-runtime function backends, or compliance requirements where the document-to-relational schema design needs expert SQL modeling and validated RLS policies. |

## Risks and mitigations

- **Document-to-SQL schema mismatch introduces data loss or corruption** — Map every Collection field to a PostgreSQL DDL decision before writing migration scripts. Validate with a representative sample of real documents before bulk import — type mismatches and missing fields surface here, not in production.
- **Appwrite Migrations tool stalls on large DB or storage migrations** — Test the Migrations tool on a copy of your production data before running against live data. Prepare a manual MariaDB dump + storage volume backup as a parallel fallback — don't depend on the tool alone.
- **Function SDK dependencies require systematic replacement** — Functions that call Appwrite SDK methods (Databases, Users, Teams, Messaging) need every SDK call replaced. Abstract the Appwrite SDK behind a service layer first, then replace service-by-service — this is safer than replacing calls in-place across all functions.
- **Realtime subscription API differences break client-side behavior** — Document all active Realtime channels and their client-side subscription handlers before migration. Appwrite and Supabase Realtime have similar concepts but different API surfaces — update client code in a staging environment before cutover.

## Stay or go

Stay if:

- Your app is genuinely document-oriented — content, events, activity logs — and the document collection API is ergonomic for your actual access patterns.
- You need a multi-runtime backend (Python, Ruby, Swift, Kotlin, Dart functions) and your team works in multiple languages — Appwrite's 15 runtimes is a genuine differentiator.
- You're self-hosting under BSD-3-Clause with full features at zero license cost — Appwrite self-host is complete and free, and the open-source license is genuinely permissive.
- Your data model is simple and flat — few nested documents, no complex joins — making the document API an acceptable abstraction.

Go if:

- Your data model is relational and you're fighting the document API to express joins and foreign keys — this is the most honest migration trigger.
- Cloud Scale pricing ($599/mo for SOC 2) is disproportionate to your workload when Supabase Pro serves the same compliance requirement at $25/mo.
- You need complex SQL queries, views, or stored procedures — Appwrite does not expose SQL access.

Appwrite is a capable open-source BaaS. The self-host path under BSD-3-Clause is genuinely compelling for teams that want maximum ownership without a license cost. Migrate when relational data needs or Cloud pricing mismatch become blockers — not to switch platforms for its own sake.

## Migration checklist

- Run Appwrite Migrations export today — The built-in Migrations tool exports accounts, databases, rows, files, and function code. Running it now creates a complete backup before any migration work begins.
- Manually back up Docker volumes and MariaDB dump if self-hosted — The Migrations tool has reported stalls on large datasets. A manual dump is your fallback and should exist independently of any automated export.
- Document every Collection and its full nested field structure — This is the schema migration map. Every nested object and array field requires an explicit PostgreSQL DDL decision — this document drives Phase 2.
- Inventory all Appwrite Functions: runtime, trigger type, and Appwrite SDK calls — Functions that call Appwrite-specific SDK methods need systematic replacement. Knowing which functions depend on Teams, Messaging, or document DB APIs sizes the function-port phase.
- List all Storage buckets and file counts — Total file count and size determines which storage migration method to use and how long it will take.
- Catalog all Realtime channels and their client-side subscription handlers — Appwrite and Supabase Realtime have different channel APIs. Each subscription handler needs updating — missing one causes silent UI breakage after cutover.
- Check all Functions that use Appwrite Messaging or Teams — Messaging (email/SMS/push) and Teams (RBAC) require replacement services (Resend, Twilio, Supabase Auth + RLS). Identifying these early prevents late-stage scope surprises.

## Frequently asked questions

### Can I export my Appwrite data?

Yes. Appwrite's built-in Migrations tool exports accounts, databases, rows, files, and function code. For self-hosted instances, you can also back up Docker volumes and the MariaDB database directly. Test the tool on a copy first — it has been reported to stall on large datasets; have a manual MariaDB dump as a fallback.

### Is Appwrite shutting down?

No. Appwrite is an actively maintained, BSD-3-Clause open-source project with Cloud and self-host tiers, updated in 2026 with Sites, Messaging, and 15 function runtimes. The migration case is about relational data needs and Cloud pricing — not platform survival.

### How long does an Appwrite migration take?

Typically 6–10 weeks. The document-to-relational schema design is the most time-consuming step — a complex backend with deeply nested document structures can need 1–2 weeks just to map the schema correctly. Simple, flat-document backends complete faster.

### What happens to my users' passwords during migration?

Password hash export from Appwrite is not documented. Plan a forced password reset for all users when migrating to Supabase Auth. Export user email addresses via the Migrations tool and prepare magic-link or reset emails to send at cutover.

### Can I migrate my Appwrite Functions to Supabase Edge Functions?

Partially. Your function code is yours and portable under the BSD-3-Clause license. Functions written in Node.js or Deno port most directly to Supabase Edge Functions. The challenge is Appwrite SDK calls within functions — methods that call Appwrite Databases, Teams, or Messaging APIs need systematic replacement with Supabase SDK equivalents. Abstract the SDK behind a service layer before replacing calls.

### What is the document-to-relational schema migration and why is it hard?

Appwrite stores data as JSON documents in collections. PostgreSQL stores data in relational tables with typed columns. Every nested object in an Appwrite document requires a design decision: flatten it into columns, store it in a JSONB column, or normalize it into a child table. Arrays require junction tables. These decisions affect query performance, RLS policy design, and application code — getting them wrong before bulk data import means re-doing the work.

### What's the target stack after migrating from Appwrite?

Next.js (App Router) + Supabase (PostgreSQL) is the standard target. Appwrite Collections map to Supabase tables after schema redesign; Appwrite Functions port to Supabase Edge Functions or Next.js API Routes; Appwrite Auth migrates to Supabase Auth; Storage moves to Supabase Storage or S3/R2; Appwrite Realtime maps to Supabase Realtime.

### How much does an Appwrite migration cost if I hire an agency?

RapidDev offers fixed-price Appwrite migrations at $13K–$25K over 6–10 weeks, covering schema design, data migration, function porting, auth migration, storage transfer, and cutover. The document-to-relational schema design is the most complex step — a free scoping call at rapidevelopers.com sizes the schema work before you commit.

---

Source: https://www.rapidevelopers.com/no-code-to-code/how-to-migrate-appwrite-project-to-code
© RapidDev — https://www.rapidevelopers.com/no-code-to-code/how-to-migrate-appwrite-project-to-code