Skip to main content
appwrite-migrate is a schema-driven migration runner for Appwrite. It creates collections from JSON Entity schemas, handles all attribute types, seeds data, and tracks applied migrations idempotently — safe to run on every deploy.

GitHub

nometria/appwrite-migrate

npm

@nometria-ai/appwrite-migrate

​
Install

# Run without installing
npx appwrite-migrate

# Install globally
npm install -g @nometria-ai/appwrite-migrate

# Or as a dev dependency
npm install --save-dev @nometria-ai/appwrite-migrate

​
Setup

1. Add environment variables: 
APPWRITE_ENDPOINT=https://cloud.appwrite.io/v1
APPWRITE_PROJECT_ID=your-project-id
APPWRITE_API_KEY=your-api-key         # requires collections.write scope
APPWRITE_DATABASE_ID=main
2. Place Entity schemas in src/Entities/: 
// src/Entities/Task.json
{
  "properties": {
    "title":     { "type": "string",  "maxLength": 500 },
    "body":      { "type": "string",  "maxLength": 5000 },
    "completed": { "type": "boolean", "default": false },
    "priority":  { "type": "integer", "minimum": 1, "maximum": 10 },
    "score":     { "type": "float",   "minimum": 0.0, "maximum": 100.0 },
    "tags":      { "type": "array",   "items": { "type": "string" } },
    "meta":      { "type": "object" }
  }
}

​
Usage

# Run migrations (creates/updates collections)
npx appwrite-migrate

# Validate without writing anything
npx appwrite-migrate --dry-run

# Seed data from a JSON file
npx appwrite-migrate --seed ./seed-data.json

# Point to a custom entity directory
npx appwrite-migrate --entities ./models

​
Supported attribute types

JSON typeAppwrite attributeNotes
stringStringmaxLength required
integerIntegerOptional minimum/maximum
floatFloatOptional minimum/maximum
booleanBooleanOptional default
array (string items)String arrayNative Appwrite array
objectJSON objectStored as string

​
Migration tracking

Each migration run is tracked idempotently — re-running the same migration is a no-op. Safe to include in your CI/CD deploy step. 
// .appwrite-migrations.json (auto-generated)
{
  "applied": ["Task", "User", "Comment"],
  "lastRun": "2025-01-15T10:30:00Z"
}
This tool is particularly useful for apps migrated from Base44, which uses Appwrite as its default backend.