appwrite-ctl

Appwrite Ctl

A Node.js (ESM) package to manage Appwrite infrastructure via Version Snapshots. Uses the Appwrite CLI for schema pull/push operations and the Appwrite SDK for data migration scripts.

Features

• Version Control for Appwrite Schema: Manage your appwrite.config.json snapshots alongside your code.
• CLI-based Snapshots: Uses appwrite-cli pull/push for reliable schema synchronization.
• Data Migrations: Execute TypeScript or JavaScript migration scripts (up and down) using the Node.js SDK.
• State Management: Tracks applied migrations in a dedicated Appwrite collection (system.migrations).
• Backup Hooks: Supports executing external backup commands before migration.
• Attribute Polling: Ensures schema attributes are available before running data scripts.

Installation

npm install -g appwrite-ctl
# or
npm install --save-dev appwrite-ctl

From Repository

npm install github:bfbechlin/appwrite-ctl

Prerequisites

• Node.js: v18 or higher.
• Appwrite CLI: Installed globally (npm install -g appwrite-cli). The tool configures the CLI automatically using API key — no interactive login required.
• Environment Variables:

APPWRITE_ENDPOINT=https://cloud.appwrite.io/v1
APPWRITE_PROJECT_ID=your_project_id
APPWRITE_API_KEY=your_api_key
BACKUP_COMMAND="docker exec appwrite-mariadb mysqldump ..." # Optional

Architecture

The tool uses a clear separation of concerns:

Operation	Tool	Why
Schema snapshots (pull/push)	Appwrite CLI	Has full serialization/deserialization of schemas via appwrite.config.json
Data migrations (up/down)	Appwrite SDK	Provides programmatic access to databases, documents, etc.
Migration tracking	Appwrite SDK	Creates/reads documents in the system.migrations collection

CLI Usage

# Default (uses .env)
npx appwrite-ctl migrations run

# Custom environment file
npx appwrite-ctl migrations run --env .env.prod

Quick Start

1. Initialize the Project

npx appwrite-ctl init

Creates:

• appwrite/migration/ directory
• appwrite/migration/config.json configuration file

2. Setup System Collection

npx appwrite-ctl migrations setup

3. Create a Migration

npx appwrite-ctl migrations create

This command:

• Creates appwrite/migration/vN/ (auto-increments version).
• Generates an index.ts file with a boilerplate migration script.
• Copies the current appwrite.config.json from the project root (or pulls from Appwrite via CLI if no local snapshot exists).

Folder Structure:

/appwrite
  schema.md                    <-- Generated by `docs` command
  /migration
    config.json
    /v1
      index.ts                 <-- Migration logic (SDK)
      appwrite.config.json     <-- Schema snapshot (CLI format)
      schema.md                <-- Auto-generated on create/update
    /v2
      index.ts
      appwrite.config.json
      schema.md

4. Edit Migration Logic

import { Migration } from 'appwrite-ctl';

const migration: Migration = {
  id: 'uuid-generated-id',
  description: 'Update finance schema',
  requiresBackup: true,

  up: async ({ client, databases, log }) => {
    log('Seeding initial data...');
    await databases.createDocument('db', 'users', 'unique()', {
      name: 'Admin',
      role: 'admin',
    });
  },

  down: async ({ client, databases, log }) => {
    // Logic to revert changes
  },
};

export default migration;

5. Update a Snapshot

After making schema changes in the Appwrite console, update a migration version's snapshot:

npx appwrite-ctl migrations update v1

This pulls the current state from Appwrite via CLI and saves it as the version's appwrite.config.json.

6. Run Migrations

npx appwrite-ctl migrations run

The runner performs these steps for each pending version:

• Configure CLI: Sets endpoint, project-id, and API key on appwrite-cli.
• Backup: Runs BACKUP_COMMAND if requiresBackup is true.
• Schema Push: Pushes the version's appwrite.config.json via CLI (settings, tables, buckets, teams, topics).
• Polling: Waits for all schema attributes to become available (via SDK).
• Execution: Runs the up function defined in index.ts (via SDK).
• Finalization: Records the migration as applied.

7. Check Status

npx appwrite-ctl migrations status

8. Generate Schema Docs

# Generate from latest version → appwrite/schema.md
npx appwrite-ctl migrations docs

