---
title: Write JSVM Migrations as pb_migrations/*.js Files
impact: HIGH
impactDescription: JSVM migrations look different from Go ones; missing the timestamp prefix or the down-callback silently breaks replay
tags: jsvm, migrations, pb_migrations, schema, extending
---

## Write JSVM Migrations as pb_migrations/*.js Files

JSVM migrations live in `pb_migrations/` next to the executable. Unlike Go migrations (which use `init()` + `m.Register(...)` inside a package imported from `main.go`), JSVM migrations are **auto-discovered by filename** and call the global `migrate()` function with an `up` callback and an optional `down` callback. `--automigrate` is on by default in v0.36+, so admin-UI changes generate these files for you; you also write them by hand for data migrations, seed data, and index changes that the UI can't express.

**Incorrect (wrong filename format, missing down, raw SQL without cache invalidation):**

```javascript
// pb_migrations/add_audit.js   ❌ missing <unix>_ prefix - never runs
migrate((app) => {
    // ❌ Raw ALTER TABLE leaves PocketBase's internal collection cache stale
    app.db().newQuery(
        "ALTER TABLE posts ADD COLUMN summary TEXT DEFAULT ''"
    ).execute();
});
// ❌ No down callback - `migrate down` cannot revert this in dev
```

**Correct (timestamped filename, collection API, both up and down):**

```javascript
// pb_migrations/1712500000_add_audit_collection.js
/// <reference path="../pb_data/types.d.ts" />

migrate(
    // UP - runs on `serve` / `migrate up`
    (app) => {
        const collection = new Collection({
            type: "base",
            name: "audit",
            fields: [
                { name: "action", type: "text", required: true },
                { name: "actor",  type: "relation", collectionId: "_pb_users_auth_", cascadeDelete: false },
                { name: "meta",   type: "json" },
                { name: "created", type: "autodate", onCreate: true },
            ],
            indexes: [
                "CREATE INDEX idx_audit_actor ON audit (actor)",
                "CREATE INDEX idx_audit_created ON audit (created)",
            ],
        });
        app.save(collection);
    },
    // DOWN - runs on `migrate down N`
    (app) => {
        const collection = app.findCollectionByNameOrId("audit");
        app.delete(collection);
    },
);
```

**Seed data migration (common pattern):**

```javascript
// pb_migrations/1712500100_seed_default_tags.js
/// <reference path="../pb_data/types.d.ts" />

migrate(
    (app) => {
        const tags = app.findCollectionByNameOrId("tags");
        for (const name of ["urgent", "bug", "feature", "docs"]) {
            const r = new Record(tags);
            r.set("name", name);
            app.save(r); // `app` here is the transactional app - all or nothing
        }
    },
    (app) => {
        const tags = app.findCollectionByNameOrId("tags");
        for (const name of ["urgent", "bug", "feature", "docs"]) {
            const r = app.findFirstRecordByFilter(
                "tags",
                "name = {:name}",
                { name },
            );
            if (r) app.delete(r);
        }
    },
);
```

**CLI commands (same as Go migrations):**

```bash
./pocketbase migrate create "add_audit_collection"  # templated blank file
./pocketbase migrate up                              # apply pending
./pocketbase migrate down 1                          # revert last
./pocketbase migrate history-sync                    # reconcile _migrations table
```

**Rules:**
- **Filename format**: `<unix_timestamp>_<description>.js`. The timestamp sets ordering. Never renumber a committed file.
- **The `app` argument is transactional**: every migration runs inside its own transaction. Throw to roll back. Do not capture `$app` from the outer scope - use the `app` parameter so the work participates in the tx.
- **Use the collection API** (`new Collection`, `app.save(collection)`), not raw `ALTER TABLE`. Raw SQL leaves PocketBase's in-memory schema cache stale until the next restart.
- **Always write the down callback** in development. In production, down migrations are rare but the callback is what makes `migrate down 1` work during emergency rollbacks.
- **Do not import from other files** - goja has no ES modules, and at migration time the `pb_hooks` loader has not necessarily run. Keep each migration self-contained.
- **Commit `pb_migrations/` to version control**. Never commit `pb_data/`.
- **Conflicting with Go migrations**: you can run either Go or JS migrations, not a mix of both in the same project. JSVM migrations are enabled by default; Go migrations require `migratecmd.MustRegister(...)` in `main.go`.

Reference: [Extend with JavaScript - Migrations](https://pocketbase.io/docs/js-migrations/)