PocketBase Schema and Migration

Create PocketBase schema changes that are accurate, reproducible, and safe to review.

The Job

1. Inspect the current PocketBase state before proposing code.
2. Translate the request into a declarative change spec.
3. Analyze data, rule, relation, and rollback impact.
4. Split changes into the smallest practical migration units.
5. Generate migration code only after the spec is clear.
6. Verify the result against snapshots, history, and expected behavior.

The goal is not to produce plausible-looking JavaScript. The goal is to produce a verifiable PocketBase change.

Core Rules

• Never guess collection names, field names, relation targets, or rule state.
• Do not treat auth, base, and view collections as interchangeable.
• Always distinguish single relation from multi relation.
• Do not blame rule or access issues on the client until rules are checked.
• Produce a change spec before producing a migration.
• Keep one migration focused on one clear change.
• Treat importCollections(..., true) and any deleteMissing=true behavior as destructive by default.
• Always include pre-change verification and post-change verification.
• Always state rollback expectations, even when rollback is partial or risky.
• If the current state is unclear, stop and ask for the missing facts instead of fabricating code.

PocketBase Facts

• PocketBase JavaScript migrations live in pb_migrations and use a single migrate(upFunc, downFunc) call.
• Unapplied migrations run automatically on serve and can be applied manually with migrate up.
• migrate down [number] reverts the most recent applied migrations.
• migrate collections generates a snapshot migration for the current collection state.
• Snapshot imports preserve missing collections and fields by default, but become destructive if deleteMissing=true or equivalent is enabled.
• Manual migrate up or migrate down operations can require a serve restart to refresh cached collection state.
• Migration history is stored in _migrations, so history and file state can drift and must be checked together.

Workflow

1. Inspect

Confirm as many of the following as possible before proposing a change:

• PocketBase version
• collection list and collection types
• field list and field options
• relation targets and cardinality
• indexes and uniqueness requirements
• list, view, create, update, and delete rules
• auth-specific settings when relevant
• existing migration files and _migrations history state

2. Normalize

Convert the request into a declarative change spec using the template in templates/change-spec.json.

Typical operations:

• create_collection
• update_collection_meta
• add_field
• update_field
• add_relation
• add_index
• update_rules
• import_snapshot
• review_existing_migration

3. Analyze Impact

Evaluate:

• data compatibility
• relation integrity
• index validity
• rule behavior
• auth behavior
• rollback feasibility
• destructive risk
• migration history implications

4. Minimize

Prefer multiple small migrations over one large migration when the changes have different risk profiles or rollback semantics.

5. Propose

Before code, provide:

• problem summary
• confirmed facts
• missing facts
• change spec
• impact summary
• migration split proposal
• verification plan
• risk and rollback memo

6. Generate

Generate migration code only when the spec is sufficiently grounded in the current state or a verified fixture.

7. Verify

Every answer should include or reference checks for:

• before-state capture
• after-state snapshot or schema confirmation
• relation and rule validation
• rollback or downgrade behavior
• _migrations history consistency

Output Format

Use this order in substantive responses:

1. Problem summary
2. Confirmed facts
3. Missing facts
4. Proposed change spec
5. Expected impact
6. Migration split
7. Verification steps
8. Risk and rollback notes

For migration review tasks, keep the same structure and make findings and risks explicit before suggesting code changes.

Migration Writing Rules

• Write migrations from verified state, not intuition.
• Keep one migration file scoped to one intent.
• Prefer explicit up and down blocks.
• If a change is destructive, label it clearly.
• Do not default to destructive snapshot import behavior.
• Treat the generated migration as incomplete until its resulting state is verified.

Validation Checklist

Before finalizing a change, confirm:

• collection type is correct
• field type and options are correct
• relation target exists
• relation cardinality is correct
• required, hidden, presentable, and uniqueness expectations are explicit
• index definitions reference real fields
• rule changes are intentional
• existing data can survive the change
• rollback expectations are stated
• migrate collections can be used to compare expected state when applicable
• _migrations history is not being ignored

When Uncertain

Do not generate migration code.

Instead provide:

• what is uncertain
• what state must be checked
• the safest minimal change that can still be proposed
• the next verification step

Supporting Files

• Required:
  • templates/change-spec.json
  • templates/migration.js.txt
  • checklists/schema-change.md
  • checklists/relation-change.md
  • checklists/destructive-change.md
  • checklists/migration-verify.md
  • decisions/001-migration-first.md
  • decisions/002-no-guessing.md
  • decisions/003-small-migrations.md
• Optional reference:
  • patterns/collections.md
  • patterns/relations.md
  • patterns/constraints-and-rules.md
  • examples/01-add-base-collection.md
  • examples/02-add-relation-single.md
  • examples/07-dangerous-change.md
• Maintenance only:
  • fixtures/

Recommended Read Order

1. Read SKILL.md.
2. Fill templates/change-spec.json.
3. Run the relevant checklist.
4. Consult one optional pattern or example if needed.
5. Use fixtures/ only when you need a verified schema baseline for maintenance or deeper validation.

Style

• Be explicit.
• Do not soften risk language.
• Prefer current-state evidence over convenience.
• Prefer minimal, reviewable changes over broad rewrites.