# Generate from a specific version
npx appwrite-ctl migrations docs v1

Generates a Markdown file with:

• ER diagrams (Mermaid) for each database (system database excluded)
• Collection details: columns, types, defaults, indexes, permissions, relationships
• Buckets: storage configuration summary

Note: Schema docs are also auto-generated inside the version folder (vN/schema.md) when running migrations create or migrations update.

Configuration (appwrite/migration/config.json)

{
  "collection": "migrations",
  "database": "system"
}

CI/CD & Automated Deployment

• Install Appwrite CLI: npm install -g appwrite-cli
• Set environment variables: APPWRITE_ENDPOINT, APPWRITE_PROJECT_ID, APPWRITE_API_KEY
• The tool automatically configures the CLI via appwrite client --key — no login required.

Required API Key Scopes:

• collections.read, collections.write
• documents.read, documents.write
• attributes.read, attributes.write
• indexes.read, indexes.write

CLI Commands

Command	Description
init	Initialize the project folder structure and config.
migrations setup	Create the system database and migrations collection.
migrations create	Create a new migration version pulling the latest snapshot from Appwrite via CLI.
migrations update <version>	Update a version's snapshot by pulling from Appwrite via CLI.
migrations run	Execute all pending migrations in order.
migrations status	List applied and pending migrations.
migrations docs	Pull current schema state from Appwrite and generate documentation with ER diagrams.

AI Rules

Understanding the Data Models Layer

📌 schema.md — The Source of Truth

The most important file for understanding the application's data model is:

appwrite/schema.md

This is an auto-generated Markdown file that documents the current state of every database, collection, attribute, relationship, index, and storage bucket in the Appwrite project. It is generated from the latest appwrite.config.json snapshot via the migrations docs command.

When you need to understand the data model — always read appwrite/schema.md first.

It contains:

• ER Diagrams (Mermaid) — visual representation of collection relationships per database.
• Collections — complete list of every collection with:
  • Column names, types, required flags, defaults, and constraints.
  • Relationships: type (oneToMany, manyToOne, etc.), related collection, on-delete behavior, and two-way configuration.
  • Indexes: type (unique, key, fulltext), columns, and sort orders.
  • Permissions: read/write/create/delete access rules.
• Buckets — storage buckets with max file size, extensions, compression, encryption, and antivirus settings.

Migration Commands

This project uses appwrite-ctl to manage schema migrations. The available commands are:

Command	Description
appwrite-ctl migrations create	Create a new migration version pulling the latest snapshot from Appwrite via CLI.
appwrite-ctl migrations update <version>	Pull the current Appwrite state and update a version's snapshot.
appwrite-ctl migrations run	Execute all pending migrations in order (push schema → poll attributes → run script).
appwrite-ctl migrations status	List applied and pending migrations.
appwrite-ctl migrations docs	Pull current schema state from Appwrite and generate/regenerate schema.md.

Each migration version lives in appwrite/migration/vN/ and contains:

• appwrite.config.json — the schema snapshot (Appwrite CLI format).
• index.ts — the migration script with up (and optional down) functions.
• schema.md — auto-generated docs for that version's snapshot.

How to Handle Data Model Changes

When a change to the data model is needed (e.g. adding a collection, modifying attributes, creating indexes), follow these steps:

• Create a new migration version:

  npx appwrite-ctl migrations create
  

  This creates appwrite/migration/vN/ and automatically pulls the current schema snapshot from Appwrite into appwrite.config.json via the CLI.

• Edit the snapshot (appwrite.config.json) inside the new version folder. Apply the desired schema changes directly to this JSON file — add/remove/modify collections, attributes, indexes, relationships, or buckets.

• Write the migration script in appwrite/migration/vN/index.ts if data manipulation is needed (e.g. seeding data, transforming existing documents). If the change is schema-only, the default empty up function is sufficient.

• Regenerate the schema docs:

  npx appwrite-ctl migrations docs
  

  This updates both appwrite/migration/vN/schema.md and the root appwrite/schema.md.

• Verify the updated appwrite/schema.md to confirm the changes are correct.

⚠️ Never edit schema.md files manually — they are auto-generated. Always modify the appwrite.config.json snapshot and run migrations docs to regenerate.