ray
47 lines
2.2 KiB
Markdown
47 lines
2.2 KiB
Markdown
# PB Migration Sequencing Pitfalls (Subagent-Driven Development)
|
|
|
|
## The Problem
|
|
|
|
When a plan involves creating/updating PocketBase collections AND frontend UI in the same batch, the frontend code inevitably references the new collection name. If the PB migration hasn't been applied yet, the frontend will:
|
|
- Type-check fine (no compile-time dependency on PB schema)
|
|
- Build fine (no import dependency)
|
|
- **Crash at runtime** with "Missing collection" errors
|
|
|
|
## When This Happens
|
|
|
|
The standard batch-parallel pattern (`delegate_task` with independent goals) is susceptible because:
|
|
1. Subagent A creates `pb_migrations/M25_new_collection.js`
|
|
2. Subagent B writes `pb.collection('newCollection').getList(...)` in a UI component
|
|
3. Both execute in parallel — neither knows about the other
|
|
4. The PB migration still needs to be `docker cp`'d and `migrate up` applied
|
|
5. The frontend code is deployed, but the collection doesn't exist in PB yet
|
|
|
|
## Mitigation Strategy
|
|
|
|
**For the agent orchestrating the batch:**
|
|
|
|
- **Deploy PB migrations BEFORE dispatching frontend subagents.** Wrap the sequence as:
|
|
1. Write all PB migration files
|
|
2. Copy to container and `migrate up`
|
|
3. Verify success with `docker exec` / `--dir` check
|
|
4. THEN dispatch frontend subagents
|
|
|
|
- **If forced to parallelize** (e.g., PB and frontend for different features are interleaved), add a guard in the frontend subagent's context: "The collection [name] already exists in PB — query it directly." Verify the collection exists first with a curl health check before dispatching.
|
|
|
|
- **For deployment safety**, add a try/catch around PB queries in new frontend code:
|
|
```typescript
|
|
try {
|
|
const records = await pb.collection('newCollection').getFullList({...});
|
|
} catch (err) {
|
|
console.warn('[newCollection] not available yet');
|
|
return [];
|
|
}
|
|
```
|
|
|
|
## Why This Is Tricky
|
|
|
|
Unlike module imports (which fail at build time), PB collection references are runtime API calls. The JS bundler doesn't know about them. In the SPQ-v2 project:
|
|
- All PB queries go through `pb.collection('name').method()`
|
|
- The collection name is a runtime string — no compile-time validation
|
|
- Missing collections produce a `404` response from PB, which the frontend may or may not handle gracefully
|