> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nometria.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Appwrite Migrate

> Schema-driven migration runner for Appwrite — the missing prisma migrate for Appwrite projects.

`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.

<CardGroup cols={2}>
  <Card title="GitHub" icon="github" href="https://github.com/nometria/appwrite-migrate">
    nometria/appwrite-migrate
  </Card>

  <Card title="npm" icon="npm" href="https://www.npmjs.com/package/@nometria-ai/appwrite-migrate">
    @nometria-ai/appwrite-migrate
  </Card>
</CardGroup>

## Install

```bash theme={null}
# 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:**

```bash theme={null}
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/`:

```json theme={null}
// 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

```bash theme={null}
# 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 type              | Appwrite attribute | Notes                        |
| ---------------------- | ------------------ | ---------------------------- |
| `string`               | String             | `maxLength` required         |
| `integer`              | Integer            | Optional `minimum`/`maximum` |
| `float`                | Float              | Optional `minimum`/`maximum` |
| `boolean`              | Boolean            | Optional `default`           |
| `array` (string items) | String array       | Native Appwrite array        |
| `object`               | JSON object        | Stored 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.

```json theme={null}
// .appwrite-migrations.json (auto-generated)
{
  "applied": ["Task", "User", "Comment"],
  "lastRun": "2025-01-15T10:30:00Z"
}
```

<Note>This tool is particularly useful for apps migrated from Base44, which uses Appwrite as its default backend.</Note>